---
editLink: false
lastUpdated: false
outline: [2, 3]
---

<!-- Generated by python/b2c-tooling-sdk/scripts/generate_api_docs.py. Do not edit. -->

# b2c_tooling_sdk.operations.sites

Site operations for B2C Commerce instances.

Mirrors `src/operations/sites/index.ts`. Provides functions for managing
site cartridge paths on B2C Commerce instances. Operations use SCAPI first,
with temporary OCAPI and site-archive fallbacks. Business Manager
(`Sites-Site`) is supported via the import/export mechanism.

## Cartridge Path Functions

- [`get_cartridge_path`](/python/api/operations/sites#get-cartridge-path) - Get the current cartridge path for a site
- [`add_cartridge`](/python/api/operations/sites#add-cartridge) - Add a cartridge at a specific position
- [`remove_cartridge`](/python/api/operations/sites#remove-cartridge) - Remove a cartridge from the path
- [`set_cartridge_path`](/python/api/operations/sites#set-cartridge-path) - Replace the entire cartridge path

## Usage

```python
from b2c_tooling_sdk.operations.sites import get_cartridge_path, add_cartridge, set_cartridge_path
from b2c_tooling_sdk.config import resolve_config

config = resolve_config()
instance = config.create_b2c_instance()

# List cartridge path
result = await get_cartridge_path(instance, "RefArch")
print(result.cartridge_list)

# Add a cartridge
await add_cartridge(instance, "RefArch", AddCartridgeOptions(name="my_cartridge", position="first"))

# Business Manager
await add_cartridge(instance, "Sites-Site", AddCartridgeOptions(name="bm_ext", position="first"))
```
## Authentication

Cartridge path operations require OAuth authentication. For SCAPI direct
updates, grant `sfcc.sites.rw`; for OCAPI grant POST/PUT/DELETE on
`/sites/*/cartridges`. For import/export fallback, grant job execution
permissions and WebDAV write access.

## Classes

### AddCartridgeOptions {#addcartridgeoptions}

```python
class AddCartridgeOptions
```

Options for adding a cartridge to a site's cartridge path.

**Fields**

| Name | Type | Default |
| --- | --- | --- |
| `name` | `str` |  |
| `position` | `CartridgePosition` | `'first'` |
| `target` | `str \| None` | `None` |

### CartridgePathResult {#cartridgepathresult}

```python
class CartridgePathResult
```

Result of a cartridge path operation.

**Fields**

| Name | Type |
| --- | --- |
| `site_id` | `str` |
| `cartridges` | `str` |
| `cartridge_list` | `list[str]` |

### CartridgeUpdateOptions {#cartridgeupdateoptions}

```python
class CartridgeUpdateOptions
```

Options for cartridge path update operations that may run jobs.

**Fields**

| Name | Type | Default |
| --- | --- | --- |
| `log` | `Callable[[str], None] \| None` | `None` |
| `wait_options` | `WaitForJobOptions \| None` | `None` |

### ListSitesOptions {#listsitesoptions}

```python
class ListSitesOptions
```

Options for listing sites.

**Fields**

| Name | Type | Default |
| --- | --- | --- |
| `count` | `int \| None` | `None` |
| `start` | `int \| None` | `None` |

### OcapiSitesBackend {#ocapisitesbackend}

```python
class OcapiSitesBackend
```

OCAPI Sites backend (legacy/fallback). Reads sites and per-site detail via
the OCAPI Data API `/sites` resource.

**Fields**

| Name | Type |
| --- | --- |
| `name` | `Literal['ocapi']` |

### ScapiSitesBackend {#scapisitesbackend}

```python
class ScapiSitesBackend
```

SCAPI Sites backend. Reads sites and manages custom cartridge paths via the
`site/sites/v1` Admin API.

**Fields**

| Name | Type |
| --- | --- |
| `name` | `Literal['scapi']` |

### SiteInfo {#siteinfo}

```python
class SiteInfo
```

Canonical site.

CamelCase-ish fields match SCAPI; the OCAPI backend maps from snake_case.
`display_name` is the default-locale display name (both APIs return a
locale map; we surface the default for table output and keep the full
object on `raw`).

**Fields**

| Name | Type | Default |
| --- | --- | --- |
| `id` | `str` |  |
| `display_name` | `str \| None` | `None` |
| `storefront_status` | `str \| None` | `None` |
| `cartridges` | `str \| None` | `None` |
| `raw` | `Any` | `None` |

### SitesBackend {#sitesbackend}

```python
class SitesBackend(BackendBase, Protocol)
```

Backend contract for site read operations.

Cartridge-path methods model the SCAPI v1.3 custom-cartridges resource and
the equivalent OCAPI Data API resource.

## Functions

### add_cartridge {#add-cartridge}

```python
async def add_cartridge(instance: B2CInstance, site_id: str, options: AddCartridgeOptions, update_options: CartridgeUpdateOptions | None = None) -> CartridgePathResult
```

Adds a cartridge to a site's cartridge path.

For regular sites, uses the SCAPI-first Sites backend and falls back to
site archive import if neither direct backend is available. For Business
Manager (`Sites-Site`), always uses site archive import.

### create_sites_backend {#create-sites-backend}

```python
def create_sites_backend(config: SitesBackendConfig) -> SitesBackend
```

Builds a Sites backend for site and cartridge-path operations.

In `auto` mode (the default) it prefers SCAPI (`site/sites/v1`) and
falls back to the deprecated OCAPI Data API on a safe capability/auth/request
rejection.

### get_cartridge_path {#get-cartridge-path}

```python
async def get_cartridge_path(instance: B2CInstance, site_id: str) -> CartridgePathResult
```

Gets the cartridge path for a site.

Uses the configured Sites backend to read the cartridge path. Auto mode
prefers SCAPI and temporarily falls back to OCAPI. Works for all sites
including Business Manager (`Sites-Site`).

**Parameters**

| Name | Type | Description |
| --- | --- | --- |
| `instance` | `B2CInstance` | B2C instance to query. |
| `site_id` | `str` | Site ID (e.g. `"RefArch"`, `"Sites-Site"`). |

**Returns:** Cartridge path result.

### remove_cartridge {#remove-cartridge}

```python
async def remove_cartridge(instance: B2CInstance, site_id: str, cartridge_name: str, update_options: CartridgeUpdateOptions | None = None) -> CartridgePathResult
```

Removes a cartridge from a site's cartridge path.

For regular sites, uses the SCAPI-first Sites backend and falls back to
site archive import if neither direct backend is available. For Business
Manager (`Sites-Site`), always uses site archive import.

### set_cartridge_path {#set-cartridge-path}

```python
async def set_cartridge_path(instance: B2CInstance, site_id: str, cartridges: str, update_options: CartridgeUpdateOptions | None = None) -> CartridgePathResult
```

Replaces the entire cartridge path for a site.

For regular sites, uses the SCAPI-first Sites backend and falls back to
site archive import if neither direct backend is available. For Business
Manager (`Sites-Site`), always uses site archive import.

## Attributes

### BM_SITE_ID {#bm-site-id}

```python
BM_SITE_ID = 'Sites-Site'
```

### CartridgePosition {#cartridgeposition}

```python
CartridgePosition = Literal['first', 'last', 'before', 'after']
```

### SitesBackendConfig {#sitesbackendconfig}

```python
SitesBackendConfig = DualBackendConfig
```