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: sp_live_a1b2c3d4e5f6
X-CLIENT-SECRET: sk_live_9f8e7d6c5b4a3210

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.

Quickstart: your first request

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

Everything in this tutorial runs against the live API at https://api.stockpilot.dev. You need a Stockpilot account on the Growth tier or higher, because API access is gated to those plans.

Get a credential pair

Stockpilot authenticates with a static client ID and secret, not OAuth. In the Stockpilot app, open Settings → API and generate a pair. You get two values:

X-CLIENT-ID:     sp_live_a1b2c3d4e5f6
X-CLIENT-SECRET: sk_live_9f8e7d6c5b4a3210

The secret is shown once. Store it the way you would store a database password.

API conventions

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

These rules hold across the whole API. Learning them once saves reading them 74 times in the reference.

Pagination

List endpoints take page and page_size query parameters.

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"

page starts at 1. page_size defaults to 100 and caps at 1000.

{
  "count": 1284,
  "page": 2,
  "page_size": 500,
  "results": [ ]
}

Walk pages until a page returns fewer results than you asked for:

def all_pages(client, path, page_size=1000, **params):
    page = 1
    while True:
        data = client.get(path, params={**params, "page": page, "page_size": page_size}).json()
        yield from data["results"]
        if len(data["results"]) < page_size:
            return
        page += 1

GET /returns paginates differently. Its next and previous fields are booleans, not URLs, and you page with current_page and total_pages. Its status filters are lowercase (requested, partly_accepted, accepted) even though the statuses themselves are returned uppercase, and its page_size caps at 100. See sales channels and returns.

Receive your first webhook

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

Polling /inventory on a timer works until you have a few thousand SKUs. Webhooks invert it: Stockpilot pushes to an HTTPS endpoint you control, within seconds of the change.

By the end of this page you will have a local endpoint receiving signed, verified deliveries.

GET /webhooks/events

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

Today that returns two event types:

Event	Fires when
`orders.completed`	An order reaches the completed state, either by transitioning to it or by arriving already completed (a bol.com import, say). Once per order.
`inventory.stock_changed`	A product’s stock quantity changes in any warehouse.

Call this endpoint at runtime rather than hardcoding the list, so new event types appear without a redeploy on your side.

Order to label: fulfil an order end to end

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

This is the path most integrations end up walking: find work, ship it, record it. Six calls, one of which is asynchronous and one of which you must never blindly retry.

1. Find open orders

GET /orders

curl -s "https://api.stockpilot.dev/orders?status=open&page_size=20" \
  -H "X-CLIENT-ID: $SP_CLIENT_ID" \
  -H "X-CLIENT-SECRET: $SP_CLIENT_SECRET"

Order statuses are open, pending, on-hold, completed and cancelled.

2. Read the whole order

The list gives you a summary. Before shipping, pull the full record with line items, addresses and channel:

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.

That per key detail matters more than it looks. An organization running several integrations on separate keys gets the full allowance on each of them, and a single key can be raised or cut off without disturbing the others. It is a good reason to give every integration its own pair.

The four buckets

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

Build a low stock reorder bot

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

Stockpilot already knows your sales velocity, lead times and inbound stock. Rather than reimplementing that maths, you can ask it for recommendations and turn the answer into a purchase order.

Find what is running low

Start with the inventory list. Thresholds are expressed as either units (5u) or weeks of cover (33w), so an item is “low” relative to its own threshold rather than a global number.

GET /inventory

def low_stock(client, page_size=1000):
    page, out = 1, []
    while True:
        data = client.get("/inventory", params={"page": page, "page_size": page_size}).json()
        out.extend(i for i in data["results"] if i["quantity"] <= threshold_units(i))
        if len(data["results"]) < page_size:
            return out
        page += 1

One paginated call at page_size=1000 costs a single read-list request. Looping \/inventory\/get per SKU would cost hundreds of read-single requests for the same data, so prefer the list.

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 picking the wrong one is the most common bug in a Stockpilot integration.

The three product level numbers

{
  "sku": "TSHIRT-BLK-M",
  "quantity": 60,
  "incoming": 120,
  "offered_stock": 38
}

Field	Question it answers
`quantity`	How many units physically exist, across every warehouse
`incoming`	How many units are on inbound purchase orders
`offered_stock`	How many units Stockpilot advertises to your sales channels

offered_stock is the one that drives availability. It is derived, not stored: the sum of warehouses flagged to feed the offer, minus buffer stock.

Give an AI agent warehouse access

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

Most APIs make an agent guess. Stockpilot publishes two machine-readable surfaces that are regenerated from the OpenAPI schema on every request, so they cannot fall out of date with the API they describe.

The two files that matter

File	What it is	When to use it
llms.txt	Compact index: auth rules, conventions, and one line per operation grouped by tag	Cheap to load. Start here in a coding session.
llms-full.txt	Every operation with parameters, request bodies, response codes and real example payloads	When the agent needs to construct an exact request.

Both are plain text. No SDK, no MCP server, no tool definitions to maintain. If your assistant can fetch a URL, it can use the Stockpilot API.

Orders and fulfilment

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

Orders carry more state than a status field suggests. This guide covers what the states mean, how line items change under you, and which operations are safe to run without a human watching.

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.

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.

Sync offered stock to an ERP without double counting

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

Pushing stock into an ERP looks trivial until the seller adds a second warehouse. This tutorial builds a consumer that stays correct across warehouses, buffers and inbound purchase orders.

Read Receive your first webhook first if you have not set up a verified endpoint yet.

POST /webhooks/create

curl -s -X POST https://api.stockpilot.dev/webhooks/create \
  -H "X-CLIENT-ID: $SP_CLIENT_ID" \
  -H "X-CLIENT-SECRET: $SP_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "erp stock sync",
    "url": "https://erp-bridge.example.com/hooks/stock",
    "event": "inventory.stock_changed",
    "secret": "'"$WEBHOOK_SECRET"'"
  }'

Leave warehouse_id off so you receive every change. Scoping to one warehouse filters which changes fire a delivery, but the body you receive is the full product payload either way.

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 things move independently, and most integration bugs here come from reading one as if it were the other.

Suppliers

GET /purchase-orders/suppliers/list lists who you can order from. Lead time and minimum order quantities are supplier properties, which is why recommendations are generated per supplier rather than across the whole catalogue.

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.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.

GET /webhooks/events returns the same list at runtime, so an integration can discover new event types without a redeploy. Call it rather than hardcoding.

Stockpilot for developers

Authentication

The two headers

Quickstart: your first request

Get a credential pair

API conventions

Pagination

Receive your first webhook

What you can subscribe to

Order to label: fulfil an order end to end

1. Find open orders

2. Read the whole order

Rate limits and idempotency

The four buckets

Build a low stock reorder bot

Find what is running low

The inventory model

The three product level numbers

Give an AI agent warehouse access

The two files that matter

Orders and fulfilment

Statuses

Shipping and labels

Carriers

Templates

Sync offered stock to an ERP without double counting

Subscribe

Purchasing and inbound deliveries

Suppliers

Recommendations

Sales channels and returns

What is connected

Webhook delivery contract

Available events