Guides
Place an Order

Place an Order

This guide walks through creating an order programmatically.

Prerequisites

  • An API key with scopes catalog:read and orders:write
  • A cart_id from the commerce cart flow (created via the storefront or /commerce-api/v1/cart)

Flow

  1. Look up the product (optional — to display to your user)
  2. Add items to a cart (via the commerce-api cart endpoints)
  3. POST to /orders with billing, shipping, and payment info
  4. Store the returned order number for the customer

Example (Node.js)

const API = 'https://api.spectradiag.com/api/v1';
const headers = {
  'Authorization': 'Bearer spk_live_xxx',
  'Content-Type': 'application/json',
};
 
// Assume you already have a cart_id with items in it.
 
const response = await fetch(`${API}/orders`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    cart_id: 'abc-123-xyz',
    billing: {
      name: 'Alice Buyer',
      email: 'alice@example.com',
      phone: '555-1234',
      address1: '123 Main St',
      city: 'Brooklyn',
      state: 'NY',
      zip: '11201',
      country: 'US',
    },
    shipping: {
      name: 'Alice Buyer',
      address1: '123 Main St',
      city: 'Brooklyn',
      state: 'NY',
      zip: '11201',
      country: 'US',
    },
    shipping_method: {
      method: 'ground',
      carrier: 'UPS',
      service: 'UPS Ground',
      cost: 8.99,
    },
    payment: {
      method: 'stripe',
      gateway_id: 'pi_xxx', // Stripe payment intent ID
    },
  }),
});
 
const { data: order } = await response.json();
console.log('Order created:', order.order_number);

Important notes

  • Tax is calculated server-side — ignore any tax_amount you send; the API recomputes it from the shipping state and tenant tax config.
  • Promo codes — include payment.promo_code to apply a promotion. Validation happens server-side.
  • Gift cards — include payment.gift_card_code to redeem a gift card balance.
  • Test orders — if you use an spk_test_ key, the order is flagged is_test = true and doesn't trigger customer emails.

Response

{
  "success": true,
  "data": {
    "id": 1234,
    "order_number": "ORD-20260515-0042",
    "status": "pending",
    "payment_status": "captured",
    "grand_total": 1234.56,
    "is_test": false,
    "items": [...]
  }
}

Next steps

  • Listen for order.created webhooks to sync the order into your system
  • Listen for order.shipped and order.delivered to update your UI
  • Use PATCH /orders/{id}/status to change status later
Guides OverviewLookup Inventory by IMEI