Create a purchase order

Spree Admin SDK

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

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

const purchaseOrder = await client.purchaseOrders.create({
  supplier_id: 'sup_1234567890',
  destination_location_id: 'sloc_1234567890',
  expected_at: '2026-10-01',
  items: [{ variant_id: 'variant_1234567890', quantity_ordered: 100, unit_cost: '12.50' }],
})

spree api post /purchase_orders -d '{"supplier_id":"sup_1234567890","destination_location_id":"sloc_1234567890","expected_at":"2026-10-01","items":[{"variant_id":"variant_1234567890","quantity_ordered":100,"unit_cost":"12.50"}]}'

{
  "id": "po_gbHJdmfrXB",
  "number": "PO1002",
  "status": "draft",
  "currency": "USD",
  "reference": "SUP-8891",
  "notes": null,
  "metadata": {},
  "close_reason": null,
  "items_count": 1,
  "quantity_received_total": 0,
  "quantity_rejected_total": 0,
  "ordered_at": null,
  "received_at": null,
  "closed_short_at": null,
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z",
  "expected_at": "2026-10-01",
  "cancel_by": null,
  "closed_short": false,
  "quantity_ordered_total": 100,
  "editable": true,
  "subtotal": "1250.00",
  "supplier_id": "sup_UkLWZg9DAJ",
  "destination_location_id": "sloc_UkLWZg9DAJ"
}

{
  "error": {
    "code": "record_not_found",
    "message": "Supplier not found"
  }
}

POST

api

admin

purchase_orders

Spree Admin SDK

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

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

const purchaseOrder = await client.purchaseOrders.create({
  supplier_id: 'sup_1234567890',
  destination_location_id: 'sloc_1234567890',
  expected_at: '2026-10-01',
  items: [{ variant_id: 'variant_1234567890', quantity_ordered: 100, unit_cost: '12.50' }],
})

spree api post /purchase_orders -d '{"supplier_id":"sup_1234567890","destination_location_id":"sloc_1234567890","expected_at":"2026-10-01","items":[{"variant_id":"variant_1234567890","quantity_ordered":100,"unit_cost":"12.50"}]}'

{
  "id": "po_gbHJdmfrXB",
  "number": "PO1002",
  "status": "draft",
  "currency": "USD",
  "reference": "SUP-8891",
  "notes": null,
  "metadata": {},
  "close_reason": null,
  "items_count": 1,
  "quantity_received_total": 0,
  "quantity_rejected_total": 0,
  "ordered_at": null,
  "received_at": null,
  "closed_short_at": null,
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z",
  "expected_at": "2026-10-01",
  "cancel_by": null,
  "closed_short": false,
  "quantity_ordered_total": 100,
  "editable": true,
  "subtotal": "1250.00",
  "supplier_id": "sup_UkLWZg9DAJ",
  "destination_location_id": "sloc_UkLWZg9DAJ"
}

{
  "error": {
    "code": "record_not_found",
    "message": "Supplier not found"
  }
}

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

supplier_id

string

required

Example:

"sup_1234567890"

destination_location_id

string

required

Example:

"sloc_1234567890"

currency

enum<string> | null

Defaults to the store's currency; set it for a foreign-currency order.

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"

expected_at

string<date> | null

The day the supplier promised. null clears it.

Example:

"2026-10-01"

cancel_by

string<date> | null

The day after which the goods are no longer wanted. null clears it.

reference

string | null

The supplier's own order number. null clears it.

notes

string | null

items

object[]

Sending the list replaces whatever the order currently holds.

Show child attributes

metadata

object | null

Response

purchase order created

string

required

number

string

required

status

required

The values listed are the built-in ones; extensions may add more.

Available options:

draft,

ordered,

partially_received,

received,

over_received,

canceled

currency

enum<string>

required

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

reference

string | null

required

notes

string | null

required

metadata

object

required

close_reason

string | null

required

items_count

number

required

quantity_received_total

number

required

quantity_rejected_total

number

required

ordered_at

string | null

required

received_at

string | null

required

closed_short_at

string | null

required

created_at

string

required

updated_at

string

required

expected_at

string | null

required

cancel_by

string | null

required

closed_short

boolean

required

quantity_ordered_total

number

required

editable

boolean

required

subtotal

string

required

supplier_id

string | null

required

destination_location_id

string | null

required

items

object[]

Show child attributes

stock_receipts

object[]

Show child attributes

supplier

object

Show child attributes

destination_location

object

Show child attributes

⌘I

API basics

Endpoints

Authorizations

Headers

Body

Response