Update order
Update specific fields of an existing order with HMAC signature verification and idempotency protection.
🔐 HMAC Signing (REQUIRED)
All order update requests MUST include HMAC-SHA256 signature:
- Generate Timestamp: Get current Unix timestamp in seconds
- Create Payload: Concatenate
timestamp + "." + JSON_body - Sign Payload:
HMAC-SHA256(hmac_secret, payload)→ base64 encode - Include Headers:
X-Timestamp: Unix timestamp (must be within 5 minutes)X-Signature: Base64-encoded HMAC signature
🔄 Idempotency Protection
Include Idempotency-Key header to prevent duplicate updates on retry.
Each PATCH operation is tracked separately - if you retry with the same key,
the original order state is returned without re-processing side effects.
Important: Use a unique idempotency key for each distinct update operation.
- ✅ Good:
update-shipping-{order_id}-{timestamp},mark-paid-{order_id}-{timestamp} - ❌ Bad: Reusing the same key for different updates to the same order
This prevents duplicate processing of critical operations like:
- Double-triggering accounting entries when marking as paid
- Re-reducing inventory stock
- Duplicate gift card redemptions
- Multiple promotion usage recordings
Updatable Fields:
payment_status: Payment status (pending, paid, failed)order_status: Order fulfillment status (pending, confirmed, processing, shipped, delivered, cancelled)notes: Additional order notestracking_number: Shipping tracking numberestimated_delivery: Estimated delivery date/timeshipped_at: Timestamp when order was shippeddelivered_at: Timestamp when order was deliveredshipping_metadata: Fulfilment details such as a purchased label’s carrier and tracking (replaces the stored object)
Status transitions:
payment_status:pending→paidorfailed;failed→paid. Apaidorder does not move back, andrefundedis set by processing a refund, not by this endpoint.order_statusmoves forward only (pending→confirmed→processing→shipped→delivered).cancelledis available until the order ships.cancelledanddeliveredare final, and a cancelled order cannot be marked paid.- Sending a field with the value it already has is not a transition: the request succeeds
and nothing is repeated. Any other move is refused with
409 invalid_transition. - A status change applies only if the order is still in the state it was in when the
request began. When two requests change it at once, one succeeds and the other receives
409 order_changed.
Automatic Accounting:
When payment_status is updated to paid, the system automatically, and once:
- Triggers accounting entry creation (production only)
- Reduces inventory stock for all order items, committing the order’s own stock holds
- Updates customer purchase metrics
- Redeems the gift card applied at checkout (if applicable)
- Records promotion usage and campaign spend (if applicable)
Anything that does not complete is listed in
post_processing_warningson the response; the order stays paid.
When an unpaid order is cancelled or its payment fails, its stock holds are released and any store credit applied to it is returned to the customer.
Key Type Support:
- ✅ Secret keys (full access)
- ❌ Publishable keys (forbidden - returns 403)
curl --request PATCH \
--url https://api.tybritelabs.com/v1/orders/{id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--header 'X-Signature: <x-signature>' \
--header 'X-Timestamp: <x-timestamp>' \
--data '
{
"payment_status": "paid"
}
'{
"id": "880e8400-e29b-41d4-a716-446655440003",
"customer_id": "550e8400-e29b-41d4-a716-446655440000",
"order_status": "shipped",
"payment_status": "paid",
"tracking_number": "1Z999AA10123456784",
"shipped_at": "2026-02-10T10:30:00Z",
"estimated_delivery": "2026-02-15T14:00:00Z",
"total_amount": 2004.99,
"items": [
{
"product_name": "Apple MacBook Pro",
"quantity": 2,
"unit_price": 1999
}
],
"created_at": "2026-02-03T10:30:00Z",
"updated_at": "2026-02-10T10:30:00Z"
}Authorizations
API Key Authentication
Use your API key in the Authorization header:
Authorization: Bearer tybrite_sk_live_YOUR_KEY
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: every write a shopper does not make for themselves, authentication, payment verification, AI recommendations
Publishable Keys (Client-Safe):
- Format:
tybrite_pk_live_*(production) ortybrite_pk_test_*(sandbox) - Catalogue reads, plus the actions a shopper takes for themselves
- ✅ Safe for client-side JavaScript, mobile apps, and public code
- Allowed for: browsing products, search, CMS content, pricing queries, cart and wishlist, reviews, storefront events, and the Agent API's quotes, cart drafts and checkout intents
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) - Shopper actions (cart, wishlist, reviews, storefront events, Agent API quotes, cart drafts and checkout intents): Both key types allowed
- All other write operations: Secret key required
- All read operations: Both key types allowed
Using a publishable key for restricted operations returns 403 Forbidden.
Headers
Unique key to prevent duplicate updates (e.g., update-{operation}-{order_id}-{timestamp})
Unix timestamp in seconds (current time). Must be within 5 minutes of server time. Used to prevent replay attacks.
HMAC-SHA256 signature of the payload (timestamp + "." + request_body), base64-encoded. Sign using your HMAC secret from the Integrations page (Developer section).
Path Parameters
Order UUID
Body
Payment status. See the allowed transitions above.
pending, paid, failed "paid"
Order fulfillment status. See the allowed transitions above.
pending, confirmed, processing, shipped, delivered, cancelled "processing"
Additional order notes
"Customer requested gift wrapping"
Shipping tracking number
"1Z999AA10123456784"
Estimated delivery date and time
"2026-02-15T14:00:00Z"
Timestamp when order was shipped
"2026-02-10T10:30:00Z"
Timestamp when order was delivered
"2026-02-15T14:30:00Z"
The reference your payment provider issued for this payment. Send it when marking an order paid that was charged outside Galactic Core, so the payment can be traced back to the provider's own record. When the store has added its own payment method, the reference is checked with that provider before the order is accepted as paid.
"ch_3PqR2sK7xYzAbCdE1fGhIjKl"
Stock reservation ids returned by POST /v1/checkout/reserve. Supplying them commits the stock already held for this shopper rather than decrementing it a second time.
["8f2c1a9b-4d7e-4f10-9a3b-2c5e7f1d0a44"]
Fulfilment details to store on the order, such as the carrier, service, label URL and tracking details of a purchased shipping label. The object replaces the order's stored shipping_metadata in full rather than being merged into it, so include any existing keys that should be kept.
{
"fee": 5.99,
"tier_name": "Local (within 10 km)",
"carrier": "UPS",
"service": "Ground",
"label_url": "https://example.com/labels/1Z999AA10123456784.pdf",
"tracking_number": "1Z999AA10123456784"
}
Response
Order updated successfully
"ORD-2026-001234"
pending, confirmed, processing, shipped, delivered, cancelled "pending"
pending, paid, failed, refunded "pending"
Method used for payment
stripe, paypal, paystack, mpesa, cash, bank_transfer "stripe"
1999.98
159.99
Per-jurisdiction tax detail when tax was calculated automatically for the shipping destination (one entry per taxing jurisdiction). Null when a flat store rate was used.
Show child attributes
Show child attributes
How the tax figure was produced — automatic (jurisdiction-accurate calculation for the destination), fallback (automatic calculation was unavailable, so the store's configured rate was used), or manual (the store's configured rate).
automatic, fallback, manual, null "automatic"
15
0
2174.97
Show child attributes
Show child attributes
Where the order goes. On a pickup order it is the collection location's address, with type: pickup, the location's name and location_id, and the address in line1 / line2 / city / state / postal_code / country.
Show child attributes
Show child attributes
Whether the order is delivered to the shopper or collected at one of the store's locations.
delivery, pickup "delivery"
The location the shopper collects from, on a pickup order. Null on a delivery order.
null
The store location the order is fulfilled from: the pickup location on a pickup order, or the location deliveries leave from when the store delivers from its nearest location. Null when the store does not route orders between locations.
"7b2e9c41-0d3f-4a58-b6e1-2f4a6c8e0b13"
The shipping option the order was placed with, as returned by POST /v1/shipping/calculate (place, opt:<id> or pickup:<location id>). Null when none was named.
"place"
Show child attributes
Show child attributes
Customer-visible updates the merchant added as the order moved — the work between payment and dispatch (preparation, checks, packing) that a shopper otherwise hears nothing about. Oldest first, so it reads as a timeline. Internal notes are never included.
Show child attributes
Show child attributes
The merchant's own fields on this order, with their values — a buyer's purchase-order number, a cost centre, whatever the merchant defined. Only fields the merchant published appear here; one holding an internal note or a cost stays in the admin. Empty when the merchant has defined none.
The merchant controls the names and how many exist, so render the array rather than reading fixed
keys: field_label is the heading to show, and field_type gives the shape of value.
Show child attributes
Show child attributes
Whether this order was created in the live or test environment. Sandbox orders are isolated from production data.
production, sandbox "production"
How the shipping charge was arrived at. shipping_source and shipping_rule are recorded by the server when the order is created; the other fields are the details the storefront sent with the order.
Show child attributes
Show child attributes
Present only when the update marked the order paid and one or more of the steps that follow (stock, gift card, store credit, promotion usage) did not complete. The order stays paid; each warning names the step and what needs follow-up.
Show child attributes
Show child attributes
curl --request PATCH \
--url https://api.tybritelabs.com/v1/orders/{id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--header 'X-Signature: <x-signature>' \
--header 'X-Timestamp: <x-timestamp>' \
--data '
{
"payment_status": "paid"
}
'{
"id": "880e8400-e29b-41d4-a716-446655440003",
"customer_id": "550e8400-e29b-41d4-a716-446655440000",
"order_status": "shipped",
"payment_status": "paid",
"tracking_number": "1Z999AA10123456784",
"shipped_at": "2026-02-10T10:30:00Z",
"estimated_delivery": "2026-02-15T14:00:00Z",
"total_amount": 2004.99,
"items": [
{
"product_name": "Apple MacBook Pro",
"quantity": 2,
"unit_price": 1999
}
],
"created_at": "2026-02-03T10:30:00Z",
"updated_at": "2026-02-10T10:30:00Z"
}