Spree Admin SDK

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

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

const { data: stockMovements } = await client.stockMovements.list({
  kind_eq: 'allocated',
})

{
  "data": [
    {
      "id": "sm_UkLWZg9DAJ",
      "quantity": 5,
      "kind": "adjusted",
      "reason": "Cycle count",
      "created_at": "2026-01-15T12:00:00.000Z",
      "updated_at": "2026-01-15T12:00:00.000Z",
      "stock_level_id": "sl_gbHJdmfrXB",
      "stock_location_id": "sloc_UkLWZg9DAJ",
      "stock_location_name": "Mona Hegmann",
      "variant_id": "variant_gbHJdmfrXB",
      "variant_name": "Product 1928513",
      "variant_sku": "SKU-241",
      "order_id": null,
      "fulfillment_id": null,
      "return_id": null,
      "exchange_id": null,
      "stock_transfer_id": null,
      "stock_receipt_id": null,
      "purchase_order_id": null,
      "order_number": null,
      "return_number": null,
      "exchange_number": null,
      "stock_transfer_number": null,
      "purchase_order_number": null,
      "unit_cost": null
    }
  ],
  "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 stock movements

Returns the stock ledger, newest first. Every row says what happened to stock (kind) and carries a direct reference to what caused it, so a merchant can answer “why is this number what it is?” from the data.

Kinds are received (goods arrived), allocated (stock promised to a placed order), shipped (promised stock left), released (a promise withdrawn) and adjusted (a manual correction, which always carries a reason).

Movements are immutable — reversing one means writing its counterpart through the resource that caused it, which is why there is no create, update or delete here.

Filter with Ransack predicates such as q[kind_eq], q[stock_level_id_eq], q[order_id_eq], q[fulfillment_id_eq] or q[created_at_gteq].

kind is null on rows written before Spree 6.0 until spree:migrate_stock_movements_to_typed_rows has run.

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

GET

api

admin

stock_movements

Spree Admin SDK

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

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

const { data: stockMovements } = await client.stockMovements.list({
  kind_eq: 'allocated',
})

{
  "data": [
    {
      "id": "sm_UkLWZg9DAJ",
      "quantity": 5,
      "kind": "adjusted",
      "reason": "Cycle count",
      "created_at": "2026-01-15T12:00:00.000Z",
      "updated_at": "2026-01-15T12:00:00.000Z",
      "stock_level_id": "sl_gbHJdmfrXB",
      "stock_location_id": "sloc_UkLWZg9DAJ",
      "stock_location_name": "Mona Hegmann",
      "variant_id": "variant_gbHJdmfrXB",
      "variant_name": "Product 1928513",
      "variant_sku": "SKU-241",
      "order_id": null,
      "fulfillment_id": null,
      "return_id": null,
      "exchange_id": null,
      "stock_transfer_id": null,
      "stock_receipt_id": null,
      "purchase_order_id": null,
      "order_number": null,
      "return_number": null,
      "exchange_number": null,
      "stock_transfer_number": null,
      "purchase_order_number": null,
      "unit_cost": null
    }
  ],
  "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[reason_cont]=…. Send a list as q[<attribute>_in][]=a&q[<attribute>_in][]=b. How filters work.

Attribute	Kind	Predicates
`created_at`	Date and time	`eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null`
`exchange_id`	Prefixed ID	`eq` `not_eq` `in` `not_in` `null` `not_null`
`fulfillment_id`	Prefixed ID	`eq` `not_eq` `in` `not_in` `null` `not_null`
`id`	Prefixed ID	`eq` `not_eq` `in` `not_in` `null` `not_null`
`kind`	One of `received`, `allocated`, `shipped`, `released`, `adjusted`	`eq` `not_eq` `in` `not_in` `null` `not_null`
`order_id`	Prefixed ID	`eq` `not_eq` `in` `not_in` `null` `not_null`
`purchase_order_id`	Prefixed ID	`eq` `not_eq` `in` `not_in` `null` `not_null`
`quantity`	Number	`eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null`
`reason`	Text	`eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank`
`return_id`	Prefixed ID	`eq` `not_eq` `in` `not_in` `null` `not_null`
`stock_level_id`	Prefixed ID	`eq` `not_eq` `in` `not_in` `null` `not_null`
`stock_receipt_id`	Prefixed ID	`eq` `not_eq` `in` `not_in` `null` `not_null`
`stock_transfer_id`	Prefixed ID	`eq` `not_eq` `in` `not_in` `null` `not_null`
`unit_cost`	Amount	`eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `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[stock_level_id_eq]. The same predicates apply.

Prefix	Attributes
`stock_level_`	`allocated_count`, `count_on_hand`, `created_at`, `id`, `incoming_count`, `reserved_count`, `stock_location_id`, `updated_at`, `variant_id`
`stock_level_stock_location_`	`active`, `country_code`, `created_at`, `default`, `id`, `kind`, `name`, `pickup_enabled`, `returns_enabled`, `seller_id`, `state_code`, `updated_at`
`stock_level_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`

Sort by: created_at, exchange_id, fulfillment_id, id, kind, order_id, purchase_order_id, quantity, reason, return_id, stock_level_id, stock_receipt_id, stock_transfer_id, unit_cost, 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

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.

fields

string

Comma-separated list of fields to include. id is always included.

Response

stock movements found

data

object[]

required

Show child attributes

API basics

Endpoints

List stock movements

Filters

Authorizations

Headers

Query Parameters

Response

​Filters

Authorizations

Headers

Query Parameters

Response

Filters