Create order

Create a new order with HMAC signature verification and idempotency protection.

🔐 HMAC Signing (REQUIRED)

All order creation requests MUST include HMAC-SHA256 signature for security:

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

Example (Node.js):

const crypto = require('crypto');
const timestamp = Math.floor(Date.now() / 1000);
const body = JSON.stringify(orderData);
const payload = `${timestamp}.${body}`;
const signature = crypto.createHmac('sha256', hmacSecret)
  .update(payload).digest('base64');
  
// Include in headers:
// X-Timestamp: 1771523993
// X-Signature: IqdgKXgloLzL5akDgFEwPaK6wviozf...

🔄 Idempotency Protection

Include Idempotency-Key header to prevent duplicate orders on retry. If the same key is used, the original order is returned (not counted against rate limit).

⚠️ Security Notes:

• HMAC secret is displayed in Settings → Integration Settings
• Never expose HMAC secret in client-side code
• Regenerate secret immediately if compromised
• Requests with invalid/missing signatures return 401 Unauthorized
• Timestamps older than 5 minutes are rejected to prevent replay attacks

POST /v1/orders

Create order

cURL

curl --request POST \
  --url https://api.tybritelabs.com/v1/orders \
  --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 '
{
  "customer_id": "c320094c-eb65-4879-804c-83d2e1dd7f99",
  "customer_email": "[e-mail]",
  "customer_name": "John Doe",
  "customer_phone": "[phone]",
  "billing_address": {
    "street": "123 Main Street",
    "city": "Nairobi",
    "state": "Nairobi County",
    "zip": "00100",
    "country": "Kenya"
  },
  "shipping_address": {
    "street": "123 Main Street",
    "city": "Nairobi",
    "state": "Nairobi County",
    "zip": "00100",
    "country": "Kenya"
  },
  "items": [
    {
      "product_id": "9b2bb0c5-666d-4729-a59d-2526ec38add9",
      "product_name": "iPhone 15 Pro",
      "product_sku": "SKU-001",
      "quantity": 2,
      "unit_price": 1000,
      "total_price": 2000
    }
  ],
  "payment_method": "card",
  "payment_status": "pending",
  "subtotal": 2000,
  "tax_amount": 320,
  "shipping_amount": 200,
  "discount_amount": 0,
  "total_amount": 2520,
  "notes": "Gift wrap requested",
  "gift_card_redemption": {
    "code": "V5G6-4N7H-9P2R-8W1S",
    "amount": 1000
  },
  "promotion_usages": [
    {
      "promotion_id": 42,
      "discount_amount": 150
    }
  ]
}
'

201

Example

{
  "id": "922d235e-48c9-4933-abcd-88cb2a264f86",
  "order_number": "ORD-1771523999910",
  "customer_id": "c320094c-eb65-4879-804c-83d2e1dd7f99",
  "customer_email": "[e-mail]",
  "customer_name": "John Doe",
  "order_status": "pending",
  "payment_status": "pending",
  "total_amount": 2520,
  "items": [
    {
      "product_id": "9b2bb0c5-666d-4729-a59d-2526ec38add9",
      "product_name": "iPhone 15 Pro",
      "quantity": 2,
      "unit_price": 1000,
      "total_price": 2000
    }
  ],
  "created_at": "2026-02-19T10: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 orders (e.g., order-{timestamp}-{random})

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.

Body

application/json

items · object[] · required

Order line items (at least one required)

Minimum array length: 1

Show child attributes

payment_method · enum<string> · required

Payment method identifier (required)

Available options: card, stripe, paystack, mpesa, airtel_money, cash

Example:

"card"

total_amount · number<float> · required

Total order amount (required)

Example:

2520

customer_id · string<uuid>

Customer UUID (optional - guest checkout supported)

Example:

"c320094c-eb65-4879-804c-83d2e1dd7f99"

customer_email · string<email>

Customer email address

Example:

"[e-mail]"

customer_name · string

Customer full name

Example:

"John Doe"

customer_phone · string

Customer phone number

Example:

"[phone]"

billing_address · object

Billing address (optional)

Show child attributes

shipping_address · object

Shipping address (optional)

Show child attributes

payment_status · enum<string>

Payment status (defaults to pending)

Available options: pending, paid, failed, refunded

Example:

"pending"

order_status · enum<string>

Order fulfillment status (defaults to pending)

Available options: pending, processing, shipped, delivered, cancelled

Example:

"pending"

subtotal · number<float>

Subtotal before tax and shipping

Example:

2000

tax_amount · number<float>

Tax amount

Example:

320

shipping_amount · number<float>

Shipping cost

Example:

200

discount_amount · number<float>

Discount amount

Example:

0

notes · string

Additional order notes

Example:

"Please deliver between 9 AM - 5 PM"

tracking_number · string

Shipping tracking number (optional, usually set on PATCH)

Example:

"1Z999AA10123456784"

estimated_delivery · string<date-time>

Estimated delivery date and time (optional)

Example:

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

payment_reference · string

External payment reference (e.g., Stripe charge ID, M-Pesa receipt)

Example:

"ch_1NqFvE2eZvKYlo2C8Z3y4abc"

shipping_metadata · object

Shipping calculation details from /v1/shipping/calculate for audit trail

Show child attributes

gift_card_redemption · object

Optional gift card to redeem towards this order

Show child attributes

promotion_usages · object[] | null

Promotion usages applied to this order (tracked when payment_status is paid)

Show child attributes

Response

201

application/json

Order created successfully (or existing order returned if idempotency key matches)

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

post_processing_warnings · object[]

Optional. Present only when one or more post-order processing steps (gift card redemption, stock reduction, etc.) failed. The order itself was created successfully, but a downstream side effect needs human follow-up. Each warning indicates the stage that failed and a human-readable message.

Show child attributes