# Stock API

URL: https://docs.sparklayer.io/developers/api/stock

The Stock API reads, batch updates and deletes stock levels by SKU and manages stock locations for your SparkLayer site. Lists every endpoint and its responses.

> **For AI assistants:** these facts apply to every SparkLayer API call.
>
> - **Base URLs:** Live `https://app.sparklayer.io`, test `https://test.app.sparklayer.io`. Each environment has its own data and its own API keys.
> - **Access:** API access needs the Pro or Enterprise plan. Create credentials (Site ID, Client ID, Client Secret) in the SparkLayer Dashboard at Settings > API.
> - **Access token:** `POST {base}/api/auth/token` with a `Site-Id` header and a JSON body (not form-encoded): `{"grant_type":"client_credentials","client_id":"…","client_secret":"…"}`. It returns `access_token`, valid for 3,600 seconds. There is no refresh token: cache the token and request a new one shortly before it expires.
> - **Every request:** `Authorization: Bearer <access_token>` and `Site-Id: <site id>`, plus `Content-Type: application/json` when there is a body. Set a `User-Agent` that names your integration.
> - **Errors:** RFC 7807 problem details: `title`, `status`, `detail` and an optional `errors[]` of `{ code, message, property }`. Some error responses have no body. Retry `5xx`, `429` (honouring `Retry-After`) and concurrent-update `409`s with exponential backoff; on `401`, get a new token once and retry; don't retry other `4xx` without changing the request.
> - **Pagination:** Most list endpoints return everything. `GET /api/v2/price-lists` pages with `page` and `page_size` (up to 250) until `pagination.current_page` equals `total_pages`. `GET /api/v1/purchases` uses `limit` (up to 500) and `offset`: stop when a page has fewer than `limit` results.
> - **Ground rules:** Use only endpoints, fields and SDK methods that the docs or OpenAPI specs define. Prefer `GET /api/v2/price-lists` over the deprecated v1. Products are matched by SKU. Keep credentials in environment variables or a secrets manager, never in code.
> - **Read the docs as Markdown:** Add `.md` to any page URL. Index of every page: https://docs.sparklayer.io/llms.txt. Every API operation, compactly: https://docs.sparklayer.io/llms-api.txt. The developer guides in full: https://docs.sparklayer.io/developers/llms.txt.
> - **OpenAPI specs:** `core`, `ordering`, `pricing`, `purchasing`, `stock`, `files`, `sync-log`: https://docs.sparklayer.io/openapi/<api>.yaml (also `.json`). Ignite: https://docs.sparklayer.io/openapi/ignite.yaml.
> - **MCP:** Search and read these docs from your assistant with the docs MCP server at https://docs.sparklayer.io/mcp.

The Stock API holds the stock level of each SKU at each of your stock locations, such as warehouses. SparkLayer uses these levels to show stock on the storefront.

## How it works

- **Stock locations** identify where stock is held. Each has a SparkLayer `id` and your own `external_id`, and you can use either to refer to it.
- **Stock levels** are set in bulk: **Update stock levels for multiple SKUs** creates or overwrites the level for each SKU and location pair you send, and leaves other pairs unchanged.
- **Get stock levels for multiple SKUs** only returns the location with the external ID `default` unless you ask for all locations or specific ones.

## Endpoints

- [POST Get stock levels for multiple SKUs](https://docs.sparklayer.io/developers/api/stock/get-stock-levels.md)
- [POST Update stock levels for multiple SKUs](https://docs.sparklayer.io/developers/api/stock/update-stock-levels.md)
- [POST Delete stock levels for multiple SKUs](https://docs.sparklayer.io/developers/api/stock/delete-stock-levels.md)
- [GET List stock locations](https://docs.sparklayer.io/developers/api/stock/list-stock-locations.md)
- [POST Create a stock location](https://docs.sparklayer.io/developers/api/stock/create-a-stock-location.md)
- [GET Get a stock location](https://docs.sparklayer.io/developers/api/stock/get-a-stock-location.md)
- [PATCH Update a stock location](https://docs.sparklayer.io/developers/api/stock/update-a-stock-location.md)
- [DELETE Delete a stock location](https://docs.sparklayer.io/developers/api/stock/delete-a-stock-location.md)

## Next steps

- [Stock display](https://docs.sparklayer.io/help/storefront/stock-display.md): how stock levels show to B2B customers.
- [Pricing API](https://docs.sparklayer.io/developers/api/pricing.md): sync prices alongside stock.