MCP server

Ask your AI app about your stock

A hosted MCP server that gives Claude Code, Cursor and any other MCP client 54 tools for orders, stock, purchasing, warehouses and sales figures. Nothing to install: add one URL and your API key.

Connect Tool reference

54 tools ·31 read ·23 write ·Streamable HTTP

claude

> What should I reorder from Vichy this week?

stockpilot · purchase_orders_recommend
stockpilot · supplier_items_list

3 items below cover at current sales:
  201156  Vichy Homme 50 ml   order 48
  201157  Vichy Homme 100 ml  order 24
  201190  Vichy Mineral 89    order 36
Draft a purchase order for these?

Connect

One endpoint, two headers

Point your client at https://mcp.stockpilot.dev/mcp and send your API key as the X-CLIENT-ID and X-CLIENT-SECRET headers. It is the same pair the CLI uses, from Settings → API in the Stockpilot app.

Claude Code

$ claude mcp add --transport http stockpilot \
    https://mcp.stockpilot.dev/mcp \
    --header "X-CLIENT-ID: your-client-id" \
    --header "X-CLIENT-SECRET: your-client-secret"

$ claude mcp list
stockpilot: https://mcp.stockpilot.dev/mcp (HTTP) - ✔ Connected

.cursor/mcp.json

{
  "mcpServers": {
    "stockpilot": {
      "url": "https://mcp.stockpilot.dev/mcp",
      "headers": {
        "X-CLIENT-ID": "${env:STOCKPILOT_CLIENT_ID}",
        "X-CLIENT-SECRET": "${env:STOCKPILOT_CLIENT_SECRET}"
      }
    }
  }
}

In Cursor, put the file in a project's .cursor/ folder or in ~/.cursor/mcp.json for every project, export both variables in your shell profile and restart Cursor, so the secret never sits in the file. To try the tools by hand, run npx @modelcontextprotocol/inspector, choose Streamable HTTP, enter the endpoint and add both headers before connecting.

Credentials go in headers, never in the URL. A request with a key in the query string is refused with 400, and one without both headers gets 401. Clients that can only sign in with OAuth, and cannot send custom headers, cannot connect yet.

Access

Read-only, when you want it

Add the header X-STOCKPILOT-READ-ONLY: 1 and the 23 tools that change data are neither listed nor callable. The model is told the connection is read-only, so it says what it would have changed instead of trying another way round.

Every tool also carries MCP annotations: read tools are marked read-only, and writes say whether they are destructive and safe to retry, so clients that ask before risky calls can do so.

Like the CLI's read-only profile, this is a guardrail against mistakes, not a security boundary. Whoever configures the client can remove the header. For a hard limit, issue API credentials that lack write permission.

read-only

$ claude mcp add --transport http stockpilot \
    https://mcp.stockpilot.dev/mcp \
    --header "X-CLIENT-ID: your-client-id" \
    --header "X-CLIENT-SECRET: your-client-secret" \
    --header "X-STOCKPILOT-READ-ONLY: 1"

> Cancel order SP-100231

This connection is read-only, so I can't cancel it.
In Stockpilot: Orders → SP-100231 → Cancel.

Behaviour

What the model can rely on

Conventions

page / page_size
On list tools. Defaults 1 and 25, maximum 100. Results carry a pagination object with has_more and next_page.
id / sku / barcode
Item lookup takes exactly one of the three.
idempotency_key
On writes the API guards. Generated when empty; pass the same key to retry a call whose outcome was lost.

Left out on purpose

deletes
Nothing can be deleted through the server.
webhooks, uploads, PDFs
Webhook management, file uploads, and label and invoice PDFs stay in the app, the CLI and the API.
one tool per task
Tools follow what a shop owner asks, not one per API route, which keeps the list short enough for a model to choose well.

Reference

All 54 tools

Generated from the server's own tool list, so it is what your client sees. Tools marked write change data and are hidden in read-only mode. Expand any tool for its parameters.

Orders and customers Stock Catalogue Purchasing Warehouses, transfers and returns Account, channels and figures

Orders and customers 11 tools

orders_list List orders, newest first, filtered by status (open orders by default).

Use this to see what needs picking, packing or shipping, or to find an order when you do not know its number. Each order includes customer, address and line items; timeline notes are left out here, so use orders_get for the full order.

statusstring: Order status to filter on, comma-separated for several. Known values: open, pending, on-hold, cancelled, completed.
include_forwardedboolean: Include orders forwarded to another channel.
pageinteger: Page number, starting at 1.
page_sizeinteger: Results per page, 1 to 100. The default of 25 keeps responses small.

orders_get Get one order with all details: customer, billing and shipping address, line items and timeline notes.

Pass exactly one of order_id or order_number.

order_idinteger: Numeric Stockpilot order ID (the id field).
order_numberstring: Order number, e.g. ‘SP-100231’.

orders_fulfillment_get Get the shipping and tracking details registered for an order: carrier, tracking code and when it shipped.

order_idinteger, required: Numeric Stockpilot order ID: the id from orders_list or orders_get, not the order number.

orders_cancellation_requests_list List orders where the sales channel or customer has asked for a cancellation that is still open.

Use this to find orders that should not be shipped. Each order includes its notes, like orders_get. Cancel one with orders_cancel once the user agrees.

pageinteger: Page number, starting at 1.

shipping_label_suggestion Show which shipping label template the organization's shipping rules pick for an order.

The rules match on things like SKU, weight and destination country. Labels themselves are created in Stockpilot.

order_idinteger, required: Numeric Stockpilot order ID: the id from orders_list or orders_get, not the order number.

customers_list List the organization's B2B customers with contact details, addresses, VAT number and payment terms.

Use search to find one customer; the API returns every customer at once, so results are filtered and capped here.

searchstring: Case-insensitive match on business name, customer code or email address.
limitinteger: Maximum number of customers to return.

orders_fulfil write Mark an order as shipped, in full or for some lines, and register the tracking details.

Use this once the parcel has actually left the warehouse. Stockpilot passes the fulfilment and tracking on to the sales channel, so it cannot be undone from here. Pass exactly one of order_id or order_number.

order_idinteger: Numeric Stockpilot order ID (the id field).
order_numberstring: Order number, e.g. ‘SP-100231’.
carrier_namestring: Human-readable carrier name, e.g. ‘PostNL’.
carrier_codestring: Carrier code, e.g. ‘POSTNL’.
tracking_codestring: Tracking number of the shipment.
tracking_urlstring: Tracking URL of the shipment.
shipping_methodstring: Shipping method, e.g. ‘Standard’ or ‘Evening’.
shipment_typestring: Shipment type, e.g. ‘Parcel’ or ‘Mailbox’.
servicestring: Shipping service provider, e.g. ‘Sendcloud’.
fulfilled_atstring: When it shipped, as an ISO datetime, e.g. ‘2026-10-21T14:30:00Z’.
itemsFulfilmentLine[]: Lines to fulfil for a partial fulfilment. Leave empty to fulfil the whole order.

orders_update_status write Change an order's status to open, pending, completed or cancelled.

To cancel an order that came from a sales channel, prefer orders_cancel, which passes the cancellation and its reason on to the channel.

order_idinteger, required: Numeric Stockpilot order ID: the id from orders_list or orders_get, not the order number.
status"open" | "pending" | "completed" | "cancelled", required: New status for the order.

orders_cancel write Cancel an order, including at the sales channel it came from. This cannot be undone.

Only call this when the user has clearly asked to cancel this specific order.

order_idinteger, required: Numeric Stockpilot order ID: the id from orders_list or orders_get, not the order number.
reason_codestring: Cancellation reason code. Defaults to REQUESTED_BY_CUSTOMER.

orders_add_note write Add a note to an order's timeline, visible to the team in Stockpilot.

Use it to record what was done or decided about an order, for example after a customer contact.

order_idinteger, required: Numeric Stockpilot order ID: the id from orders_list or orders_get, not the order number.
messagestring, required: Text of the note, at most 280 characters.

orders_backorder write Move order lines onto backorder when there is not enough stock, or back off it once stock is in.

order_idinteger, required: Numeric Stockpilot order ID: the id from orders_list or orders_get, not the order number.
direction"to_backorder" | "from_backorder", required: to_backorder when stock is missing; from_backorder once it is available again.
linesBackorderLine[], required: Order lines and quantities to move.

Stock 8 tools

inventory_list List inventory items (sellable SKUs) with stock levels, prices and bin locations.

Use this to search or filter stock, find low or recently changed items, or browse the catalogue at SKU level. For one known SKU, barcode or id, inventory_get is faster and more complete.

searchstring: Case-insensitive match on SKU, item name or barcode.
product_idinteger: Only the items (variants) of this product.
supplier_idinteger: Only items linked to this supplier.
brand_idinteger: Only items of this brand.
category_idinteger: Only items in this category.
is_activeboolean: True for active items only, false for inactive only.
created_sincestring: Only items created on or after this date.
updated_sincestring: Only items updated on or after this date.
sort"sku" | "-sku" | "item_name" | "-item_name" | "barcode" | "-barcode" | "quantity" | "-quantity" | "base_price" | "-base_price" | "stock_threshold" | "-stock_threshold" | "created_at" | "-created_at" | "updated_at" | "-updated_at": Field to sort by. Prefix with ‘-’ for descending, e.g. ‘-quantity’.
pageinteger: Page number, starting at 1.
page_sizeinteger: Results per page, 1 to 100. The default of 25 keeps responses small.

inventory_get Get one inventory item with its stock (overall and per warehouse), prices, dimensions and bin locations.

Pass exactly one of id, sku or barcode.

idinteger: Inventory item ID (the id field of an inventory item).
skustring: SKU of the inventory item.
barcodestring: Barcode / EAN of the inventory item.

assemblies_list List assemblies: items built from other items (kits, sets), with their components.

`quantity` is how many are built and in stock; `buildable_quantity` is how many more could be built from component stock right now. The component with the lowest buildable_from_component is the one holding production back.

searchstring: Match on SKU.
pageinteger: Page number, starting at 1.
page_sizeinteger: Results per page, 1 to 100. The default of 25 keeps responses small.

assemblies_get Get one assembly with its components, stock and how many more can be built right now.

item_idinteger, required: Inventory item ID of the assembly.

inventory_update write Change an inventory item: stock levels, bin locations, reorder threshold, prices or status.

Identify the item with exactly one of id, sku or barcode, then pass only the fields to change. Stock quantities overwrite the current level; read it first with inventory_get when you mean to add or subtract. With `quantities`, check each entry's status in the response: an unknown warehouse comes back as an error entry while the other entries are still applied.

idinteger: Inventory item ID (the id field of an inventory item).
skustring: SKU of the inventory item.
barcodestring: Barcode / EAN of the inventory item.
quantityinteger: New stock in the default warehouse. Absolute, not a delta.
quantitiesWarehouseStockLevel[]: New stock per warehouse. Each entry sets one warehouse to an absolute level.
assign_bin_locationstring: Bin location to add, formatted path-rack-shelf(-bin), e.g. ‘A1-001-01’.
remove_bin_locationstring: Bin location to remove, formatted path-rack-shelf(-bin), e.g. ‘B3-002-01’.
thresholdstring: Reorder threshold: ‘5u’ for 5 units or ‘3w’ for 3 weeks of stock.
stock_thresholdinteger: Minimum stock level for low-stock alerts.
moqinteger: Minimum order quantity.
item_namestring: New item name.
base_pricenumber: New base price.
retail_pricenumber: New retail price.
purchase_pricenumber: New purchase price.
wholesale_pricenumber: New wholesale price.
sale_pricenumber: New sale price.
conditionstring: Item condition, e.g. ‘NEW’.
is_activeboolean: Activate or deactivate the item.

inventory_bulk_update write Change many inventory items in one call: stock levels, bin locations, thresholds, prices or status.

Use this instead of calling inventory_update in a loop. Rows succeed or fail one by one: read the updated/failed counters and each row's status in `results`. Each item may appear only once.

itemsInventoryChange[], required: 1 to 500 rows, each one item and the fields to change.

inventory_create write Create a new inventory item (a sellable SKU) under an existing product.

product_idinteger, required: Product the new item (variant) belongs to, from products_list or products_create.
skustring, required: SKU of the new item.
item_namestring, required: Name of the new item.
barcodestring, required: Barcode / EAN of the new item.
quantityinteger: Starting stock. Defaults to 0.
purchase_pricenumber: Purchase price.
base_pricenumber: Base (selling) price.
wholesale_pricenumber: Wholesale price.
stock_thresholdinteger: Minimum stock level for alerts. Defaults to 1.
moqinteger: Minimum order quantity. Defaults to 1.
weightstring: Weight in grams, as a string.
vat_classstring: VAT class name. Defaults to ‘standard_rate’.
is_activeboolean: Whether the item is active. Defaults to true.

assemblies_build write Build assemblies from component stock, or take built ones apart. This moves real stock.

Check buildable_quantity with assemblies_get first: a build that stock cannot cover is refused and nothing moves.

item_idinteger, required: Inventory item ID of the assembly.
quantityinteger, required: How many assemblies to build or take apart.
direction"assemble" | "disassemble": assemble consumes component stock; disassemble returns built units to components.
idempotency_keystring: Optional. Leave empty on the first attempt; one is generated and shown if the call fails. When retrying a call whose outcome you did not see, pass the same key so Stockpilot runs it only once.

Catalogue 6 tools

products_list List products: the parent records (title, description, brand, category) that inventory items belong to.

Use this for catalogue-level questions. Stock, SKUs, barcodes and prices live on inventory items; use inventory_list with product_id to see a product's variants.

supplier_idinteger: Only products linked to this supplier.
category_idinteger: Only products in this category.
brand_idinteger: Only products of this brand.
pageinteger: Page number, starting at 1.
page_sizeinteger: Results per page, 1 to 100. The default of 25 keeps responses small.

products_get Get one product by its ID. To look an item up by SKU or barcode, use inventory_get instead.

product_idinteger, required: Product ID, e.g. the product_id of an inventory item.

bundles_list List bundles (sets of products sold together as one listing), each with the products it contains.

pageinteger: Page number, starting at 1.
page_sizeinteger: Results per page, 1 to 100. The default of 25 keeps responses small.

bundles_get Get one bundle with the products and quantities it contains.

bundle_idinteger, required: Bundle ID from bundles_list.

brands_and_categories_list List the organization's brands and product categories with their IDs.

Use the IDs to filter products_list or inventory_list, or when creating a product.

products_create write Create a new product: the parent record that inventory items (SKUs) belong to.

A product has no SKU or stock of its own; add one or more items with inventory_create afterwards.

titlestring, required: Product title.
descriptionstring: Product description.
brand_idinteger: Brand ID from brands_and_categories_list. Defaults to ‘Brandless’.
category_idinteger: Category ID from brands_and_categories_list. Defaults to ‘No category’.
is_activeboolean: Whether the product is active. Defaults to true.

Purchasing 13 tools

suppliers_list List suppliers with contact details, lead time, payment terms and how many products each supplies.

Use this to find a supplier_id before listing their products or creating a purchase order.

searchstring: Case-insensitive match on supplier name.
pageinteger: Page number, starting at 1.
page_sizeinteger: Results per page, 1 to 100. The default of 25 keeps responses small.

suppliers_get Get one supplier with contact, address, banking, currency, lead time and payment terms.

supplier_idinteger, required: Supplier ID from suppliers_list.

purchase_orders_list List purchase orders and drafts with supplier, totals and delivery progress.

Use status DRAFT to see drafts waiting to be published. Delivery does not change the status by itself: judge progress from fully_delivered and total_remaining rather than status.

statusstring: Filter by status, e.g. DRAFT, ORDERED, DELIVERED or COMPLETED.
supplier_idinteger: Only purchase orders for this supplier.
searchstring: Match on cart ID or supplier name.
created_afterstring: Created on or after this date (inclusive).
created_beforestring: Created on or before this date (inclusive).
sort"created_at" | "-created_at" | "updated_at" | "-updated_at" | "expected_date" | "-expected_date" | "delivered_date" | "-delivered_date" | "order_total" | "-order_total" | "status" | "-status" | "cart_id" | "-cart_id" | "supplier" | "-supplier": Field to sort by, ‘-’ prefix for descending. With status DRAFT only created_at, updated_at, order_total, cart_id and supplier are accepted.
pageinteger: Page number, starting at 1.
page_sizeinteger: Results per page, 1 to 100. The default of 25 keeps responses small.

purchase_orders_get Get one published purchase order with its lines, quantities delivered and remaining.

purchase_order_idinteger, required: Numeric purchase order id. Only published orders have one; a draft only has a string cart_id.

supplier_items_list List which supplier carries which items, with each supplier's article number, price, MOQ and lead time.

Use this to see who to buy an item from and on what terms.

supplier_idinteger: Only items carried by this supplier.
searchstring: Case-insensitive match on SKU, barcode or item name.
pageinteger: Page number, starting at 1.
page_sizeinteger: Results per page, 1 to 100. The default of 25 keeps responses small.

purchase_orders_recommend Calculate what to reorder: suggested purchase quantities based on sales, stock and lead time.

Use this for questions like "what should I order from this supplier". The calculation runs in the background; this waits up to about 10 seconds for it. If it is not finished, the response carries a task_id: call again later with only that task_id. Nothing is ordered; create a purchase order from the result with purchase_orders_create.

supplier_idinteger: Supplier to calculate reorder quantities for.
lead_time_daysinteger: Supplier lead time in days.
cover_daysinteger: Days of stock the order should cover.
history_daysinteger: Days of sales history to base the forecast on.
include_flaggedboolean: Include flagged products.
include_inboundboolean: Count stock already on its way as available.
task_idstring: Only to check on an earlier call that was still processing: pass its task_id, nothing else.

purchase_orders_create write Create a draft purchase order for one supplier.

A draft is not an order yet: nothing is sent to the supplier and the quantities do not count as incoming stock. Call purchase_orders_publish with the returned cart_id to place the order.

supplier_idinteger, required: Supplier to order from, from suppliers_list.
itemsPurchaseOrderLine[], required: Lines to order, at least one.
shipping_costnumber: Shipping cost. Can still be changed when publishing.
idempotency_keystring: Optional. Leave empty on the first attempt; one is generated and shown if the call fails. When retrying a call whose outcome you did not see, pass the same key so Stockpilot runs it only once.

purchase_orders_publish write Publish a draft purchase order, turning it into a real order at status ORDERED.

After this the quantities count as incoming stock. It emails the supplier only when send_email is true; that email cannot be taken back. The response carries the numeric purchase order id.

cart_idstring, required: The purchase order’s cart_id (a string), as returned by create.
expected_deliverystring: Expected delivery date in ISO format, e.g. ‘2026-11-15’.
delivery_warehouse_idinteger: Numeric warehouse id to deliver to. Defaults to the default warehouse.
order_notestring: Note stored on the purchase order.
shipping_costnumber: Overrides the shipping cost set on the draft.
processed_bystring: Who placed the order. Defaults to ‘API’.
send_emailboolean: Email the order sheet to the supplier. Only set this when the user asked for it.
supplier_messagestring: Message in the email to the supplier. Only used with send_email.
idempotency_keystring: Optional. Leave empty on the first attempt; one is generated and shown if the call fails. When retrying a call whose outcome you did not see, pass the same key so Stockpilot runs it only once.

purchase_orders_update write Change a draft or published purchase order: its lines, delivery details, notes or landed costs.

Pass one action per call with only the fields that action uses.

cart_idstring, required: The purchase order’s cart_id (a string), as returned by create.
action"add_cost" | "remove_cost" | "add_note" | "distribute_costs" | "update_details" | "add_line" | "update_line" | "remove_line", required: add_line / update_line / remove_line: change the ordered lines (identify the product with exactly one of product_id, sku or barcode). update_details: shipping_cost, expected_delivery, delivery_warehouse_id, order_note. add_note: message for the activity log. add_cost: landed cost (cost_type and amount). remove_cost: cost_id. distribute_costs: spread landed costs over the lines.
product_idinteger: Line product ID (line actions).
skustring: Line product SKU (line actions).
barcodestring: Line product barcode (line actions).
quantityinteger: Ordered quantity, a multiple of the product’s MOQ (add_line, update_line).
purchase_pricenumber: Unit purchase price (add_line, update_line).
supplier_referencestring: Supplier’s reference for the line.
shipping_costnumber: Shipping cost (update_details).
expected_deliverystring: Expected delivery as ISO datetime, e.g. 2026-11-02T10:00:00Z (update_details).
delivery_warehouse_idinteger: Numeric warehouse id (update_details).
order_notestring: Note on the order (update_details).
messagestring: Activity log note (add_note).
cost_type"FREIGHT" | "DUTIES" | "CUSTOMS" | "INSURANCE" | "HANDLING" | "OTHER": Kind of landed cost (add_cost).
amountnumber: Landed cost amount (add_cost).
descriptionstring: What the landed cost is for (add_cost).
referencestring: Your reference for the cost, e.g. an invoice number (add_cost).
cost_idinteger: ID of the landed cost to remove (remove_cost).

purchase_orders_update_status write Move a published purchase order to ORDERED, SHIPPED, CONFIRMED, DELIVERED or COMPLETED.

DELIVERED spreads landed costs over the received units. COMPLETED recalculates the order total from what was actually delivered, closes open parcels and stops counting the rest as incoming stock, so only complete an order the user says is finished. To book goods that arrived, use purchase_orders_receive instead.

cart_idstring, required: The purchase order’s cart_id (a string), as returned by create.
status"ORDERED" | "SHIPPED" | "CONFIRMED" | "DELIVERED" | "COMPLETED", required: Status to move the purchase order to.

purchase_orders_receive write Book a delivery against a purchase order, in full or in part, and add the goods to stock.

Use purchase_orders_get first to see what is still outstanding per line. By default the booking is queued: the response shows projected quantities and the stock follows shortly; check purchase_orders_get for confirmed numbers.

purchase_order_idinteger, required: Numeric purchase order id (only published orders have one), not the cart_id.
itemsReceivedLine[]: Lines that arrived. Leave empty to receive everything still outstanding.
referencestring: Reference for this delivery, e.g. a packing slip number.
wait_for_stockboolean: Wait until the stock has actually been booked. Slower; leave false for large orders.
idempotency_keystring: Optional. Leave empty on the first attempt; one is generated and shown if the call fails. When retrying a call whose outcome you did not see, pass the same key so Stockpilot runs it only once.

suppliers_create write Create a new supplier. Search suppliers_list first so the same supplier is not added twice.

namestring, required: Supplier name.
contact_namestring, required: Primary contact person.
contact_emailstring, required: Primary contact email address.
order_emailstring: Address purchase orders go to, if not the contact email.
phone_numberstring: Phone number.
websitestring: Website URL.
countrystring: Country as an ISO 2-letter code.
citystring: City.
currencystring: Default currency, ISO 4217, e.g. EUR.
lead_time_daysinteger: Default delivery lead time in days.
payment_terms_daysinteger: Payment term in days.
vat_numberstring: VAT registration number.
idempotency_keystring: Optional. Leave empty on the first attempt; one is generated and shown if the call fails. When retrying a call whose outcome you did not see, pass the same key so Stockpilot runs it only once.

supplier_items_update write Set the terms one supplier gives for one item: their article number, price, MOQ and lead time.

supplier_idinteger, required: Supplier whose terms change.
item_idinteger: Inventory item ID. Send exactly one of item_id, sku or barcode.
skustring: Item SKU. Send exactly one of item_id, sku or barcode.
barcodestring: Item barcode. Send exactly one of item_id, sku or barcode.
supplier_skustring: The supplier’s own article number for the item.
purchase_pricenumber: Agreed purchase price.
currencystring: Currency of purchase_price, ISO 4217.
moqinteger: Minimum order quantity at this supplier.
lead_time_daysinteger: Lead time in days for this item.

Warehouses, transfers and returns 10 tools

warehouses_list List warehouses and stock locations, including channel-managed ones (e.g. Shopify locations).

Each has a numeric `id` (used by transfers_create and purchase_orders_publish) and a string `unique_id` (used by warehouse_items_list and per-warehouse stock in inventory_update).

pageinteger: Page number, starting at 1.
page_sizeinteger: Results per page, 1 to 100. The default of 25 keeps responses small.

warehouse_items_list List the stock held in one warehouse, optionally narrowed to one SKU or barcode.

warehouse_unique_idstring, required: The warehouse’s unique_id from warehouses_list.
skustring: Only this SKU.
barcodestring: Only this barcode.
pageinteger: Page number, starting at 1.
page_sizeinteger: Results per page, 1 to 100. The default of 25 keeps responses small.

transfers_list List stock transfers between warehouses with source, destination, status and unit totals.

status"Draft" | "Shipped" | "Delivered": Only transfers in this status.
searchstring: Match on transfer ID or reference.
pageinteger: Page number, starting at 1.
page_sizeinteger: Results per page, 1 to 100. The default of 25 keeps responses small.

transfers_get Get one stock transfer with its lines.

transfer_idstring, required: Transfer ID, e.g. ‘TO-0000001’.

returns_list List customer returns with their order, items, reasons and handling state.

statusstring: Comma-separated statuses: requested, partly_accepted, accepted.
channel_handle"channel" | "amazon" | "bol" | "mirakl" | "etsy" | "kaufland" | "shopify" | "woocommerce" | "b2b-portal": Sales channel type. Must be given together with channel_id.
channel_idinteger: Sales channel id from sales_channels_list. Must be given with channel_handle.
pageinteger: Page number, starting at 1.
page_sizeinteger: Results per page, 1 to 100. The default of 25 keeps responses small.

transfers_create write Create a draft stock transfer between two warehouses.

Every line is taken out of the source warehouse's available stock the moment the draft is created, not when it ships. A draft that is no longer needed keeps that stock reserved until it is cancelled with transfers_cancel, so only create one the user actually wants. Shipping the transfer is done with transfers_ship.

source_warehouse_idinteger, required: Numeric id of the warehouse the stock leaves from (default or custom warehouse).
destination_warehouse_idinteger, required: Numeric id of the warehouse the stock goes to. Must differ from the source.
itemsTransferLine[], required: Lines to move, at least one.
referencestring: Free-text reference, searchable in transfers_list.
idempotency_keystring: Optional. Leave empty on the first attempt; one is generated and shown if the call fails. When retrying a call whose outcome you did not see, pass the same key so Stockpilot runs it only once.

transfers_add_items write Add lines to a draft transfer. A product already on it gets its quantity increased.

Stock for the new lines is reserved in the source warehouse straight away.

transfer_idstring, required: Transfer ID, e.g. ‘TO-0000001’.
itemsTransferLine[], required: Lines to add, at least one.
idempotency_keystring: Optional. Leave empty on the first attempt; one is generated and shown if the call fails. When retrying a call whose outcome you did not see, pass the same key so Stockpilot runs it only once.

transfers_ship write Ship a draft transfer: status becomes Shipped and the stock is booked at the destination.

For a custom warehouse the stock arrives as inbound until transfers_mark_delivered; for a Shopify location it goes straight into stock. After this the transfer can no longer be changed or cancelled.

transfer_idstring, required: Transfer ID, e.g. ‘TO-0000001’.
idempotency_keystring: Optional. Leave empty on the first attempt; one is generated and shown if the call fails. When retrying a call whose outcome you did not see, pass the same key so Stockpilot runs it only once.

transfers_mark_delivered write Mark a shipped transfer as delivered, moving its inbound stock into the destination's stock.

transfer_idstring, required: Transfer ID, e.g. ‘TO-0000001’.

transfers_cancel write Cancel a draft transfer and release the stock it reserved in the source warehouse.

transfer_idstring, required: Transfer ID, e.g. ‘TO-0000001’.

Account, channels and figures 6 tools

account_get Show which Stockpilot organization these API credentials belong to and which features it has enabled.

Use this first to confirm the connection works, or to check whether a feature such as purchase order or warehouse management is available before relying on it.

sales_channels_list List the connected sales channels (webshops and marketplaces) with their id, handle and sync state.

Use the id and handle to filter returns by channel.

pageinteger: Page number, starting at 1.
page_sizeinteger: Results per page, 1 to 100. The default of 25 keeps responses small.

analytics_item_sales Get sales figures for one item over the last N days: orders, units sold, revenue, prices and a demand forecast.

Use this for questions like "how fast does this sell" or "how much will I need next month". Pass exactly one of sku, barcode or id. Analytics is rate limited more tightly than other reads (about 20 calls a minute), so avoid calling it for many items in a row.

skustring: SKU of the item. Preferred identifier.
barcodestring: Barcode / EAN of the item.
idinteger: ID of the item, as the API’s ‘Product ID’. Prefer sku or barcode.
daysinteger: Number of days to look back.
include_channelsboolean: Add a breakdown per sales channel.
metrics"total_orders" | "total_items" | "revenue" | "forecast" | "pricing" | "daily_breakdown"[]: Metrics to include. Defaults to everything except daily_breakdown, which lists one row per day; add it only when the day-by-day trend is needed.

analytics_sales_summary Get the overall sales picture for the last N days: units, orders, revenue, average order value and best sellers.

Use this for "how did we do this month" or "what sells best". Rate limited like other analytics.

daysinteger: Number of days to look back.
top_itemsinteger: How many best-selling items to include.

analytics_product_order_history List every order that contained one item, with channel, date, quantity and customer.

Use this for customer support ("who bought this batch") or to see where an item sells. Pass exactly one of sku, barcode or id.

skustring: SKU of the item. Preferred identifier.
barcodestring: Barcode / EAN of the item.
idinteger: ID of the item, as the API’s ‘Product ID’. Prefer sku or barcode.
start_datestring: Only orders on or after this date.
end_datestring: Only orders on or before this date.

sales_channels_sync write Pull the latest listings from one sales channel into Stockpilot, in the background.

Safe to repeat: if a sync is already queued or running, nothing new is started and the response says so, with when the last sync ran.

channel_handlestring, required: The channel’s handle from sales_channels_list, e.g. ‘shopify’.
channel_idinteger, required: The channel’s id from sales_channels_list.
full_syncboolean: Re-import every listing instead of only changes. Slower; only for reconciling gaps.

Agents

MCP, CLI or llms.txt?

All three reach the same API with the same key. Pick the one that fits where your agent runs.

MCP for chat and IDE agents: tools appear in the client, nothing to install.
CLI for agents with a shell, and for everything the server leaves out.
llms.txt for coding agents writing their own integration against the API.

Give an agent warehouse access

claude

> Which open orders can't ship from stock?

stockpilot · orders_list
stockpilot · inventory_get × 6

2 of 12 open orders are short:
  SP-100231  330012 Enamel mug   need 4, have 2
  SP-100244  201156 Vichy 50 ml  need 6, have 3