Platform guides on Stockpilot for developers

Authentication

Thu, 03 Sep 2026 00:00:00 +0000

Stockpilot uses static API key authentication. There is no OAuth flow, no bearer token and no refresh cycle. A merchant generates a credential pair in the app and hands it to you.

The two headers

Send both on every request, including reads:

X-CLIENT-ID: 7c1f4ab93e5d2680
X-CLIENT-SECRET: e04b9d7a15c3f8621b0e94d7c5a3f8be

curl -s https://api.stockpilot.dev/auth/who-is \
  -H "X-CLIENT-ID: $SP_CLIENT_ID" \
  -H "X-CLIENT-SECRET: $SP_CLIENT_SECRET"

There is no Authorization header and no query parameter alternative. Sending a bearer token will get you a 401.

API conventions

Thu, 03 Sep 2026 00:00:00 +0000

These rules hold across the whole API.

Pagination

Every list endpoint takes page and page_size. page starts at 1, page_size defaults to 100.

curl -s "https://api.stockpilot.dev/inventory?page=2&page_size=500" \
  -H "X-CLIENT-ID: $SP_CLIENT_ID" \
  -H "X-CLIENT-SECRET: $SP_CLIENT_SECRET"

There are two envelopes, and they page differently. Write one paginator against the wrong one and it will silently read page one forever.

Counted envelope, on /inventory, /assemblies, /purchase-orders and /returns. next and previous are booleans, not URLs:

Rate limits and idempotency

Thu, 03 Sep 2026 00:00:00 +0000

Limits are applied per API key, per X-CLIENT-ID and X-CLIENT-SECRET pair, in fixed 60 second windows.

Each key gets its own allowance, so give every integration its own pair. One key can then be adjusted without affecting the others.

The four buckets

A request is bucketed by what it costs to serve, not by its HTTP verb alone.

Bucket	Limit per minute	What lands here
`read-single`	300	Fetching one record by id, sku or barcode
`read-list`	120	Paginated list endpoints
`write`	60	Creates, updates, deletes
`heavy`	20	Anything that reaches a carrier, a marketplace or a mail provider

The heavy routes, specifically:

The inventory model

Thu, 03 Sep 2026 00:00:00 +0000

An inventory record carries several numbers that all look like “how many do we have”. They are not interchangeable, and the two surfaces answer different questions.

Two surfaces, two shapes

GET /inventory returns the stored record for an item:

{
  "id": 34897,
  "sku": "201156",
  "item_name": "Vichy Homme Structure Force 50 ml",
  "quantity": 150,
  "reserved_quantity": 3,
  "incoming_quantity": 50,
  "backorder_amount": 0,
  "bin_location": ["A1-001-01", "B2-003-05"],
  "threshold": "5u"
}

The inventory.stock_changed webhook sends a different, purpose built payload, because stored fields alone cannot express multi warehouse stock unambiguously:

Assemblies

Sun, 06 Sep 2026 00:00:00 +0000

An assembly is an inventory item built from other inventory items. A dive set made of a mask, a snorkel and fins. A light fitting made of a housing, a driver and an LED board.

There is no separate “create assembly” call. An item becomes an assembly the moment it has its first component, and stops being one when you remove the last.

Assemblies are not bundles

Both are items made of other items, and they behave nothing alike.

Orders and fulfilment

Thu, 03 Sep 2026 00:00:00 +0000

What the order states mean, how line items change under you, and which operations are safe to run unattended.

Statuses

open · pending · on-hold · completed · cancelled

Filter with ?status=open, or pass several comma separated. An order arriving from a marketplace can land in any of them: a bol.com import can arrive already completed, which is why orders.completed fires on arrival as well as on transition.

Reading an order

GET /orders gives you a page of summaries. GET /orders/get-single takes either order_pk or order_number, and returns the full record with line items, addresses and channel.

Shipping and labels

Thu, 03 Sep 2026 00:00:00 +0000

Buying a label is the most expensive thing this API does. It reaches a carrier, it costs money, and it cannot be undone by a retry. Everything below is arranged around that.

Carriers

GET /shipping/integrations lists what the organization has connected. You need the carrier id from here to request anything.

Templates

GET /shipping/label-templates returns the templates available, each with an id, a name and a carrier_identifier.

Some templates are virtual: they are generated per connected channel rather than configured by hand.

Purchasing and inbound deliveries

Thu, 03 Sep 2026 00:00:00 +0000

Purchase orders track what you asked a supplier for and what has physically turned up. Those two move independently, and reading one as the other is the most common bug here.

Suppliers

GET /purchase-orders/suppliers/list lists who you can order from. Recommendations are generated per supplier, because lead time and minimum order quantities are supplier properties.

Recommendations

Stockpilot already knows your sales velocity, lead times and inbound stock, so ask it rather than recomputing:

Sales channels and returns

Thu, 03 Sep 2026 00:00:00 +0000

Stockpilot sits between a seller’s channels and their stock. The API exposes what is connected and lets you trigger a sync, but connecting a channel is not something you can do through it.

What is connected

GET /sales-channels

{
  "channels": [
    {
      "id": 1,
      "name": "My Shopify Store",
      "handle": "shopify",
      "is_active": true,
      "logo": "https://…/shopify-icon.png",
      "channel_is_forwarded": false,
      "is_inventory_source": true,
      "is_synchronized": true,
      "created_at": "2023-01-15T10:30:00Z"
    }
  ]
}

Supported handles today:

shopify · woocommerce · amazon · bol · etsy · kaufland · mirakl · b2b-portal

Four fields decide how a channel behaves, and they are worth reading rather than assuming:

Webhook delivery contract

Thu, 03 Sep 2026 00:00:00 +0000

Stockpilot pushes events to an HTTPS endpoint you control. You register an endpoint with POST /webhooks/create, verify the signature on every request, and respond 2xx quickly. Delivery is at-least-once, so your handler must be idempotent.

Available events

Event	Fires when
`orders.created`	A new order arrives.
`orders.updated`	An order changes. Chattier than it looks, see below.
`orders.completed`	An order reaches the completed state, either by transitioning to it or by arriving already completed, such as a bol.com import. Fires once per order.
`inventory.stock_changed`	A product’s stock quantity changes in any warehouse.
`purchase_orders.status_changed`	A purchase order moves between `DRAFT`, `ORDERED`, `SHIPPED`, `CONFIRMED`, `DELIVERED` and `COMPLETED`.
`purchase_orders.received`	A purchase order reaches `DELIVERED`.
`purchase_orders.parcel_status_changed`	A parcel moves between `CREATED`, `PROCESSING` and `COMPLETED`.
`purchase_orders.parcel_received`	A parcel has been applied to stock.

One event per webhook. Subscribe to each one you want with its own POST /webhooks/create.