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 - Get the current cartridge path for a site
• add_cartridge - Add a cartridge at a specific position
• remove_cartridge - Remove a cartridge from the path
• set_cartridge_path - Replace the entire cartridge path

Usage

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

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

class CartridgePathResult

Result of a cartridge path operation.

Fields

Name	Type
site_id	str
cartridges	str
cartridge_list	list[str]

CartridgeUpdateOptions

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

class ListSitesOptions

Options for listing sites.

Fields

Name	Type	Default
count	int | None	None
start	int | None	None

OcapiSitesBackend

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

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

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

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

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

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

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

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

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 = 'Sites-Site'

CartridgePosition

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

SitesBackendConfig

SitesBackendConfig = DualBackendConfig