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:

1. Generate Timestamp: Get current Unix timestamp in seconds
2. Create Payload: Concatenate timestamp + "." + JSON_body
3. Sign Payload: HMAC-SHA256(hmac_secret, payload) → base64 encode
4. 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 /v1/orders/{id}

cURL

mark_as_paid

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

200

Example

{
  "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": 2049.97,
  "items": [
    {
      "product_name": "iPhone 15 Pro",
      "quantity": 2,
      "unit_price": 999.99
    }
  ],
  "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 Settings → Integration Settings.

Path Parameters

id · 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"

Response

200

application/json

Order updated successfully

id · 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, paystack, mpesa, airtel, cash, bank_transfer

Example:

"stripe"

payment_reference · string

subtotal · number<float>

Example:

1999.98

tax_amount · number<float>

Example:

159.99

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

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>

shipping_metadata · object

Complete shipping calculation details for audit trail

Show child attributes