Skip to main content
POST
Prepare studio order refund

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

X-BatchRelay-Delegated-Authorization
string

Original delegated Clerk OAuth bearer. Go independently verifies signature/current revocation, exact resource audience, allowed OAuth client and action scope. Caller must match attributed API key creator. Never send an unverified subject header.

Idempotency-Key
string
required

Durable exact refund preview/request identity. Repeat unchanged after interruption.

Required string length: 16 - 80
Pattern: ^[A-Za-z0-9_-]{16,80}$
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

Opaque public studio_id. Private Convex IDs are rejected.

Body

application/json
amount_cents
integer
required
Required range: 1 <= x <= 9007199254740991
customer_id
string
required
note
string
required
order_id
string
required
reason_code
string
required
basis
string
percentage
number
Required range: x <= 100Must be a multiple of 0.01

Response

Authoritative Studio result

allocations
object[]
required
already_refunded_cents
integer<int64>
required
amount_cents
integer<int64>
required
approval_reserved_cents
integer<int64>
required
basis
string
required
blockers
string[]
required
currency
string
required
customer_id
string
required
delivery_effect
string
required
destination
string
required
environment
string
required
expires_at
integer<int64>
required
financial_revision
string
required
id
string
required
note
string
required
order_id
string
required
original_paid_cents
integer<int64>
required
pending_cents
integer<int64>
required
percentage
number | null
required
reason_code
string
required
remaining_cents
integer<int64>
required
requires_approval
boolean
required
simulated
boolean
required
studio_id
string
required