Orders

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:

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

Example (Node.js):

🔄 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 the Integrations page (Developer section)
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

🛡️ Server-side price validation (anti-tampering)

HMAC proves the body wasn’t altered in transit; it does not prove the amounts are honest. So the server independently recomputes the order from authoritative data and rejects any mismatch — you cannot set your own prices or discounts:

Item prices are recomputed from the live catalog. unit_price / total_price that don’t match the catalog price → 400 price_mismatch. (The stored order always uses the catalog price, never the value you send.)
subtotal, tax_amount, total_amount must reconcile to subtotal + tax + shipping − discount over those catalog prices → otherwise 400 price_mismatch.
discount_amount is validated against the discount the promotions / gift card you claim actually grant (computed server-side from promotion_usages + gift_card_redemption). A discount_amount greater than that legitimate maximum → 400 discount_invalid. A discount with no real promotion/gift card behind it → max is 0. (You may apply less than the maximum.)
shipping_amount may not be negative → 400 price_mismatch.

In short: send the real catalog prices and the actual promotions/gift card the shopper is entitled to. Don’t compute or invent prices/discounts client-side — the server is the authority.

POST

orders

Create order

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_email": "john.doe@example.com",
  "customer_name": "John Doe",
  "customer_phone": "+12125550142",
  "billing_address": {
    "street": "350 Fifth Avenue",
    "city": "New York",
    "state": "NY",
    "zip": "10118",
    "country": "US"
  },
  "shipping_address": {
    "street": "350 Fifth Avenue",
    "city": "New York",
    "state": "NY",
    "zip": "10118",
    "country": "US"
  },
  "items": [
    {
      "product_id": "715b8c10-eb11-4289-8c0e-2966e78cf9a5",
      "variant_id": "15ca5a86-4b1b-47c3-8762-a1aa43941565",
      "product_name": "Apple MacBook Pro",
      "product_sku": "APP-MBP-13",
      "quantity": 1,
      "unit_price": 1999,
      "total_price": 1999
    }
  ],
  "payment_method": "card",
  "payment_status": "paid",
  "subtotal": 1999,
  "shipping_amount": 5.99,
  "discount_amount": 0,
  "total_amount": 2004.99,
  "shipping_metadata": {
    "fee": 5.99,
    "tier_name": "Local (within 10 km)",
    "distance_meters": 8548,
    "is_free": false,
    "reason": "8.5 km away",
    "applied_rule": "distance"
  },
  "notes": "Leave with front desk"
}
'

import requests

url = "https://api.tybritelabs.com/v1/orders"

payload = {
    "customer_email": "john.doe@example.com",
    "customer_name": "John Doe",
    "customer_phone": "+12125550142",
    "billing_address": {
        "street": "350 Fifth Avenue",
        "city": "New York",
        "state": "NY",
        "zip": "10118",
        "country": "US"
    },
    "shipping_address": {
        "street": "350 Fifth Avenue",
        "city": "New York",
        "state": "NY",
        "zip": "10118",
        "country": "US"
    },
    "items": [
        {
            "product_id": "715b8c10-eb11-4289-8c0e-2966e78cf9a5",
            "variant_id": "15ca5a86-4b1b-47c3-8762-a1aa43941565",
            "product_name": "Apple MacBook Pro",
            "product_sku": "APP-MBP-13",
            "quantity": 1,
            "unit_price": 1999,
            "total_price": 1999
        }
    ],
    "payment_method": "card",
    "payment_status": "paid",
    "subtotal": 1999,
    "shipping_amount": 5.99,
    "discount_amount": 0,
    "total_amount": 2004.99,
    "shipping_metadata": {
        "fee": 5.99,
        "tier_name": "Local (within 10 km)",
        "distance_meters": 8548,
        "is_free": False,
        "reason": "8.5 km away",
        "applied_rule": "distance"
    },
    "notes": "Leave with front desk"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "X-Timestamp": "<x-timestamp>",
    "X-Signature": "<x-signature>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    'X-Timestamp': '<x-timestamp>',
    'X-Signature': '<x-signature>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    customer_email: 'john.doe@example.com',
    customer_name: 'John Doe',
    customer_phone: '+12125550142',
    billing_address: {
      street: '350 Fifth Avenue',
      city: 'New York',
      state: 'NY',
      zip: '10118',
      country: 'US'
    },
    shipping_address: {
      street: '350 Fifth Avenue',
      city: 'New York',
      state: 'NY',
      zip: '10118',
      country: 'US'
    },
    items: [
      {
        product_id: '715b8c10-eb11-4289-8c0e-2966e78cf9a5',
        variant_id: '15ca5a86-4b1b-47c3-8762-a1aa43941565',
        product_name: 'Apple MacBook Pro',
        product_sku: 'APP-MBP-13',
        quantity: 1,
        unit_price: 1999,
        total_price: 1999
      }
    ],
    payment_method: 'card',
    payment_status: 'paid',
    subtotal: 1999,
    shipping_amount: 5.99,
    discount_amount: 0,
    total_amount: 2004.99,
    shipping_metadata: {
      fee: 5.99,
      tier_name: 'Local (within 10 km)',
      distance_meters: 8548,
      is_free: false,
      reason: '8.5 km away',
      applied_rule: 'distance'
    },
    notes: 'Leave with front desk'
  })
};

fetch('https://api.tybritelabs.com/v1/orders', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.tybritelabs.com/v1/orders",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'customer_email' => 'john.doe@example.com',
    'customer_name' => 'John Doe',
    'customer_phone' => '+12125550142',
    'billing_address' => [
        'street' => '350 Fifth Avenue',
        'city' => 'New York',
        'state' => 'NY',
        'zip' => '10118',
        'country' => 'US'
    ],
    'shipping_address' => [
        'street' => '350 Fifth Avenue',
        'city' => 'New York',
        'state' => 'NY',
        'zip' => '10118',
        'country' => 'US'
    ],
    'items' => [
        [
                'product_id' => '715b8c10-eb11-4289-8c0e-2966e78cf9a5',
                'variant_id' => '15ca5a86-4b1b-47c3-8762-a1aa43941565',
                'product_name' => 'Apple MacBook Pro',
                'product_sku' => 'APP-MBP-13',
                'quantity' => 1,
                'unit_price' => 1999,
                'total_price' => 1999
        ]
    ],
    'payment_method' => 'card',
    'payment_status' => 'paid',
    'subtotal' => 1999,
    'shipping_amount' => 5.99,
    'discount_amount' => 0,
    'total_amount' => 2004.99,
    'shipping_metadata' => [
        'fee' => 5.99,
        'tier_name' => 'Local (within 10 km)',
        'distance_meters' => 8548,
        'is_free' => false,
        'reason' => '8.5 km away',
        'applied_rule' => 'distance'
    ],
    'notes' => 'Leave with front desk'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>",
    "X-Signature: <x-signature>",
    "X-Timestamp: <x-timestamp>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.tybritelabs.com/v1/orders"

	payload := strings.NewReader("{\n  \"customer_email\": \"john.doe@example.com\",\n  \"customer_name\": \"John Doe\",\n  \"customer_phone\": \"+12125550142\",\n  \"billing_address\": {\n    \"street\": \"350 Fifth Avenue\",\n    \"city\": \"New York\",\n    \"state\": \"NY\",\n    \"zip\": \"10118\",\n    \"country\": \"US\"\n  },\n  \"shipping_address\": {\n    \"street\": \"350 Fifth Avenue\",\n    \"city\": \"New York\",\n    \"state\": \"NY\",\n    \"zip\": \"10118\",\n    \"country\": \"US\"\n  },\n  \"items\": [\n    {\n      \"product_id\": \"715b8c10-eb11-4289-8c0e-2966e78cf9a5\",\n      \"variant_id\": \"15ca5a86-4b1b-47c3-8762-a1aa43941565\",\n      \"product_name\": \"Apple MacBook Pro\",\n      \"product_sku\": \"APP-MBP-13\",\n      \"quantity\": 1,\n      \"unit_price\": 1999,\n      \"total_price\": 1999\n    }\n  ],\n  \"payment_method\": \"card\",\n  \"payment_status\": \"paid\",\n  \"subtotal\": 1999,\n  \"shipping_amount\": 5.99,\n  \"discount_amount\": 0,\n  \"total_amount\": 2004.99,\n  \"shipping_metadata\": {\n    \"fee\": 5.99,\n    \"tier_name\": \"Local (within 10 km)\",\n    \"distance_meters\": 8548,\n    \"is_free\": false,\n    \"reason\": \"8.5 km away\",\n    \"applied_rule\": \"distance\"\n  },\n  \"notes\": \"Leave with front desk\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("X-Timestamp", "<x-timestamp>")
	req.Header.Add("X-Signature", "<x-signature>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.tybritelabs.com/v1/orders")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("X-Timestamp", "<x-timestamp>")
  .header("X-Signature", "<x-signature>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"customer_email\": \"john.doe@example.com\",\n  \"customer_name\": \"John Doe\",\n  \"customer_phone\": \"+12125550142\",\n  \"billing_address\": {\n    \"street\": \"350 Fifth Avenue\",\n    \"city\": \"New York\",\n    \"state\": \"NY\",\n    \"zip\": \"10118\",\n    \"country\": \"US\"\n  },\n  \"shipping_address\": {\n    \"street\": \"350 Fifth Avenue\",\n    \"city\": \"New York\",\n    \"state\": \"NY\",\n    \"zip\": \"10118\",\n    \"country\": \"US\"\n  },\n  \"items\": [\n    {\n      \"product_id\": \"715b8c10-eb11-4289-8c0e-2966e78cf9a5\",\n      \"variant_id\": \"15ca5a86-4b1b-47c3-8762-a1aa43941565\",\n      \"product_name\": \"Apple MacBook Pro\",\n      \"product_sku\": \"APP-MBP-13\",\n      \"quantity\": 1,\n      \"unit_price\": 1999,\n      \"total_price\": 1999\n    }\n  ],\n  \"payment_method\": \"card\",\n  \"payment_status\": \"paid\",\n  \"subtotal\": 1999,\n  \"shipping_amount\": 5.99,\n  \"discount_amount\": 0,\n  \"total_amount\": 2004.99,\n  \"shipping_metadata\": {\n    \"fee\": 5.99,\n    \"tier_name\": \"Local (within 10 km)\",\n    \"distance_meters\": 8548,\n    \"is_free\": false,\n    \"reason\": \"8.5 km away\",\n    \"applied_rule\": \"distance\"\n  },\n  \"notes\": \"Leave with front desk\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.tybritelabs.com/v1/orders")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["X-Timestamp"] = '<x-timestamp>'
request["X-Signature"] = '<x-signature>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"customer_email\": \"john.doe@example.com\",\n  \"customer_name\": \"John Doe\",\n  \"customer_phone\": \"+12125550142\",\n  \"billing_address\": {\n    \"street\": \"350 Fifth Avenue\",\n    \"city\": \"New York\",\n    \"state\": \"NY\",\n    \"zip\": \"10118\",\n    \"country\": \"US\"\n  },\n  \"shipping_address\": {\n    \"street\": \"350 Fifth Avenue\",\n    \"city\": \"New York\",\n    \"state\": \"NY\",\n    \"zip\": \"10118\",\n    \"country\": \"US\"\n  },\n  \"items\": [\n    {\n      \"product_id\": \"715b8c10-eb11-4289-8c0e-2966e78cf9a5\",\n      \"variant_id\": \"15ca5a86-4b1b-47c3-8762-a1aa43941565\",\n      \"product_name\": \"Apple MacBook Pro\",\n      \"product_sku\": \"APP-MBP-13\",\n      \"quantity\": 1,\n      \"unit_price\": 1999,\n      \"total_price\": 1999\n    }\n  ],\n  \"payment_method\": \"card\",\n  \"payment_status\": \"paid\",\n  \"subtotal\": 1999,\n  \"shipping_amount\": 5.99,\n  \"discount_amount\": 0,\n  \"total_amount\": 2004.99,\n  \"shipping_metadata\": {\n    \"fee\": 5.99,\n    \"tier_name\": \"Local (within 10 km)\",\n    \"distance_meters\": 8548,\n    \"is_free\": false,\n    \"reason\": \"8.5 km away\",\n    \"applied_rule\": \"distance\"\n  },\n  \"notes\": \"Leave with front desk\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "7f3c1e88-2b4a-4c9e-9d21-5a6b7c8d9e01",
  "order_number": "ORD-20260804-4f2a91",
  "order_status": "processing",
  "payment_status": "paid",
  "total_amount": 324.5
}

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 the Integrations page (Developer section).

Body

application/json

customer_email

string<email>

required

Customer email address. Required.

Example:

"john.doe@example.com"

customer_name

string

required

Customer full name. Required.

Example:

"John Doe"

billing_address

object

required

Billing address. Required.

Show child attributes

shipping_address

object

required

Shipping address. Required.

Show child attributes

items

object[]

required

Order line items (at least one required)

Minimum array length: 1

Provide variant_id OR product_id (at least one). Prefer variant_id — it is the exact variant (SKU) the shopper chose, so pass the same variant_id you put in the cart straight through to the order. If you send only product_id, the order is placed against the product's default variant — convenient for single-variant products, but for a product with multiple variants it may not be the one the shopper selected. When both are sent, variant_id wins (and product_id is resolved from it).

Option 1
Option 2

Show child attributes

payment_method

enum<string>

required

Payment method identifier (required)

Available options:

card,

stripe,

paypal,

paystack,

mpesa,

cash

Example:

"card"

subtotal

number<float>

required

Subtotal before tax and shipping. Required.

Example:

2000

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_phone

string

Customer phone number (optional)

Example:

"+14155550199"

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"

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"

custom_fields

object | null

Values for the merchant's own custom fields on this order, as { field_name: value }. Use this to carry a reference the merchant asked for at checkout — a buyer's purchase-order number, a cost centre, a delivery instruction.

Each value is validated against the merchant's definition: a name that is not defined, a value outside a select field's options, or a number that will not parse is rejected. A rejected field does not fail the order — the order is created and the reason is returned in post_processing_warnings, because the payment has already been taken by that point. Read GET /v1/products/{id}/custom-fields or the order response's custom_fields to discover which fields a merchant has defined.

Example:

{
  "buyer_po": "PO-2026-0819",
  "priority": "Express"
}

shipping_metadata

object | null

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

Show child attributes

gift_card_redemption

object | null

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

apply_store_credit

boolean

Apply the customer's redeemable store credit to this order. When true (and the order has a customer_id), store credit is spent against the order total, capped at the total. The amount actually applied is returned as store_credit_applied. Requires a customer.

Example:

true

store_credit_amount

number<float>

Optional cap on how much store credit to apply. When omitted (and apply_store_credit is true) up to the full order total is applied. The applied amount never exceeds the available balance or the total.

Example:

25

order_number

string

Your own order reference. When omitted, Galactic Core generates one. Use this to keep order numbers aligned with a system you already run.

Example:

"ORD-10432"

currency

string

ISO 4217 currency code the order is priced in. When omitted, the store's default storefront currency is used. Set it when you present prices in a currency the shopper selected, so the order is recorded in the same currency it was paid in.

Example:

"USD"

reservation_ids

string[]

Stock reservation ids returned by POST /v1/checkout/reserve. Supplying them commits the stock already held for this shopper instead of decrementing it again, which is what keeps a high-demand drop from overselling between reservation and payment.

Example:

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

shipping_latitude

number<float>

Delivery latitude, used to resolve the delivery zone or distance tier that prices shipping. Send it with shipping_longitude when the shopper's coordinates are known; the server re-derives the shipping cost from them rather than trusting a client total.

Example:

40.7128

shipping_longitude

number<float>

Delivery longitude. See shipping_latitude.

Example:

-74.006

shippo_rate_id

string

The id of the shipping rate the shopper chose, when rates came from a multi-carrier quote. The rate is re-fetched and validated server-side before it is charged, so a modified or stale rate is rejected rather than honoured.

Example:

"rate_8f2c1a9b4d7e4f109a3b2c5e7f1d0a44"

attribution

object | null

Where this order came from, recorded for the merchant's analytics. Accepts the fields below; the same fields are also read from the top level of the request body if you already send them there. Promotions that actually applied are recorded from the server-validated result, so promotion_ids never inflates what a shopper received.

Show child attributes

gclid

string | null

Google ad click id, when the shopper arrived from a Google ad. On a paid order this lets the merchant's Google advertising get credit for the sale. Forward the true captured value; omit if not present.

Example:

"Cj0KCQiA...gclid"

fbclid

string | null

Meta (Facebook & Instagram) ad click id, when the shopper arrived from a Meta ad. On a paid order this lets the merchant's Meta advertising get credit for the sale. The conversion is sent server-side (Conversions API) and de-duplicated against the storefront's Meta Pixel by the order id, so it counts even when the browser blocks the Pixel. Forward the true captured value; omit if not present.

Example:

"IwAR1abc...fbclid"

Advertising privacy-consent state captured at checkout, used to decide whether a conversion may be reported to an ad platform for this shopper's region (required for EEA shoppers; UK/Swiss records are not dropped for a missing signal). Always forward the true captured values — never guess.

Show child attributes

Response

The Idempotency-Key has already been used for this store, so the order it created is returned instead of a new one being made. The body is the order resource, exactly as GET /v1/orders/{id} would return it — note this differs from the 201 envelope, which nests the order under an order property.

Retrying a create with the same key is always safe: concurrent retries resolve to the same order, and only the first request receives 201.

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

Create order

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_email": "john.doe@example.com",
  "customer_name": "John Doe",
  "customer_phone": "+12125550142",
  "billing_address": {
    "street": "350 Fifth Avenue",
    "city": "New York",
    "state": "NY",
    "zip": "10118",
    "country": "US"
  },
  "shipping_address": {
    "street": "350 Fifth Avenue",
    "city": "New York",
    "state": "NY",
    "zip": "10118",
    "country": "US"
  },
  "items": [
    {
      "product_id": "715b8c10-eb11-4289-8c0e-2966e78cf9a5",
      "variant_id": "15ca5a86-4b1b-47c3-8762-a1aa43941565",
      "product_name": "Apple MacBook Pro",
      "product_sku": "APP-MBP-13",
      "quantity": 1,
      "unit_price": 1999,
      "total_price": 1999
    }
  ],
  "payment_method": "card",
  "payment_status": "paid",
  "subtotal": 1999,
  "shipping_amount": 5.99,
  "discount_amount": 0,
  "total_amount": 2004.99,
  "shipping_metadata": {
    "fee": 5.99,
    "tier_name": "Local (within 10 km)",
    "distance_meters": 8548,
    "is_free": false,
    "reason": "8.5 km away",
    "applied_rule": "distance"
  },
  "notes": "Leave with front desk"
}
'

import requests

url = "https://api.tybritelabs.com/v1/orders"

payload = {
    "customer_email": "john.doe@example.com",
    "customer_name": "John Doe",
    "customer_phone": "+12125550142",
    "billing_address": {
        "street": "350 Fifth Avenue",
        "city": "New York",
        "state": "NY",
        "zip": "10118",
        "country": "US"
    },
    "shipping_address": {
        "street": "350 Fifth Avenue",
        "city": "New York",
        "state": "NY",
        "zip": "10118",
        "country": "US"
    },
    "items": [
        {
            "product_id": "715b8c10-eb11-4289-8c0e-2966e78cf9a5",
            "variant_id": "15ca5a86-4b1b-47c3-8762-a1aa43941565",
            "product_name": "Apple MacBook Pro",
            "product_sku": "APP-MBP-13",
            "quantity": 1,
            "unit_price": 1999,
            "total_price": 1999
        }
    ],
    "payment_method": "card",
    "payment_status": "paid",
    "subtotal": 1999,
    "shipping_amount": 5.99,
    "discount_amount": 0,
    "total_amount": 2004.99,
    "shipping_metadata": {
        "fee": 5.99,
        "tier_name": "Local (within 10 km)",
        "distance_meters": 8548,
        "is_free": False,
        "reason": "8.5 km away",
        "applied_rule": "distance"
    },
    "notes": "Leave with front desk"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "X-Timestamp": "<x-timestamp>",
    "X-Signature": "<x-signature>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    'X-Timestamp': '<x-timestamp>',
    'X-Signature': '<x-signature>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    customer_email: 'john.doe@example.com',
    customer_name: 'John Doe',
    customer_phone: '+12125550142',
    billing_address: {
      street: '350 Fifth Avenue',
      city: 'New York',
      state: 'NY',
      zip: '10118',
      country: 'US'
    },
    shipping_address: {
      street: '350 Fifth Avenue',
      city: 'New York',
      state: 'NY',
      zip: '10118',
      country: 'US'
    },
    items: [
      {
        product_id: '715b8c10-eb11-4289-8c0e-2966e78cf9a5',
        variant_id: '15ca5a86-4b1b-47c3-8762-a1aa43941565',
        product_name: 'Apple MacBook Pro',
        product_sku: 'APP-MBP-13',
        quantity: 1,
        unit_price: 1999,
        total_price: 1999
      }
    ],
    payment_method: 'card',
    payment_status: 'paid',
    subtotal: 1999,
    shipping_amount: 5.99,
    discount_amount: 0,
    total_amount: 2004.99,
    shipping_metadata: {
      fee: 5.99,
      tier_name: 'Local (within 10 km)',
      distance_meters: 8548,
      is_free: false,
      reason: '8.5 km away',
      applied_rule: 'distance'
    },
    notes: 'Leave with front desk'
  })
};

fetch('https://api.tybritelabs.com/v1/orders', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.tybritelabs.com/v1/orders",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'customer_email' => 'john.doe@example.com',
    'customer_name' => 'John Doe',
    'customer_phone' => '+12125550142',
    'billing_address' => [
        'street' => '350 Fifth Avenue',
        'city' => 'New York',
        'state' => 'NY',
        'zip' => '10118',
        'country' => 'US'
    ],
    'shipping_address' => [
        'street' => '350 Fifth Avenue',
        'city' => 'New York',
        'state' => 'NY',
        'zip' => '10118',
        'country' => 'US'
    ],
    'items' => [
        [
                'product_id' => '715b8c10-eb11-4289-8c0e-2966e78cf9a5',
                'variant_id' => '15ca5a86-4b1b-47c3-8762-a1aa43941565',
                'product_name' => 'Apple MacBook Pro',
                'product_sku' => 'APP-MBP-13',
                'quantity' => 1,
                'unit_price' => 1999,
                'total_price' => 1999
        ]
    ],
    'payment_method' => 'card',
    'payment_status' => 'paid',
    'subtotal' => 1999,
    'shipping_amount' => 5.99,
    'discount_amount' => 0,
    'total_amount' => 2004.99,
    'shipping_metadata' => [
        'fee' => 5.99,
        'tier_name' => 'Local (within 10 km)',
        'distance_meters' => 8548,
        'is_free' => false,
        'reason' => '8.5 km away',
        'applied_rule' => 'distance'
    ],
    'notes' => 'Leave with front desk'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>",
    "X-Signature: <x-signature>",
    "X-Timestamp: <x-timestamp>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.tybritelabs.com/v1/orders"

	payload := strings.NewReader("{\n  \"customer_email\": \"john.doe@example.com\",\n  \"customer_name\": \"John Doe\",\n  \"customer_phone\": \"+12125550142\",\n  \"billing_address\": {\n    \"street\": \"350 Fifth Avenue\",\n    \"city\": \"New York\",\n    \"state\": \"NY\",\n    \"zip\": \"10118\",\n    \"country\": \"US\"\n  },\n  \"shipping_address\": {\n    \"street\": \"350 Fifth Avenue\",\n    \"city\": \"New York\",\n    \"state\": \"NY\",\n    \"zip\": \"10118\",\n    \"country\": \"US\"\n  },\n  \"items\": [\n    {\n      \"product_id\": \"715b8c10-eb11-4289-8c0e-2966e78cf9a5\",\n      \"variant_id\": \"15ca5a86-4b1b-47c3-8762-a1aa43941565\",\n      \"product_name\": \"Apple MacBook Pro\",\n      \"product_sku\": \"APP-MBP-13\",\n      \"quantity\": 1,\n      \"unit_price\": 1999,\n      \"total_price\": 1999\n    }\n  ],\n  \"payment_method\": \"card\",\n  \"payment_status\": \"paid\",\n  \"subtotal\": 1999,\n  \"shipping_amount\": 5.99,\n  \"discount_amount\": 0,\n  \"total_amount\": 2004.99,\n  \"shipping_metadata\": {\n    \"fee\": 5.99,\n    \"tier_name\": \"Local (within 10 km)\",\n    \"distance_meters\": 8548,\n    \"is_free\": false,\n    \"reason\": \"8.5 km away\",\n    \"applied_rule\": \"distance\"\n  },\n  \"notes\": \"Leave with front desk\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("X-Timestamp", "<x-timestamp>")
	req.Header.Add("X-Signature", "<x-signature>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.tybritelabs.com/v1/orders")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("X-Timestamp", "<x-timestamp>")
  .header("X-Signature", "<x-signature>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"customer_email\": \"john.doe@example.com\",\n  \"customer_name\": \"John Doe\",\n  \"customer_phone\": \"+12125550142\",\n  \"billing_address\": {\n    \"street\": \"350 Fifth Avenue\",\n    \"city\": \"New York\",\n    \"state\": \"NY\",\n    \"zip\": \"10118\",\n    \"country\": \"US\"\n  },\n  \"shipping_address\": {\n    \"street\": \"350 Fifth Avenue\",\n    \"city\": \"New York\",\n    \"state\": \"NY\",\n    \"zip\": \"10118\",\n    \"country\": \"US\"\n  },\n  \"items\": [\n    {\n      \"product_id\": \"715b8c10-eb11-4289-8c0e-2966e78cf9a5\",\n      \"variant_id\": \"15ca5a86-4b1b-47c3-8762-a1aa43941565\",\n      \"product_name\": \"Apple MacBook Pro\",\n      \"product_sku\": \"APP-MBP-13\",\n      \"quantity\": 1,\n      \"unit_price\": 1999,\n      \"total_price\": 1999\n    }\n  ],\n  \"payment_method\": \"card\",\n  \"payment_status\": \"paid\",\n  \"subtotal\": 1999,\n  \"shipping_amount\": 5.99,\n  \"discount_amount\": 0,\n  \"total_amount\": 2004.99,\n  \"shipping_metadata\": {\n    \"fee\": 5.99,\n    \"tier_name\": \"Local (within 10 km)\",\n    \"distance_meters\": 8548,\n    \"is_free\": false,\n    \"reason\": \"8.5 km away\",\n    \"applied_rule\": \"distance\"\n  },\n  \"notes\": \"Leave with front desk\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.tybritelabs.com/v1/orders")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["X-Timestamp"] = '<x-timestamp>'
request["X-Signature"] = '<x-signature>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"customer_email\": \"john.doe@example.com\",\n  \"customer_name\": \"John Doe\",\n  \"customer_phone\": \"+12125550142\",\n  \"billing_address\": {\n    \"street\": \"350 Fifth Avenue\",\n    \"city\": \"New York\",\n    \"state\": \"NY\",\n    \"zip\": \"10118\",\n    \"country\": \"US\"\n  },\n  \"shipping_address\": {\n    \"street\": \"350 Fifth Avenue\",\n    \"city\": \"New York\",\n    \"state\": \"NY\",\n    \"zip\": \"10118\",\n    \"country\": \"US\"\n  },\n  \"items\": [\n    {\n      \"product_id\": \"715b8c10-eb11-4289-8c0e-2966e78cf9a5\",\n      \"variant_id\": \"15ca5a86-4b1b-47c3-8762-a1aa43941565\",\n      \"product_name\": \"Apple MacBook Pro\",\n      \"product_sku\": \"APP-MBP-13\",\n      \"quantity\": 1,\n      \"unit_price\": 1999,\n      \"total_price\": 1999\n    }\n  ],\n  \"payment_method\": \"card\",\n  \"payment_status\": \"paid\",\n  \"subtotal\": 1999,\n  \"shipping_amount\": 5.99,\n  \"discount_amount\": 0,\n  \"total_amount\": 2004.99,\n  \"shipping_metadata\": {\n    \"fee\": 5.99,\n    \"tier_name\": \"Local (within 10 km)\",\n    \"distance_meters\": 8548,\n    \"is_free\": false,\n    \"reason\": \"8.5 km away\",\n    \"applied_rule\": \"distance\"\n  },\n  \"notes\": \"Leave with front desk\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "7f3c1e88-2b4a-4c9e-9d21-5a6b7c8d9e01",
  "order_number": "ORD-20260804-4f2a91",
  "order_status": "processing",
  "payment_status": "paid",
  "total_amount": 324.5
}

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

Create order

Authorizations

Headers

Body

Response