Create a draft order

Creates a new draft order in one shot. Customer, items, addresses, currency, market, channel, locale, notes, metadata, and a coupon code can all be provided inline.

Setting preferred_stock_location_id pins the order’s preferred fulfillment location — Order Routing’s built-in PreferredLocation rule consumes it when picking which stock location ships each shipment.

Invalid coupon codes are non-fatal — the order is created and the failure is reported on the service result (not in the API response body for now).

Required scope: write_orders (for API-key authentication).

POST

api

admin

orders

Spree Admin SDK

import { createAdminClient } from '@spree/admin-sdk'

const client = createAdminClient({
  baseUrl: 'https://your-store.com',
  secretKey: 'sk_xxx',
})

// One-shot order create: customer, items, addresses, market, channel,
// notes, metadata, and a coupon code in a single call. Everything
// except `email` is optional.
const order = await client.orders.create({
  email: 'jane@example.com',
  customer_id: 'cus_UkLWZg9DAJ',           // Existing customer; omit for guest orders
  use_customer_default_address: false,     // true to copy the customer's saved addresses

  currency: 'USD',
  market_id: 'mkt_UkLWZg9DAJ',
  channel_id: 'ch_UkLWZg9DAJ',             // Optional — defaults to the store's primary channel
  locale: 'en-US',

  // Pin the order's preferred fulfillment location. Order Routing's
  // built-in PreferredLocation rule ranks this location first when
  // it stocks the cart's items; if it doesn't, routing falls back
  // to the next rule (Minimize Splits → Default Location).
  preferred_stock_location_id: 'sloc_UkLWZg9DAJ',

  customer_note: 'Please leave at the front desk.',
  internal_note: 'VIP customer — handle with care.',
  metadata: {
    external_reference: 'subscription_invoice_2026_04',
    source: 'recurring-engine',
  },

  // Items: each variant_id + quantity. Optional metadata per line.
  items: [
    { variant_id: 'variant_k5nR8xLq', quantity: 2 },
    { variant_id: 'variant_QXyZ12abCD', quantity: 1, metadata: { gift: true } },
  ],

  // Provide addresses inline OR by ID (existing customer addresses).
  shipping_address: {
    first_name: 'Jane',
    last_name: 'Doe',
    address1: '350 Fifth Avenue',
    address2: 'Floor 42',
    city: 'New York',
    postal_code: '10118',
    country_iso: 'US',
    state_abbr: 'NY',
    phone: '+1 212 555 1234',
    company: 'Acme Inc.',
  },
  // shipping_address_id: 'addr_UkLWZg9DAJ',  // alternative to inline

  billing_address: {
    first_name: 'Jane',
    last_name: 'Doe',
    address1: '350 Fifth Avenue',
    city: 'New York',
    postal_code: '10118',
    country_iso: 'US',
    state_abbr: 'NY',
    phone: '+1 212 555 1234',
  },
  // billing_address_id: 'addr_UkLWZg9DAJ',

  // Optional. Invalid codes are non-fatal — the order is created either way.
  coupon_code: 'WELCOME10',
})

spree api post /orders -d '{"email":"jane@example.com","customer_id":"cus_UkLWZg9DAJ","use_customer_default_address":false,"currency":"USD","market_id":"mkt_UkLWZg9DAJ","channel_id":"ch_UkLWZg9DAJ","locale":"en-US","preferred_stock_location_id":"sloc_UkLWZg9DAJ","customer_note":"Please leave at the front desk.","internal_note":"VIP customer — handle with care.","metadata":{"external_reference":"subscription_invoice_2026_04","source":"recurring-engine"},"items":[{"variant_id":"variant_k5nR8xLq","quantity":2},{"variant_id":"variant_QXyZ12abCD","quantity":1,"metadata":{"gift":true}}],"shipping_address":{"first_name":"Jane","last_name":"Doe","address1":"350 Fifth Avenue","address2":"Floor 42","city":"New York","postal_code":"10118","country_iso":"US","state_abbr":"NY","phone":"+1 212 555 1234","company":"Acme Inc."},"billing_address":{"first_name":"Jane","last_name":"Doe","address1":"350 Fifth Avenue","city":"New York","postal_code":"10118","country_iso":"US","state_abbr":"NY","phone":"+1 212 555 1234"},"coupon_code":"WELCOME10"}'

{
  "id": "or_gbHJdmfrXB",
  "market_id": null,
  "channel_id": "ch_UkLWZg9DAJ",
  "number": "R168714331",
  "email": "pinned@example.com",
  "customer_note": null,
  "currency": "USD",
  "locale": "en",
  "total_quantity": 0,
  "fulfillment_status": null,
  "payment_status": null,
  "completed_at": null,
  "item_total": "0.0",
  "display_item_total": "$0.00",
  "adjustment_total": "0.0",
  "display_adjustment_total": "$0.00",
  "discount_total": "0.0",
  "display_discount_total": "$0.00",
  "tax_total": "0.0",
  "display_tax_total": "$0.00",
  "included_tax_total": "0.0",
  "display_included_tax_total": "$0.00",
  "additional_tax_total": "0.0",
  "display_additional_tax_total": "$0.00",
  "total": "0.0",
  "display_total": "$0.00",
  "gift_card_total": "0.0",
  "display_gift_card_total": "$0.00",
  "amount_due": "0.0",
  "display_amount_due": "$0.00",
  "delivery_total": "0.0",
  "display_delivery_total": "$0.00",
  "store_credit_total": "0.0",
  "display_store_credit_total": "$0.00",
  "covered_by_store_credit": false,
  "gift_card": null,
  "market": null,
  "status": "draft",
  "last_ip_address": null,
  "considered_risky": false,
  "confirmation_delivered": false,
  "store_owner_notification_delivered": null,
  "payment_total": "0.0",
  "display_payment_total": "$0.00",
  "metadata": {},
  "canceled_at": null,
  "approved_at": null,
  "created_at": "2026-07-24T18:11:42.859Z",
  "updated_at": "2026-07-24T18:11:42.867Z",
  "preferred_stock_location_id": "sloc_UkLWZg9DAJ",
  "tags": [],
  "internal_note": null,
  "approver_id": null,
  "canceler_id": null,
  "created_by_id": null,
  "customer_id": null
}

Authorizations

x-spree-api-key

string

header

required

Secret API key for admin access

Authorization

string

header

required

JWT token for admin user authentication

Headers

x-spree-api-key

string

required

Authorization

string

required

Bearer token for admin authentication

Body

application/json

string

Example:

"customer@example.com"

customer_id

string

Customer ID. Alias: user_id (legacy).

use_customer_default_address

boolean

When true with customer_id, copies the customer's saved billing/shipping addresses onto the order.

currency

string

Example:

"USD"

market_id

string

Market ID

channel_id

string

Channel ID. Defaults to the store primary channel when omitted.

preferred_stock_location_id

string

Stock Location ID to prefer for fulfillment. Order Routing's built-in PreferredLocation rule reads this and ranks the location first; routing falls back to the next rule when the preferred location can't cover the cart.

locale

string

Example:

"en-US"

customer_note

string

Public, customer-visible note

internal_note

string

Staff-only note

metadata

object

Arbitrary key/value metadata

shipping_address

object

Show child attributes

shipping_address_id

string

Existing customer address ID

billing_address

object

Show child attributes

billing_address_id

string

Existing customer address ID

items

object[]

Show child attributes

coupon_code

string

Optional. Applied non-fatally; invalid codes do not block creation.

Response

201 - application/json

order created with preferred_stock_location_id

List orders

Show an order

⌘I

Spree Admin SDK

import { createAdminClient } from '@spree/admin-sdk'

const client = createAdminClient({
  baseUrl: 'https://your-store.com',
  secretKey: 'sk_xxx',
})

// One-shot order create: customer, items, addresses, market, channel,
// notes, metadata, and a coupon code in a single call. Everything
// except `email` is optional.
const order = await client.orders.create({
  email: 'jane@example.com',
  customer_id: 'cus_UkLWZg9DAJ',           // Existing customer; omit for guest orders
  use_customer_default_address: false,     // true to copy the customer's saved addresses

  currency: 'USD',
  market_id: 'mkt_UkLWZg9DAJ',
  channel_id: 'ch_UkLWZg9DAJ',             // Optional — defaults to the store's primary channel
  locale: 'en-US',

  // Pin the order's preferred fulfillment location. Order Routing's
  // built-in PreferredLocation rule ranks this location first when
  // it stocks the cart's items; if it doesn't, routing falls back
  // to the next rule (Minimize Splits → Default Location).
  preferred_stock_location_id: 'sloc_UkLWZg9DAJ',

  customer_note: 'Please leave at the front desk.',
  internal_note: 'VIP customer — handle with care.',
  metadata: {
    external_reference: 'subscription_invoice_2026_04',
    source: 'recurring-engine',
  },

  // Items: each variant_id + quantity. Optional metadata per line.
  items: [
    { variant_id: 'variant_k5nR8xLq', quantity: 2 },
    { variant_id: 'variant_QXyZ12abCD', quantity: 1, metadata: { gift: true } },
  ],

  // Provide addresses inline OR by ID (existing customer addresses).
  shipping_address: {
    first_name: 'Jane',
    last_name: 'Doe',
    address1: '350 Fifth Avenue',
    address2: 'Floor 42',
    city: 'New York',
    postal_code: '10118',
    country_iso: 'US',
    state_abbr: 'NY',
    phone: '+1 212 555 1234',
    company: 'Acme Inc.',
  },
  // shipping_address_id: 'addr_UkLWZg9DAJ',  // alternative to inline

  billing_address: {
    first_name: 'Jane',
    last_name: 'Doe',
    address1: '350 Fifth Avenue',
    city: 'New York',
    postal_code: '10118',
    country_iso: 'US',
    state_abbr: 'NY',
    phone: '+1 212 555 1234',
  },
  // billing_address_id: 'addr_UkLWZg9DAJ',

  // Optional. Invalid codes are non-fatal — the order is created either way.
  coupon_code: 'WELCOME10',
})

spree api post /orders -d '{"email":"jane@example.com","customer_id":"cus_UkLWZg9DAJ","use_customer_default_address":false,"currency":"USD","market_id":"mkt_UkLWZg9DAJ","channel_id":"ch_UkLWZg9DAJ","locale":"en-US","preferred_stock_location_id":"sloc_UkLWZg9DAJ","customer_note":"Please leave at the front desk.","internal_note":"VIP customer — handle with care.","metadata":{"external_reference":"subscription_invoice_2026_04","source":"recurring-engine"},"items":[{"variant_id":"variant_k5nR8xLq","quantity":2},{"variant_id":"variant_QXyZ12abCD","quantity":1,"metadata":{"gift":true}}],"shipping_address":{"first_name":"Jane","last_name":"Doe","address1":"350 Fifth Avenue","address2":"Floor 42","city":"New York","postal_code":"10118","country_iso":"US","state_abbr":"NY","phone":"+1 212 555 1234","company":"Acme Inc."},"billing_address":{"first_name":"Jane","last_name":"Doe","address1":"350 Fifth Avenue","city":"New York","postal_code":"10118","country_iso":"US","state_abbr":"NY","phone":"+1 212 555 1234"},"coupon_code":"WELCOME10"}'

{
  "id": "or_gbHJdmfrXB",
  "market_id": null,
  "channel_id": "ch_UkLWZg9DAJ",
  "number": "R168714331",
  "email": "pinned@example.com",
  "customer_note": null,
  "currency": "USD",
  "locale": "en",
  "total_quantity": 0,
  "fulfillment_status": null,
  "payment_status": null,
  "completed_at": null,
  "item_total": "0.0",
  "display_item_total": "$0.00",
  "adjustment_total": "0.0",
  "display_adjustment_total": "$0.00",
  "discount_total": "0.0",
  "display_discount_total": "$0.00",
  "tax_total": "0.0",
  "display_tax_total": "$0.00",
  "included_tax_total": "0.0",
  "display_included_tax_total": "$0.00",
  "additional_tax_total": "0.0",
  "display_additional_tax_total": "$0.00",
  "total": "0.0",
  "display_total": "$0.00",
  "gift_card_total": "0.0",
  "display_gift_card_total": "$0.00",
  "amount_due": "0.0",
  "display_amount_due": "$0.00",
  "delivery_total": "0.0",
  "display_delivery_total": "$0.00",
  "store_credit_total": "0.0",
  "display_store_credit_total": "$0.00",
  "covered_by_store_credit": false,
  "gift_card": null,
  "market": null,
  "status": "draft",
  "last_ip_address": null,
  "considered_risky": false,
  "confirmation_delivered": false,
  "store_owner_notification_delivered": null,
  "payment_total": "0.0",
  "display_payment_total": "$0.00",
  "metadata": {},
  "canceled_at": null,
  "approved_at": null,
  "created_at": "2026-07-24T18:11:42.859Z",
  "updated_at": "2026-07-24T18:11:42.867Z",
  "preferred_stock_location_id": "sloc_UkLWZg9DAJ",
  "tags": [],
  "internal_note": null,
  "approver_id": null,
  "canceler_id": null,
  "created_by_id": null,
  "customer_id": null
}

API basics

Endpoints

Create a draft order

Authorizations

Headers

Body

Response