Orders

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, refunded)
order_status: Order fulfillment status (pending, processing, shipped, delivered, cancelled)
notes: Additional order notes
tracking_number: Shipping tracking number
estimated_delivery: Estimated delivery date/time
shipped_at: Timestamp when order was shipped
delivered_at: Timestamp when order was delivered

Automatic Accounting: When payment_status is updated to paid, the system automatically:

Triggers accounting entry creation (production only)
Reduces inventory stock for all order items
Updates customer purchase metrics
Processes gift card redemptions (if applicable)
Records promotion usage (if applicable)

Key Type Support:

✅ Secret keys (full access)
❌ Publishable keys (forbidden - returns 403)

PATCH

orders

{id}

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

Authorization

string

header

required

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) or tybrite_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) or tybrite_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.

Headers

Idempotency-Key

string

required

Unique key to prevent duplicate updates (e.g., update-{operation}-{order_id}-{timestamp})

X-Timestamp

integer

required

Unix timestamp in seconds (current time). Must be within 5 minutes of server time. Used to prevent replay attacks.

X-Signature

string

required

HMAC-SHA256 signature of the payload (timestamp + "." + request_body), base64-encoded. Sign using your HMAC secret from the Integrations page (Developer section).

Path Parameters

string<uuid>

required

Order UUID

Body

application/json

payment_status

enum<string>

Payment status

Available options:

pending,

paid,

failed,

refunded

Example:

"paid"

order_status

enum<string>

Order fulfillment status

Available options:

pending,

processing,

shipped,

delivered,

cancelled

Example:

"processing"

notes

string

Additional order notes

Example:

"Customer requested gift wrapping"

tracking_number

string

Shipping tracking number

Example:

"1Z999AA10123456784"

estimated_delivery

string<date-time>

Estimated delivery date and time

Example:

"2026-02-15T14:00:00Z"

shipped_at

string<date-time>

Timestamp when order was shipped

Example:

"2026-02-10T10:30:00Z"

delivered_at

string<date-time>

Timestamp when order was delivered

Example:

"2026-02-15T14:30:00Z"

payment_reference

string

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.

Example:

"ch_3PqR2sK7xYzAbCdE1fGhIjKl"

reservation_ids

string[]

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.

Example:

["8f2c1a9b-4d7e-4f10-9a3b-2c5e7f1d0a44"]

Response

Order updated successfully

string<uuid>

order_number

string

Example:

"ORD-2026-001234"

customer_id

string<uuid>

customer_email

string<email>

customer_phone

string

customer_name

string

order_status

enum<string>

Available options:

pending,

processing,

shipped,

delivered,

cancelled

Example:

"pending"

payment_status

enum<string>

Available options:

pending,

paid,

failed,

refunded

Example:

"pending"

payment_method

enum<string>

Method used for payment

Available options:

stripe,

paypal,

paystack,

mpesa,

cash,

bank_transfer

Example:

"stripe"

payment_reference

string

subtotal

number<float>

Example:

1999.98

tax_amount

number<float>

Example:

159.99

tax_breakdown

object[] | null

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

tax_source

enum<string> | null

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).

Available options:

automatic,

fallback,

manual,

null

Example:

"automatic"

shipping_amount

number<float>

Example:

15

discount_amount

number<float>

Example:

0

total_amount

number<float>

Example:

2174.97

billing_address

object

Show child attributes

shipping_address

object

Show child attributes

items

object[]

Show child attributes

status_notes

object[]

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

custom_fields

object[]

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

notes

string

tracking_number

string

estimated_delivery

string<date-time>

shipped_at

string<date-time>

delivered_at

string<date-time>

created_at

string<date-time>

updated_at

string<date-time>

environment

enum<string>

Whether this order was created in the live or test environment. Sandbox orders are isolated from production data.

Available options:

production,

sandbox

Example:

"production"

shipping_metadata

object | null

Complete shipping calculation details for audit trail

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"
}

Reference

System

Products

Taxonomy

Orders

Payments

Cart & Wishlist

Marketplace

Recommendations

Discovery

Events

Tax

Analytics

Search

Authentication

Customers

Gift Cards

Promotions

CMS

Pricing

Messaging

Shipping

GC Connect

Reviews

Returns

Disputes

B2B

Webhooks

Ingestion

Sandbox

Update order

Authorizations

Headers

Path Parameters

Body

Response