# Stockpilot API

> REST API for multi-channel e-commerce operations: inventory, orders, products,
> returns, purchase orders, shipping, analytics and outbound webhooks. Every
> endpoint is authenticated with `X-CLIENT-ID` and `X-CLIENT-SECRET` headers.

## Authentication

Send both headers on every request:

```
X-CLIENT-ID: your_client_id
X-CLIENT-SECRET: your_client_secret
```

Missing or invalid credentials return `401`. Verify a credential pair with
`GET /auth/who-is`.

## Conventions

- **Pagination**: `page` (default 1) and `page_size` (default 100, max 100) query
  parameters. Responses carry `count`, `current_page`, `total_pages` and boolean
  `next` / `previous` - page until `current_page == total_pages`.
- **Dates**: ISO `YYYY-MM-DD`; timestamps ISO 8601 with timezone.
- **Product lookup**: many endpoints accept exactly one of `id`, `sku` or `barcode`.
- **Errors**: JSON body with a `detail` or `error` key.
- **Rate limits**: advisory, per API key, per 60s window - 300 single reads,
  120 list reads, 60 writes, 20 heavy (analytics, labels, channel sync). Every
  response carries `X-RateLimit-Limit`, `-Remaining`, `-Reset` and `-Policy`.
  Nothing is rejected with `429` today.
- **Idempotency**: no `Idempotency-Key` header. `GET`s and absolute-value updates
  are safe to retry; creates are not - poll before resending one.

## Endpoints

### Authentication

- `GET /auth/who-is` - Verify API credentials

### Products

- `GET /products` - Get paginated list of products
- `POST /products/create` - Create a new product
- `GET /products/get` - Get product by ID
- `POST /products/{product_id}/set-image` - Set image for a product

### Categories & Brands

- `GET /brands` - List all brands
- `POST /brands/create` - Create a brand
- `GET /categories` - List all categories
- `POST /categories/create` - Create a category

### Inventory

- `GET /inventory` - List inventory items
- `POST /inventory/create` - Create a new inventory item
- `GET /inventory/get` - Get single inventory item by barcode, SKU, or ID
- `POST /inventory/update` - Update inventory item
- `POST /inventory/{item_id}/set-image` - Set image for an inventory item

### Bundles

- `GET /bundles/` - Get Bundles
- `POST /bundles/create` - Create Bundle
- `GET /bundles/{bundle_id}` - Get Bundle Detail
- `PATCH /bundles/{bundle_id}` - Update Bundle
- `DELETE /bundles/{bundle_id}` - Delete Bundle
- `POST /bundles/{bundle_id}/items/add` - Add Bundle Items
- `DELETE /bundles/{bundle_id}/items/{product_id}/delete` - Remove Bundle Item
- `PUT /bundles/{bundle_id}/items/{product_id}/update` - Update Bundle Item

### Warehouses

- `GET /warehouses/get` - List warehouses
- `GET /warehouses/{unique_id}/items` - List warehouse items

### Orders

- `GET /orders` - List orders
- `PUT /orders/cancel-order` - Cancel order
- `GET /orders/cancellation-request` - Check cancellation request
- `GET /orders/cancellation-requests` - Get orders with cancellation requests
- `POST /orders/create` - Create a new order
- `POST /orders/fulfil` - Fulfil an order
- `GET /orders/fulfillment` - Get fulfillment details
- `GET /orders/get-single` - Get single order
- `PATCH /orders/ordered-items/{item_id}/update` - Update ordered item details
- `DELETE /orders/{order_id}` - Delete entire order
- `DELETE /orders/{order_id}/items/{item_id}` - Delete order item
- `POST /orders/{order_id}/move-from-backorder` - Move order items from backorder
- `POST /orders/{order_id}/move-to-backorder` - Move order items to backorder
- `PATCH /orders/{order_id}/update-customer-details` - Update order customer details
- `PATCH /orders/{order_id}/update-forwarding` - Update order forwarding status
- `PATCH /orders/{order_id}/update-status` - Update order status
- `POST /orders/{order_pk}/items/add` - Add item to order
- `POST /orders/{order_pk}/items/swap` - Swap order item product

### Returns

- `GET /returns` - List returns

### Purchase Orders

- `GET /purchase-orders` - Get purchase orders list
- `POST /purchase-orders` - Create purchase order
- `POST /purchase-orders/recommendations` - Start purchase order recommendations generation
- `GET /purchase-orders/recommendations/status/{task_id}` - Get recommendations task status
- `GET /purchase-orders/suppliers/list` - Get suppliers list
- `GET /purchase-orders/{order_id}` - Get purchase order details
- `POST /purchase-orders/{order_id}/parcels/create` - Create a parcel against a purchase order
- `POST /purchase-orders/{order_id}/parcels/{parcel_id}/delete` - Remove an unprocessed parcel

### Invoices

- `GET /invoices/get/{order_pk}` - Get invoice for an order
- `POST /invoices/send` - Send invoice for an order

### Shipping

- `GET /shipping/integrations` - List available shipping integrations
- `GET /shipping/label-suggestion` - Get label suggestion based on shipping rules
- `GET /shipping/label-templates` - Get available shipping label templates
- `POST /shipping/request-label` - Request a shipping label
- `POST /shipping/retrieve-label` - Retrieve a generated shipping label

### Customers

- `GET /customers` - List customers
- `PATCH /customers/{customer_id}/update` - Update customer details

### Analytics

- `GET /analytics/items/sales` - Get item sales analytics
- `GET /analytics/product-order-history` - Get product order history
- `GET /analytics/sales-summary` - Get sales summary

### Sales Channels

- `GET /sales-channels` - List all channels
- `POST /sales-channels/sync-listings` - Sync listings for a channel

### Webhooks

- `GET /webhooks` - List webhooks
- `POST /webhooks/create` - Create a webhook
- `GET /webhooks/events` - List available event types
- `GET /webhooks/{webhook_id}` - Get a webhook
- `POST /webhooks/{webhook_id}/delete` - Delete a webhook
- `GET /webhooks/{webhook_id}/deliveries` - List recent deliveries
- `POST /webhooks/{webhook_id}/reactivate` - Reactivate a webhook
- `POST /webhooks/{webhook_id}/test` - Send a test delivery
- `POST /webhooks/{webhook_id}/update` - Update a webhook

## Guides

- **Rate Limits & Idempotency** - Limits are applied **per API key** - per `X-CLIENT-ID` / `X-CLIENT-SECRET` pair - in fixed 60 second windows. Full text in `/llms-full.txt`.
- **Webhook Delivery Contract** - Stockpilot pushes events to an HTTPS endpoint you control. Full text in `/llms-full.txt`.

## Full documentation

- [/llms-full.txt](/llms-full.txt): every operation with parameters, request bodies and response examples, plus the guides above.
- [/openapi.json](/openapi.json): machine-readable OpenAPI schema.
- [/redoc](/redoc): human-readable reference (rendered client-side; not readable by fetching).