Skip to main content
POST
Create order

Authorizations

​
Authorization
string
header
required

API Key Authentication

Use your API key in the Authorization header:

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: every write a shopper does not make for themselves, authentication, payment verification, AI recommendations

Publishable Keys (Client-Safe):

  • Format: tybrite_pk_live_* (production) or tybrite_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

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

​
items
object[]
required

Order line items (at least one, at most 100)

Required array length: 1 - 100 elements

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

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

​
shipping_address
object

Shipping address. Required for a delivery order. On a pickup order it is not needed: the collection location's address is stored as the order's shipping address, with type: pickup.

​
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,
confirmed,
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:
​
shipping_metadata
object | null

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

​
gift_card_redemption
object | null

Optional gift card to redeem towards this order

​
promotion_usages
object[] | null

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

​
campaign_ids
string<uuid>[] | null

Campaigns to apply to this order, by id. The discount each one grants is computed server-side against the campaign's own rules and its remaining budget, so a campaign that has spent its budget adds nothing. Once the order is paid, what each campaign granted is drawn from its budget.

Example:
​
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. On a pending order the ids are kept with the order: they are committed when the order is paid and released when it is cancelled or its payment fails. Only holds on the order's own items are committed. At most 100 ids.

Example:
​
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 a carrier option from the store's connected carrier account. Equivalent to shipping_rate_id with shipping_rate_source: shippo. The option is fetched again and checked before it is charged, so a modified, stale or foreign option is rejected.

Example:

"rate_8f2c1a9b4d7e4f109a3b2c5e7f1d0a44"

​
shipping_rate_id
string

The id of the carrier option the shopper chose, as returned in rates[] by POST /v1/shipping/calculate. Send with shipping_rate_source.

Example:

"rate_8f2c1a9b4d7e4f109a3b2c5e7f1d0a44"

​
shipping_rate_source
enum<string>

Where the chosen option came from — its source in rates[]: the store's carrier account (shippo) or its custom shipping extension (custom).

Available options:
shippo,
custom
Example:

"shippo"

​
shipping_parcel
object

The parcel the option was quoted for. Required with shipping_rate_source: custom, because the extension is asked for its options again to check the one chosen.

​
fulfillment_method
enum<string>
default:delivery

How the shopper receives the order: delivered to shipping_address, or collected at one of the store's locations.

Available options:
delivery,
pickup
Example:

"delivery"

​
pickup_location_id
string<uuid>

The location to collect from, on a pickup order — a location id from pickup_locations (GET /v1/shipping/zones) or from a pickup option's location (POST /v1/shipping/calculate). When omitted on a pickup order, the store's primary pickup location is used.

Example:

"3d5c7a10-8b2e-4f61-9c4d-1a2b3c4d5e6f"

​
shipping_option_id
string

The id of the option the shopper chose from options[] in POST /v1/shipping/calculate — place for standard delivery, opt:<id> for a named delivery option such as Express, or pickup:<location id> on a pickup order. shipping_amount must equal that option's fee for this order.

Maximum string length: 60
Example:

"opt:9a1f3c2e-5b7d-4e8a-a2c4-6d8e0f1a3b5c"

​
shipping_address_from
object

The ship-from address the option was quoted with, when one was sent to POST /v1/shipping/calculate as address_from.

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

​
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, and is kept on the order so the merchant's own reports can attribute revenue and profit to the ad that earned it rather than relying on the ad platform's account. 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. It is kept on the order so the merchant's own reports can attribute revenue and profit to the ad that earned it. Forward the true captured value; omit if not present.

Example:

"IwAR1abc...fbclid"

​
ad_consent
object | null

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.

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.

​
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,
confirmed,
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.

​
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
​
shipping_address
object

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.

​
fulfillment_method
enum<string>

Whether the order is delivered to the shopper or collected at one of the store's locations.

Available options:
delivery,
pickup
Example:

"delivery"

​
pickup_location_id
string<uuid> | null

The location the shopper collects from, on a pickup order. Null on a delivery order.

Example:

null

​
fulfillment_location_id
string<uuid> | 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.

Example:

"7b2e9c41-0d3f-4a58-b6e1-2f4a6c8e0b13"

​
shipping_option_id
string | null

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.

Example:

"place"

​
items
object[]
​
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.

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

​
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

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.