Spree Admin SDK

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

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

// This delivery's counts, not running totals: 58 accepted, 2 refused as
// damaged. A second delivery adds to the first. Omit `items` to book in
// everything still outstanding, intact.
const stockReceipt = await client.purchaseOrders.stockReceipts.create('po_1234567890', {
  reference: 'DN-4471',
  items: [
    {
      id: 'poi_1234567890',
      quantity_accepted: 58,
      quantity_rejected: 2,
      rejection_reason: 'damaged',
    },
  ],
})

spree api post /purchase_orders/{purchase_order_id}/stock_receipts -d '{"reference":"DN-4471","items":[{"id":"poi_1234567890","quantity_accepted":58,"quantity_rejected":2,"rejection_reason":"damaged"}]}'

{
  "id": "sr_UkLWZg9DAJ",
  "number": "SR1001",
  "reference": "DN-4471",
  "notes": null,
  "metadata": {},
  "quantity_accepted_total": 58,
  "quantity_rejected_total": 2,
  "received_at": "2026-01-15T12:00:00.000Z",
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z",
  "receivable_type": "purchase_order",
  "receivable_id": "po_UkLWZg9DAJ",
  "received_by_id": "adm_UkLWZg9DAJ",
  "received_by_type": "admin_user",
  "items_count": 1
}

{
  "error": {
    "code": "processing_error",
    "message": "Only a purchase order that has been placed can be received"
  }
}

Book in a delivery

The moment purchased goods first count toward availability. Records one delivery as a stock receipt: what this delivery brought, per line, not a running total — a second delivery adds to the first.

quantity_accepted reaches the shelf; quantity_rejected is refused and recorded with a rejection_reason (damaged, wrong_item, expired or other), never stocked. Omit items to book in everything still outstanding, intact.

Each received stock movement carries the line’s unit_cost and names the receipt, so a delivery can be reconciled against the ledger.

The order stays partially_received while any line is still owed, settles in received once every line has what it expected, and in over_received once any line has more.

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

POST

api

admin

purchase_orders

{purchase_order_id}

stock_receipts

Spree Admin SDK

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

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

// This delivery's counts, not running totals: 58 accepted, 2 refused as
// damaged. A second delivery adds to the first. Omit `items` to book in
// everything still outstanding, intact.
const stockReceipt = await client.purchaseOrders.stockReceipts.create('po_1234567890', {
  reference: 'DN-4471',
  items: [
    {
      id: 'poi_1234567890',
      quantity_accepted: 58,
      quantity_rejected: 2,
      rejection_reason: 'damaged',
    },
  ],
})

spree api post /purchase_orders/{purchase_order_id}/stock_receipts -d '{"reference":"DN-4471","items":[{"id":"poi_1234567890","quantity_accepted":58,"quantity_rejected":2,"rejection_reason":"damaged"}]}'

{
  "id": "sr_UkLWZg9DAJ",
  "number": "SR1001",
  "reference": "DN-4471",
  "notes": null,
  "metadata": {},
  "quantity_accepted_total": 58,
  "quantity_rejected_total": 2,
  "received_at": "2026-01-15T12:00:00.000Z",
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z",
  "receivable_type": "purchase_order",
  "receivable_id": "po_UkLWZg9DAJ",
  "received_by_id": "adm_UkLWZg9DAJ",
  "received_by_type": "admin_user",
  "items_count": 1
}

{
  "error": {
    "code": "processing_error",
    "message": "Only a purchase order that has been placed can be received"
  }
}

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

Path Parameters

purchase_order_id

string

required

Purchase order ID

Body

application/json

reference

string | null

The supplier's delivery note, or the carrier's reference.

Example:

"DN-4471"

received_at

string<date-time> | null

When the goods were counted in. Defaults to now.

notes

string | null

items

object[]

Omit to book in everything still outstanding, intact. Naming lines, even none, records exactly what the dock counted: quantity_accepted reaches the shelf; quantity_rejected is refused, recorded with a rejection_reason and never stocked.

Show child attributes

Response

delivery booked in

string

required

number

string

required

reference

string | null

required

notes

string | null

required

metadata

object

required

quantity_accepted_total

number

required

quantity_rejected_total

number

required

received_at

string

required

created_at

string

required

updated_at

string

required

receivable_type

enum<string>

required

Available options:

purchase_order,

stock_transfer

receivable_id

string

required

received_by_id

string | null

required

received_by_type

required

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

Available options:

admin_user,

api_key

items_count

number

required

received_by

object

Show child attributes

items

object[]

Show child attributes

⌘I

API basics

Endpoints

Book in a delivery

Authorizations

Headers

Path Parameters

Body

Response