salesforce-b2c-tooling-sdk is the Python SDK for Salesforce B2C Commerce
tooling. Import name is b2c_tooling_sdk; distribution name is
salesforce-b2c-tooling-sdk. It is async-first with a complete synchronous
facade. Python 3.10+.
This skill covers consuming the SDK. For developing the SDK itself, see
python/b2c-tooling-sdk/CLAUDE.md. For the full symbol catalog, read
references/api-catalog.md.
1. Install
Not on PyPI yet — install from git during development:
pip install "git+https://github.com/SalesforceCommerceCloud/b2c-developer-tooling.git@main#subdirectory=python/b2c-tooling-sdk"
# or pin a release tag: ...@<tag>#subdirectory=python/b2c-tooling-sdk
For notebooks also install a kernel: pip install ipykernel. Once published this
becomes pip install salesforce-b2c-tooling-sdk.
2. Async vs. sync — pick the import root
The two surfaces are identical except one word: sync drops await.
| Context | Import from | Style |
|---|---|---|
| Scripts / notebooks / REPL | b2c_tooling_sdk.sync |
blocking, no await |
| Inside an existing event loop (web server, async app) | b2c_tooling_sdk |
await |
Notebooks: use the sync facade — it is the frictionless path (no
asyncio.run, no await). All sync calls run on one shared background loop, so
token caching still works.
# Notebook / script (sync)
from b2c_tooling_sdk.sync import resolve_config
from b2c_tooling_sdk.sync import list_code_versions
config = resolve_config() # blocks
instance = config.create_b2c_instance()
for v in list_code_versions(instance):
print(v.id, "active" if v.active else "")
# Async
import asyncio
from b2c_tooling_sdk import resolve_config
from b2c_tooling_sdk.operations.code import list_code_versions
async def main() -> None:
config = await resolve_config()
instance = config.create_b2c_instance()
for v in await list_code_versions(instance):
print(v.id)
asyncio.run(main())
Never call the sync facade from inside a running event loop (including async notebook cells /
await-ing cells) — it waits on a background loop and can deadlock. In async code, import fromb2c_tooling_sdkandawait.Streaming APIs (
tail_logs, cartridge watching) are async-only — not in the sync facade. Use the async API for those.
The examples below use the async form. For sync, import the same names from
b2c_tooling_sdk.sync and drop await.
3. Authenticate — choose by use case
Credentials usually come from a dw.json via resolve_config() (see §4). If you
already have a dw.json, prefer resolve_config + create_b2c_instance() —
it selects the auth mechanism for you. Reach for an explicit strategy only when
you have no config file or need a specific flow.
| Use case | Mechanism | How |
|---|---|---|
| Server-to-server automation (CI, scripts) | OAuth client-credentials | OAuthStrategy(OAuthConfig(client_id, client_secret, scopes)) |
| Server-to-server with a cert instead of a secret | JWT Bearer | JwtOAuthStrategy(JwtOAuthConfig(client_id, cert_path, key_path, ...)) |
| Interactive user login (opens a browser) | PKCE (+ implicit fallback) | create_user_auth_strategy(PkceOAuthConfig(client_id=..., account_manager_host=...)) |
Reuse a session created by b2c auth login |
shared session store | resolve_config() picks it up automatically; or find_auth_session(client_id) |
| WebDAV / OCAPI Basic auth | Basic | BasicAuthStrategy(username, password) |
| Static API key header | API key | ApiKeyStrategy("my-key") |
| Storefront shopper tokens (guest/registered) | SLAS | b2c_tooling_sdk.slas.get_guest_token(...) — see §6 |
from b2c_tooling_sdk.auth import OAuthStrategy, OAuthConfig
auth = OAuthStrategy(OAuthConfig(
client_id="...", client_secret="...", scopes=["sfcc.products"],
))
CLI interoperability: the SDK shares the same on-disk auth-sessions.json
and config files as the @salesforce/b2c-cli. Recommended interactive workflow:
run b2c auth login <clientId> once, then run non-interactive Python — it reuses
the session with no browser prompt. find_auth_session,
is_auth_session_token_valid, and list_auth_sessions inspect the store.
Don't know which methods a credential bundle supports? Use
resolve_auth_strategy(AuthCredentials(...), allowed_methods=[...]) to pick the
best available, or check_available_auth_methods(...) to probe without side
effects.
4. Resolve config from dw.json
resolve_config() merges the same sources the CLI reads (dw.json walking up
from cwd, ~/.mobify, package.json, settings.json) into a resolved config
whose .create_b2c_instance() builds an authenticated B2CInstance.
from b2c_tooling_sdk import resolve_config, NormalizedConfig
config = await resolve_config() # from dw.json etc.
instance = config.create_b2c_instance()
# ...or pass explicit overrides instead of a file:
config = await resolve_config(NormalizedConfig(
hostname="example.demandware.net",
client_id="...", client_secret="...", scopes=["sfcc.products"],
))
Multi-environment dw.json (a configs array of named envs): select one with
resolve_config(options=ResolveConfigOptions(instance="staging")) (priority:
requested name → active: true → root). Manage entries with add_instance /
remove_instance / set_active_instance from b2c_tooling_sdk.config.
5. Call the APIs — two layers
Choose the layer by how you want errors handled:
- Operations (
b2c_tooling_sdk.operations.*, common ones re-exported at top level) — task-oriented, success-or-raise. Straight-line code; failures raise typed exceptions (JobExecutionError, sandbox polling errors, ...). Prefer this for most work. - Clients (
instance.ocapi,instance.webdav, SCAPIcreate_*_client) — low-level. Every call returns aClientResult(data, error, response)and never raises on 4xx/5xx (only a genuine network failure raisesNetworkError). Use when you want to inspect status codes yourself.
# Operation (raises on failure)
from b2c_tooling_sdk.operations.jobs import execute_job, wait_for_job
execution = await execute_job(instance, "MyJob")
finished = await wait_for_job(instance, "MyJob", execution.id) # raises JobExecutionError on failure
# Client (never raises on HTTP status)
result = await instance.ocapi.get("/sites")
if result.error is not None:
print("failed:", result.response.status_code, result.error)
else:
for site in result.data.get("data", []):
print(site["id"])
What's available (full lists in references/api-catalog.md):
- Code —
find_and_deploy_cartridges,list_code_versions,create_code_version,activate_code_version. Deploy needsinstance.config.code_versionset. - Jobs —
execute_job,wait_for_job,site_archive_import,site_archive_export_to_path(+scapi_*native variants). - Sites —
get_cartridge_path,add_cartridge. - Catalogs / BM users / BM roles — dual-backend (SCAPI→OCAPI) façades:
create_catalogs_backend,create_users_backend,create_roles_backend. - ODS (sandboxes) —
create_ods_client+wait_for_sandbox. - Metrics —
create_metrics_client+get_overall_metrics,get_sales_metrics,get_scapi_metrics, ... - Logs —
list_log_files,get_recent_logs;tail_logs(async-only). - Account Manager —
create_user,grant_role,list_orgs, ... - Raw HTTP —
instance.ocapi(OCAPI Data API),instance.webdav(put/get/delete/propfind).
SCAPI Admin clients need system auth (client-credentials or JWT) and a
short_code + tenant_id. Get the coordinates from instance.scapi_client_config
(it's None when the instance can't do SCAPI):
from b2c_tooling_sdk.clients import create_metrics_client, MetricsClientConfig
scapi = instance.scapi_client_config
if scapi is not None:
metrics = create_metrics_client(
MetricsClientConfig(short_code=scapi.short_code, tenant_id=scapi.tenant_id),
scapi.auth,
)
6. SLAS shopper tokens (storefront)
For shopper-facing storefront tokens (not admin/tooling). Subpath import only — not in the top-level barrel:
from b2c_tooling_sdk.slas import get_guest_token, SlasTokenConfig
token = await get_guest_token(SlasTokenConfig(
short_code="abcd1234", organization_id="f_ecom_zzte_053",
slas_client_id="...", site_id="RefArch",
redirect_uri="http://localhost:3000/callback",
# slas_client_secret="..." # omit for a public PKCE client
))
print(token.access_token) # shopper JWT
get_registered_token(SlasRegisteredLoginConfig(...)) for logged-in customers.
Blocking twins are in b2c_tooling_sdk.sync. The tooling SDK has no dedicated
storefront client — after minting the token, call Shopper endpoints with plain
httpx using token.access_token as a bearer.
Runnable examples
python/samples/ has runnable scripts (code/*_async.py + *_sync.py) and
notebooks (notebook/*.ipynb) for each scenario above (oauth_ocapi, oauth_scapi,
basic_webdav, cli_session, browser_login, slas_shopper, multi_env). Point users
there; copy dw.example.json → dw.json and fill in credentials.