j1.0.3
API Overview
The Environments API provides B2C Commerce (SCAPI)-native access to Managed Runtime (MRT) environment data for Storefront Next and PWA Kit storefronts. It replaces the Business Manager UI and partial data API setup flow. The B2C CLI and other tooling can use it for end-to-end automation.
- Environment tasks — create, retrieve, list, update (display name), delete environments belonging to a storefront, and clone or promote them.
- Cache invalidations — trigger a CDN cache invalidation on an environment by path prefix.
- Environment variables — read and merge-update the customer-defined key/value configuration on an environment.
- Access control headers — create, read, and delete header-based access control rules on an environment.
- Redirects — create, list, read, update, delete, and clone URL redirect rules on an environment.
Environment creation and deletion are asynchronous: the API returns immediately with the resource in a non-terminal status, and callers poll the resource by ID to track progress.
Authentication & Authorization
Requests are authenticated with Account Manager OAuth 2.0 bearer tokens (AmOAuth2). Access is governed by the Environments API scopes: sfcc.storefront.environments grants read-only access, and sfcc.storefront.environments.rw grants read and write access. Read operations (GET) accept either scope. Write operations (POST, PATCH, PUT, DELETE) require the .rw variant.
Idempotency
POST .../environments: This operation isn't idempotent, in effect or response.environmentIdis server-generated, so there is no client-supplied key to reject a retry against. Each call creates a new, distinct environment.PATCH .../environments/{environmentId}: This operation is idempotent. The request body is the environment's full desireddisplayName. Repeating an identical request produces the same resulting state.DELETE .../environments/{environmentId}: This operation is idempotent in effect, but not in response code. The first call queues deletion (202). Once deletion completes, retrying returns 404. Deleting an environment that is stillbuildingordeletingreturns 409 (EnvironmentBusyErrorResponse) rather than queuing a duplicate deletion.PUT .../environments/{environmentId}/primary: This operation is idempotent. Setting an already-primary environment as primary again has no effect and returns 200.
Use Cases
- Provision a storefront's environments.
- Clone an existing environment to stand up a new one with matching configuration.
- Poll environment status during asynchronous provisioning or teardown.
- Promote an environment to be the storefront's primary environment.
- Decommission environments belonging to a storefront.
- Purge stale content from a storefront's CDN after a release.
- Manage environment variables, access control headers, and redirects as part of storefront development and administration.
Let us know so we can improve!