> ## Documentation Index > Fetch the complete documentation index at: https://docs.batchrelay.com/llms.txt > Use this file to discover all available pages before exploring further. # Promote sandbox studio setup > Review and apply a bounded sandbox-to-Live studio configuration promotion. A sandbox promotion copies selected studio configuration from Test Mode into Live Mode. It is a reviewable configuration change, not a general migration. The promotion plan records the source state, the target state, and the exact changes the server can safely apply. Use a Live `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. A promotion changes Live studio configuration. Review the plan and resolve every block or conflict before applying it. The CLI requires an explicit studio-name confirmation in its terminal workflow. Noninteractive apply and rollback also require `--yes`. ## What can move Choose one or more of these configuration areas when creating a plan: | Include | What the plan evaluates | | ------------ | ----------------------------------------------------------------------------------- | | `forms` | Reusable form definitions and event form configuration that the promotion supports. | | `catalog` | Studio catalog products, variants, and packages. | | `storefront` | The published storefront assortment. | 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: ```bash theme={null} batchrelay sandbox promotions plan \ --studio stu_example \ --include forms,catalog,storefront \ --idempotency-key sandbox-to-live-20260830-001 \ --pretty ``` The CLI writes the complete plan JSON to stdout. It writes warnings and diagnostics to stderr, with keys, idempotency values, signed URLs, and storage identifiers removed. Save the promotion ID, plan version, and plan SHA-256 from the reviewed response. Do not construct either checksum yourself. The `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: ```bash theme={null} batchrelay sandbox promotions get spr_example --studio stu_example --pretty ``` `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: ```bash theme={null} batchrelay sandbox promotions apply spr_example \ --studio stu_example \ --expected-plan-version 4 \ --plan-sha256 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef \ --idempotency-key sandbox-to-live-20260830-apply \ --yes \ --pretty ``` The server rejects a stale plan with `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. ```bash theme={null} batchrelay sandbox promotions rollback spr_example \ --studio stu_example \ --expected-applied-version 2 \ --applied-sha256 abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789 \ --idempotency-key sandbox-to-live-20260830-rollback \ --yes \ --pretty ``` ## 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 Run `batchrelay 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 | Code | Meaning | Recovery | | ------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------- | | `invalid_promotion_request` | Includes, version, checksum, or request body is invalid. | Correct the request without changing the intended idempotency key. | | `idempotency_key_required` | A write did not include a stable key. | Supply one before retrying. | | `sandbox_promotion_forbidden` | The key is not a Live key or lacks the studio grant or scope. | Use the intended Live profile and grant. | | `sandbox_promotion_not_found` | The promotion is not visible to this studio credential. | Check the studio ID and promotion ID. | | `sandbox_promotion_conflict` | The reviewed version no longer matches, or a lifecycle transition is unsafe. | Fetch the promotion, resolve the change, then create a new plan if needed. | | `invalid_sandbox_promotion` | The current configuration cannot be promoted. | Resolve the reported block in Test Mode, then plan again. | | `sandbox_promotion_unavailable` | The service cannot prepare or apply the promotion now. | Retry the same write with the same idempotency key. | | `sandbox_promotion_failed` | A dependent promotion step failed. | Inspect the safe response details and preserve the request ID for support. | See [Idempotency](/idempotency), [Authentication](/authentication), [Sandbox Testing](/sandbox-testing), and [Errors](/errors) for the shared request rules.