Spree Admin SDK

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

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

const { data: purchaseOrders } = await client.purchaseOrders.list({
  status_eq: 'ordered',
  expand: ['supplier'],
})

{
  "data": [
    {
      "id": "po_UkLWZg9DAJ",
      "number": "PO1001",
      "status": "draft",
      "currency": "USD",
      "reference": null,
      "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"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 25,
    "count": 1,
    "pages": 1,
    "from": 1,
    "to": 1,
    "in": 1,
    "previous": null,
    "next": null
  }
}

{
  "error": {
    "code": "authentication_required",
    "message": "Authentication required"
  }
}

List purchase orders

Stock bought from suppliers. A purchase order carries what a purchase has and a stock transfer does not: a supplier, a unit cost per line and an expected arrival date.

Ordered units never count toward availability. Nothing here changes count_on_hand until receive runs, because a merchant who has ordered stock does not have it.

Statuses are draft, ordered, partially_received, received, over_received and canceled. Each move between them is its own endpoint, not a PATCH that writes status.

Filter with Ransack predicates such as q[status_eq], q[supplier_id_eq] or q[expected_at_lteq]. Expand items, supplier and destination_location.

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

GET

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 { data: purchaseOrders } = await client.purchaseOrders.list({
  status_eq: 'ordered',
  expand: ['supplier'],
})

{
  "data": [
    {
      "id": "po_UkLWZg9DAJ",
      "number": "PO1001",
      "status": "draft",
      "currency": "USD",
      "reference": null,
      "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"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 25,
    "count": 1,
    "pages": 1,
    "from": 1,
    "to": 1,
    "in": 1,
    "previous": null,
    "next": null
  }
}

{
  "error": {
    "code": "authentication_required",
    "message": "Authentication required"
  }
}

Filters

Filter with q[<attribute>_<predicate>]=value, for example q[number_cont]=…. Send a list as q[<attribute>_in][]=a&q[<attribute>_in][]=b. How filters work.

Attribute	Kind	Predicates
`cancel_by`	Date	`eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null`
`closed_short_at`	Date and time	`eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null`
`created_at`	Date and time	`eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null`
`currency`	One of the `CurrencyCode` codes	`eq` `not_eq` `in` `not_in` `null` `not_null`
`destination_location_id`	Prefixed ID	`eq` `not_eq` `in` `not_in` `null` `not_null`
`expected_at`	Date	`eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null`
`id`	Prefixed ID	`eq` `not_eq` `in` `not_in` `null` `not_null`
`number`	Text	`eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank`
`ordered_at`	Date and time	`eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null`
`received_at`	Date and time	`eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null`
`reference`	Text	`eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank`
`status`	One of `draft`, `ordered`, `partially_received`, `received`, `over_received`, `canceled`	`eq` `not_eq` `in` `not_in` `null` `not_null`
`supplier_id`	Prefixed ID	`eq` `not_eq` `in` `not_in` `null` `not_null`
`updated_at`	Date and time	`eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null`

Filters through associations

Prefix an associated record’s attribute with the association, as in q[destination_location_id_eq]. The same predicates apply.

Prefix	Attributes
`destination_location_`	`active`, `country_code`, `created_at`, `default`, `id`, `kind`, `name`, `pickup_enabled`, `returns_enabled`, `seller_id`, `state_code`, `updated_at`
`destination_location_seller_`	`contact_email`, `created_at`, `id`, `name`, `status`, `updated_at`
`items_`	`created_at`, `id`, `quantity_ordered`, `quantity_received`, `quantity_rejected`, `unit_cost`, `updated_at`, `variant_id`
`items_variant_`	`carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width`
`supplier_`	`city`, `contact_name`, `country_code`, `created_at`, `email`, `id`, `name`, `phone`, `updated_at`

Sort by: cancel_by, closed_short_at, created_at, currency, destination_location_id, expected_at, id, number, ordered_at, received_at, reference, status, supplier_id, updated_at. Prefix a field with - to sort descending.

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

Query Parameters

q[search]

string

Matches any of number and reference (partial, case-insensitive).

q[closed]

boolean

Set to true to apply closed.

q[open]

boolean

Set to true to apply open.

q[overdue]

boolean

Set to true to apply overdue.

q[past_cancel_by]

boolean

Set to true to apply past_cancel_by.

page

integer

Page number

limit

integer

Number of records per page

object

Attribute filters, as q[<attribute>_<predicate>]=value. See Filters above for the list.

expand

string

Comma-separated associations to embed: items, supplier, destination_location

Response

purchase orders found

data

object[]

required

Show child attributes

API basics

Endpoints

List purchase orders

Filters

Authorizations

Headers

Query Parameters

Response

​Filters

Authorizations

Headers

Query Parameters

Response

Filters