Reserve stock for checkout
Optional. Holds stock for the items a customer is checking out so the units can’t be sold to someone else while they complete payment.
Use this when there is a gap between “customer commits to buy” and “payment
confirms” — card redirects, 3‑D Secure, or mobile‑money push prompts — so
the stock is claimed before the customer pays and a second shopper racing
for the last unit is turned away up front. For instant‑capture or fully
synchronous flows you can skip it and call POST /v1/orders directly;
Galactic Core still prevents stock from going negative at order time. In
other words, reserving is a stronger guarantee for async payments, not a
mandatory step before every order.
Reservations are all‑or‑nothing: if any item lacks available stock, nothing
is reserved and the response is 409. Each hold expires automatically after
a window (15 minutes by default). Pass the returned reservation_ids to
POST /v1/orders (or when you PATCH an order to paid) and Galactic Core
converts the hold into the actual stock deduction. If the customer abandons
checkout, the hold simply expires and the stock returns to availability —
you don’t need to release it explicitly.
Works with both publishable and secret keys (checkout originates in the browser).
Rate limit: 300 requests/hour per API key.
Authorizations
API Key Authentication
Use your API key in the Authorization header:
Key Types:
Secret Keys (Server-Side Only):
- Format:
tybrite_sk_live_*(production) ortybrite_sk_test_*(sandbox) - Full read/write access to all endpoints
- ⚠️ NEVER expose in client-side code or public repositories
- Required for: write operations, authentication, payment verification, AI recommendations
Publishable Keys (Client-Safe):
- Format:
tybrite_pk_live_*(production) ortybrite_pk_test_*(sandbox) - Read-only access (GET requests only, plus POST semantic search)
- ✅ Safe for client-side JavaScript, mobile apps, and public code
- Allowed for: browsing products, search, CMS content, pricing queries
Endpoint-Specific Requirements:
- Authentication endpoints (
/v1/auth/*): Secret key required - Payment verification (
POST /v1/payments/verify): Secret key required - AI Recommendations (
POST /v1/recommendations): Secret key required - Semantic Search (
POST /v1/search): Both key types allowed (read-only operation) - All write operations: Secret key required
- All read operations: Both key types allowed
Using a publishable key for restricted operations returns 403 Forbidden.
Body
The variants and quantities to hold.
1Optional hold duration in seconds. Defaults to 900 (15 minutes); values below 60 are raised to 60.
900
Optional - associate the hold with a customer (used for checkout recovery).
Optional - associate the hold with an anonymous browser session.

