Skip to content
Skills Library
Programming · Tool integration

using-b2c-tooling-sdk

/using-b2c-tooling-sdk

Consuming the salesforce-b2c-tooling-sdk Python SDK from scripts or Jupyter notebooks — installation, choosing an authentication mechanism, and the available OCAPI/SCAPI/WebDAV clients and operations. Use when writing Python (or notebook) code that authenticates to a B2C Commerce instance, resolves config from dw.json, deploys code, runs jobs, reads sites/catalogs/logs/metrics, provisions sandboxes, or mints SLAS shopper tokens.

Licence
Apache-2.0
Last repository change
23.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
2
Deprecation

No signals detected. Repository changed on 23.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Consuming the salesforce-b2c-tooling-sdk Python SDK from scripts or Jupyter notebooks — installation, choosing an authentication mechanism, and the available OCAPI/SCAPI/WebDAV clients and operations. Use when writing Python (or notebook) code that authenticates to a B2C Commerce instance, resolves config from dw.json, deploys code, runs jobs, reads sites/catalogs/logs/metrics, provisions sandboxes, or mints SLAS shopper tokens.

Original author description

Consuming the salesforce-b2c-tooling-sdk Python SDK from scripts or Jupyter notebooks — installation, choosing an authentication mechanism, and the available OCAPI/SCAPI/WebDAV clients and operations. Use when writing Python (or notebook) code that authenticates to a B2C Commerce instance, resolves config from dw.json, deploys code, runs jobs, reads sites/catalogs/logs/metrics, provisions sandboxes, or mints SLAS shopper tokens.

How it works

  1. 1. Install
  2. 2. Async vs. sync — pick the import root
  3. 3. Authenticate — choose by use case
  4. 4. Resolve config from dw.json
  5. 5. Call the APIs — two layers
  6. 6. SLAS shopper tokens (storefront)
  7. Runnable examples
Original SKILL.md headings · 223 lines, 1,078 words
SKILL.md preview
---
name: using-b2c-tooling-sdk
description: Consuming the salesforce-b2c-tooling-sdk Python SDK from scripts or Jupyter notebooks — installation, choosing an authentication mechanism, and the available OCAPI/SCAPI/WebDAV clients and operations. Use when writing Python (or notebook) code that authenticates to a B2C Commerce instance, resolves config from dw.json, deploys code, runs jobs, reads sites/catalogs/logs/metrics, provisions sandboxes, or mints SLAS shopper tokens.
---

# Using the B2C Tooling SDK (Python)

`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](references/api-catalog.md).

## 1. Install

Not on PyPI yet — install from git during development:

```bash
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.

```python
# 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 "")
```

```python
# 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 from `b2c_tooling_sdk` and `await`.
>
> **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 |

```python
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`.

```python
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`, SCAPI `create_*_client`) —
  low-level. Every call returns a `ClientResult(data, error, response)` and
  **never raises on 4xx/5xx** (only a genuine network failure raises
  `NetworkError`). Use when you want to inspect status codes yourself.

```python
# 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](references/api-catalog.md)):

- **Code** — `find_and_deploy_cartridges`, `list_code_versions`,
  `create_code_version`, `activate_code_version`. Deploy needs
  `instance.config.code_version` set.
- **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):

```python
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:

```python
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.
Files in this package (2)
  • SKILL.md 10 KB
  • references/api-catalog.md 8 KB

Versions

The database has no other skills named using-b2c-tooling-sdk.

Database snapshot: 13.11.2026 · package version 0b32188199a6 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100sf-b2c-scapi
    Build with Salesforce Commerce API (SCAPI) — Shopper APIs (Products, Search, Baskets, Orders, Customers), SLAS authentication, Commerce SDK for Node.js, rate limiting, pagination, and headless commerce patterns. This is the primary B2C API. Use when building headless storefronts or API integrations.
  • 90sf-b2c-ocapi
    MIGRATION SKILL: OCAPI (Open Commerce API) — Shop API and Data API endpoints, authentication, pagination, and OCAPI-to-SCAPI migration guide. OCAPI is in maintenance-only mode with no new features. Use this skill only for maintaining legacy integrations or planning migration to SCAPI.
  • 100b2c-hooks
    Register and implement B2C Commerce platform hooks declared in hooks.json and invoked by HookMgr during OCAPI/SCAPI requests or system events. Use for hooks.json, HookMgr.callHook(), dw.system.Status, dw.ocapi.shop.* before/after/modifyResponse hooks,…
  • 100b2c-webdav
    List, upload, download, and manage files on B2C Commerce instances via WebDAV. Use this skill whenever the user needs to upload files to IMPEX directories, download exports from an instance, list remote files, create or delete directories, zip or unzip files on the server,…
  • 100salesforce-headless
    Use when building headless or composable storefronts on Salesforce B2C Commerce Cloud, integrating Salesforce Commerce APIs (SCAPI), developing with PWA Kit or Composable Storefront, migrating from SFRA to headless, implementing Shopper APIs, or deploying to Managed Runtime…
  • 90python-notebooks-async
    Use when writing or reviewing asyncio code in Jupyter notebooks or '#%%' cell workflows — structuring event-loop ownership, orchestrating async tasks, or choosing compatibility strategies. Also use when hitting RuntimeError: This event loop is already running, asyncio.run()…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.