Skip to main content
POST
Schedule a studio offer

Authorizations

Authorization
string
header
required

Batch Relay scoped API key or an anonymous Test Mode session. Scope names document required capabilities. Anonymous sessions are sandbox-only and do not authorize studio, event, billing, or Live Mode operations.

Headers

Idempotency-Key
string
required
Required string length: 1 - 200
X-BatchRelay-Client-Surface
string

Untrusted optional analytics hint naming the calling client surface. It never affects authorization, routing, pricing, or behavior.

Required string length: 1 - 100
X-BatchRelay-Client-Version
string

Untrusted optional analytics hint naming the calling client version. It never affects authorization, routing, pricing, or behavior.

Required string length: 1 - 100
X-BatchRelay-Invocation-Mode
string

Untrusted optional analytics hint naming the invocation mode. It never affects authorization, routing, pricing, or behavior.

Required string length: 1 - 100

Path Parameters

studio_id
string
required

Stable public studio ID beginning with stu_. The API never selects a studio implicitly; a local CLI profile name is not a studio ID.

Required string length: 5 - 256
Pattern: ^stu_[A-Za-z0-9_-]+$
offer_id
string
required

Body

application/json
expected_revision
integer
required
Required range: x >= 1
ends_at
string<date-time>

Optional schedule end; when set it must match the immutable revision terms.

reason
string
Maximum string length: 500
revision_id
string

Required for activate and schedule; the provisioned immutable revision to transition.

Required string length: 1 - 240
starts_at
string<date-time>

Required and future-dated for schedule.

Response

Scheduled studio offer

application
enum<string>
required
Available options:
automatic,
code
created_at
string<date-time>
required
currency
string
required
Allowed value: "USD"
id
string
required
kind
enum<string>
required
Available options:
percent,
fixed
limits
object
required
name
string
required
provisioning_status
enum<string>
required
Available options:
pending,
processing,
succeeded,
failed,
uncertain,
unsupported
revision
integer
required
Required range: x >= 1
revision_id
string
required

Immutable candidate revision ID to pass to activate or schedule.

Minimum string length: 1
scope
object
required
status
enum<string>
required
Available options:
draft,
scheduled,
active,
paused,
expired,
exhausted,
revoked,
sync_error
updated_at
string<date-time>
required
usage
object
required
amount_off_cents
integer
code
string
customer_service_reason
string
ends_at
string<date-time>
minimum_subtotal_cents
integer
percent_off
integer
starts_at
string<date-time>