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.',
  // Rich text: send HTML. Reads return this as plain text, plus
  // `internal_note_html` with the markup.
  internal_note: '<p>VIP customer — handle with care.</p>',
  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_code: 'US',
    state_code: '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_code: 'US',
    state_code: '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":"<p>VIP customer — handle with care.</p>","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_code":"US","state_code":"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_code":"US","state_code":"NY","phone":"+1 212 555 1234"},"coupon_code":"WELCOME10"}'

{
  "id": "or_gbHJdmfrXB",
  "market_id": "mkt_UkLWZg9DAJ",
  "withdrawal_period_ends_at": null,
  "within_withdrawal_period": false,
  "shipping_eq_billing_address": false,
  "cart_id": null,
  "channel_id": "ch_UkLWZg9DAJ",
  "company_id": null,
  "company_name": null,
  "po_document_filename": null,
  "po_document_byte_size": null,
  "number": "R1002",
  "email": "pinned@example.com",
  "customer_note": null,
  "po_number": null,
  "currency": "USD",
  "locale": "en",
  "total_quantity": 0,
  "coupon_code": null,
  "fulfillment_status": null,
  "payment_status": null,
  "completed_at": null,
  "item_total": "0.00",
  "discount_total": "0.00",
  "tax_total": "0.00",
  "included_tax_total": "0.00",
  "additional_tax_total": "0.00",
  "delivery_total": "0.00",
  "fee_total": "0.00",
  "gift_card_total": "0.00",
  "store_credit_total": "0.00",
  "total": "0.00",
  "amount_due": "0.00",
  "covered_by_store_credit": false,
  "adjustment_total": "0.00",
  "gift_card": null,
  "market": {
    "id": "mkt_UkLWZg9DAJ",
    "name": "United States",
    "currency": "USD",
    "default_locale": "en",
    "tax_inclusive": false,
    "default": true,
    "country_codes": [
      "US"
    ],
    "supported_locales": [
      "en"
    ],
    "created_at": "2026-01-15T12:00:00.000Z",
    "updated_at": "2026-01-15T12:00:00.000Z",
    "tax_provider": null
  },
  "external_references": {},
  "status": "draft",
  "last_ip_address": null,
  "considered_risky": false,
  "confirmation_delivered": false,
  "store_owner_notification_delivered": null,
  "metadata": {},
  "cancel_note": null,
  "canceled_at": null,
  "approved_at": null,
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z",
  "payment_total": "0.00",
  "commission_amount_total": "0.00",
  "commission_tax_total": "0.00",
  "commission_total": "0.00",
  "preferred_stock_location_id": "sloc_UkLWZg9DAJ",
  "po_document_url": null,
  "seller_id": null,
  "order_group_id": null,
  "tags": [],
  "internal_note": null,
  "internal_note_html": null,
  "approver_id": null,
  "approver_type": null,
  "canceler_id": null,
  "canceler_type": null,
  "created_by_id": "adm_UkLWZg9DAJ",
  "created_by_type": "admin_user",
  "cancel_reason_id": null,
  "cancel_reason_name": null,
  "customer_id": null,
  "freight_summary": null
}

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.',
  // Rich text: send HTML. Reads return this as plain text, plus
  // `internal_note_html` with the markup.
  internal_note: '<p>VIP customer — handle with care.</p>',
  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_code: 'US',
    state_code: '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_code: 'US',
    state_code: '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":"<p>VIP customer — handle with care.</p>","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_code":"US","state_code":"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_code":"US","state_code":"NY","phone":"+1 212 555 1234"},"coupon_code":"WELCOME10"}'

{
  "id": "or_gbHJdmfrXB",
  "market_id": "mkt_UkLWZg9DAJ",
  "withdrawal_period_ends_at": null,
  "within_withdrawal_period": false,
  "shipping_eq_billing_address": false,
  "cart_id": null,
  "channel_id": "ch_UkLWZg9DAJ",
  "company_id": null,
  "company_name": null,
  "po_document_filename": null,
  "po_document_byte_size": null,
  "number": "R1002",
  "email": "pinned@example.com",
  "customer_note": null,
  "po_number": null,
  "currency": "USD",
  "locale": "en",
  "total_quantity": 0,
  "coupon_code": null,
  "fulfillment_status": null,
  "payment_status": null,
  "completed_at": null,
  "item_total": "0.00",
  "discount_total": "0.00",
  "tax_total": "0.00",
  "included_tax_total": "0.00",
  "additional_tax_total": "0.00",
  "delivery_total": "0.00",
  "fee_total": "0.00",
  "gift_card_total": "0.00",
  "store_credit_total": "0.00",
  "total": "0.00",
  "amount_due": "0.00",
  "covered_by_store_credit": false,
  "adjustment_total": "0.00",
  "gift_card": null,
  "market": {
    "id": "mkt_UkLWZg9DAJ",
    "name": "United States",
    "currency": "USD",
    "default_locale": "en",
    "tax_inclusive": false,
    "default": true,
    "country_codes": [
      "US"
    ],
    "supported_locales": [
      "en"
    ],
    "created_at": "2026-01-15T12:00:00.000Z",
    "updated_at": "2026-01-15T12:00:00.000Z",
    "tax_provider": null
  },
  "external_references": {},
  "status": "draft",
  "last_ip_address": null,
  "considered_risky": false,
  "confirmation_delivered": false,
  "store_owner_notification_delivered": null,
  "metadata": {},
  "cancel_note": null,
  "canceled_at": null,
  "approved_at": null,
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z",
  "payment_total": "0.00",
  "commission_amount_total": "0.00",
  "commission_tax_total": "0.00",
  "commission_total": "0.00",
  "preferred_stock_location_id": "sloc_UkLWZg9DAJ",
  "po_document_url": null,
  "seller_id": null,
  "order_group_id": null,
  "tags": [],
  "internal_note": null,
  "internal_note_html": null,
  "approver_id": null,
  "approver_type": null,
  "canceler_id": null,
  "canceler_type": null,
  "created_by_id": "adm_UkLWZg9DAJ",
  "created_by_type": "admin_user",
  "cancel_reason_id": null,
  "cancel_reason_name": null,
  "customer_id": null,
  "freight_summary": 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

external_references

object

Identities the record has in external systems, keyed by system: the same { system: external_id } map the Admin API renders, so what you read can be sent straight back. Systems you do not name keep the reference they have. A list of { system, external_id } entries is accepted too.

string

Example:

"customer@example.com"

customer_id

string | null

Null detaches the customer, leaving a guest order under its email.

use_customer_default_address

boolean

Copies the saved default billing and shipping addresses onto the order. Sent with company_id, it takes that company's defaults, inherited from its parent nodes when the company holds none of its own; otherwise it takes the customer's.

currency

enum<string>

Available options:

AED,

AFN,

ALL,

AMD,

ANG,

AOA,

ARS,

AUD,

AWG,

AZN,

BAM,

BBD,

BDT,

BGN,

BHD,

BIF,

BMD,

BND,

BOB,

BRL,

BSD,

BTN,

BWP,

BYN,

BYR,

BZD,

CAD,

CDF,

CHF,

CLF,

CLP,

CNY,

COP,

CRC,

CUC,

CUP,

CVE,

CZK,

DJF,

DKK,

DOP,

DZD,

EEK,

EGP,

ERN,

ETB,

EUR,

FJD,

FKP,

GBP,

GEL,

GHS,

GIP,

GMD,

GNF,

GTQ,

GYD,

HKD,

HNL,

HRK,

HTG,

HUF,

IDR,

ILS,

INR,

IQD,

IRR,

ISK,

JMD,

JOD,

JPY,

KES,

KGS,

KHR,

KMF,

KPW,

KRW,

KWD,

KYD,

KZT,

LAK,

LBP,

LKR,

LRD,

LSL,

LTL,

LVL,

LYD,

MAD,

MDL,

MGA,

MKD,

MMK,

MNT,

MOP,

MRO,

MRU,

MTL,

MUR,

MVR,

MWK,

MXN,

MYR,

MZN,

NAD,

NGN,

NIO,

NOK,

NPR,

NZD,

OMR,

PAB,

PEN,

PGK,

PHP,

PKR,

PLN,

PYG,

QAR,

RON,

RSD,

RUB,

RWF,

SAR,

SBD,

SCR,

SDG,

SEK,

SGD,

SHP,

SKK,

SLE,

SLL,

SOS,

SRD,

SSP,

STD,

STN,

SVC,

SYP,

SZL,

THB,

TJS,

TMM,

TMT,

TND,

TOP,

TRY,

TTD,

TWD,

TZS,

UAH,

UGX,

USD,

UYI,

UYU,

UYW,

UZS,

VED,

VEF,

VES,

VND,

VUV,

WST,

XAF,

XCD,

XCG,

XOF,

XPF,

YER,

ZAR,

ZMK,

ZMW,

ZWD,

ZWG,

ZWL,

ZWN,

ZWR

Example:

"USD"

market_id

string

channel_id

string

Defaults to the store primary channel when omitted.

locale

enum<string>

Available options:

aa,

ab,

ae,

af,

ak,

am,

an,

ar,

as,

av,

ay,

az,

ba,

be,

bg,

bh,

bi,

bm,

bn,

bo,

br,

bs,

ca,

ce,

ch,

co,

cr,

cs,

cu,

cv,

cy,

da,

de,

de-AT,

de-CH,

dv,

dz,

ee,

el,

en,

en-AU,

en-CA,

en-GB,

en-IN,

en-NZ,

en-US,

eo,

es,

es-419,

es-CL,

es-EC,

es-MX,

et,

eu,

fa,

ff,

fi,

fj,

fo,

fr,

fr-CA,

fy,

ga,

gd,

gl,

gn,

gu,

gv,

ha,

he,

hi,

ho,

hr,

ht,

hu,

hy,

hz,

ia,

id,

ie,

ig,

ii,

ik,

io,

is,

it,

iu,

ja,

jv,

ka,

kg,

ki,

kj,

kk,

kl,

km,

kn,

ko,

kr,

ks,

ku,

kv,

kw,

ky,

la,

lb,

lg,

li,

ln,

lo,

lt,

lu,

lv,

mg,

mh,

mi,

mk,

ml,

mn,

mr,

ms,

mt,

my,

na,

nb,

nd,

ne,

ng,

nl,

nn,

no,

nr,

nv,

ny,

oc,

oj,

om,

or,

os,

pa,

pi,

pl,

ps,

pt,

pt-BR,

pt-PT,

qu,

rm,

rn,

ro,

ru,

rw,

sa,

sc,

sd,

se,

sg,

si,

sk,

sl,

sl-SI,

sm,

sn,

so,

sq,

sr,

ss,

st,

su,

sv,

sw,

ta,

te,

tg,

th,

ti,

tk,

tl,

tn,

to,

tr,

ts,

tt,

tw,

ty,

ug,

uk,

ur,

uz,

ve,

vi,

vo,

wa,

wo,

xh,

yi,

yo,

za,

zh-CN,

zh-HK,

zh-TW,

zu

Example:

"en-US"

customer_note

string

Public, customer-visible note.

internal_note

string

Staff-only note. Rich text HTML; reads come back as this plus internal_note_html.

po_number

string

The buyer's own purchase-order reference. Searchable alongside the order number, and rendered on every order-facing document.

po_document_signed_id

string | null

The signed_id of the buyer's purchase order, from files.upload() with visibility: 'private'. Null removes the document the order carries.

shipping_address_id

string

An existing address from the customer's address book, or from the address book of the company the order is for.

billing_address_id

string

An existing address from the customer's address book, or from the address book of the company the order is for.

preferred_stock_location_id

string

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

company_id

string | null

Makes the order a company purchase, with that company's catalog prices and tax treatment. Null makes a draft a plain customer order again.

coupon_code

string

Applied non-fatally: an invalid code does not block creation.

metadata

object

Response

201 - application/json

order created with preferred_stock_location_id

⌘I

API basics

Endpoints

Create a draft order

Authorizations

Headers

Body

Response