br_... API key. Test keys, anonymous sessions, and OAuth sessions
cannot create, inspect, apply, or roll back a promotion. The key needs a grant
for the named studio plus sandbox_promotions:read to plan or review and
sandbox_promotions:apply to apply or roll back.
What can move
Choose one or more of these configuration areas when creating a plan:
The response lists each action as
create, update, archive, no_op, or
block. It also includes the resource changes, catalog price before/after
where it applies, new Live ID mappings, the current media-preparation state,
warnings, and conflicts. Values are limited to user-visible fields. The API
does not return storage IDs, temporary upload credentials, or asset URLs.
Create and review a plan
Create a plan with a stable idempotency key:plan_sha256 is the commitment for the complete promoted public
configuration, not only the compact review summary. The summary names each
resource and its changed_fields, while omitting verbose values that do not
need to be shown at review time. Each resource also includes before_sha256
and after_sha256 commitments for its privacy-safe before and after payloads.
Together they cover every promoted field without exposing private snapshots,
provider payloads, URLs, object keys, storage IDs, or raw form data. Apply
requires the exact reviewed plan version and checksum, so the server can reject
a changed plan instead of applying a different configuration.
Read the plan again before acting:
preparing means internal trusted media staging is unsettled. Creating the
plan may begin copying already-stored sandbox media, but preparing makes no
readiness guarantee. Wait until the plan is ready, or resolve the reported
preparation issue.
Apply a reviewed plan
Apply only the plan version and SHA-256 you reviewed:409 sandbox_promotion_conflict. Fetch
the current promotion, read the conflict, and create a new plan when the
source or Live configuration changed. Do not retry an ambiguous apply with a
different idempotency key.
Roll back an applied promotion
Rollback uses the applied version and checksum returned after a successful apply. It rolls back only the recorded promotion changes. It does not undo configuration changes made later outside that promotion.Identity and media behavior
Live records receive Live IDs. The plan’s identity mapping tells you which sandbox record maps to which new Live record. Treat those mappings as the only safe way to update downstream configuration after promotion. Media can require preparation before apply. The promotion status reports that state:preparing means it is unsettled, while ready means the server can
review and apply the plan. A blocked or failed plan requires correction in the
sandbox configuration and a new plan. The API can work with already-stored
sandbox media internally, but it never accepts or returns bytes, temporary
upload sessions, storage IDs, object keys, signed URLs, or reusable storage
capabilities.
What stays out of a promotion
Promotions intentionally exclude checkout links, event records, temporary upload sessions, API idempotency records, and anonymous sessions. Test checkout links remain non-payable. Recreate approved checkout links in Live Mode after the storefront and catalog changes are live.Terminal workflow
Runbatchrelay tui from a human terminal and choose Promote sandbox setup.
The review screen shows the selected studio name and ID, creates, updates,
archives, blocks, price changes, new ID mappings, media preparation, warnings,
and conflicts. Before apply, type the displayed studio name exactly.
The TUI calls the same Cobra commands shown above. --json, --no-tui, CI,
agent mode, and non-TTY sessions stay scriptable and never open the TUI.
Errors and recovery
See Idempotency, Authentication,
Sandbox Testing, and Errors for the shared
request rules.