# Shipping API

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

The Shipping API lets you manipulate SparkLayer shipping methods, used when 'SparkLayer shipping rates' are enabled.

> **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, and the Customers API (`/api/v2/customers`) over the legacy `DELETE /api/v1/customers` in the Core API. 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:** `customers`, `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 Shipping API holds any SparkLayer shipping methods you have set. If 'Sparklayer shipping rates' is enabled, SparkLayer uses these methods to determine shipping costs and availability.

## How it works

- **Shipping Methods** contain display information and a list of **bands**. Each **band** contains a cost and, optionally, a requirement to be met for the band to apply. **Bands** are applied in descending priority (so a band with a priority of 2 will apply instead of a band with a priority of 1 if both are applicable).
- **Shipping Methods** apply to a specific set of locations and customer groups, defined in **locations** and **groups** respectively.
- **Shipping Methods** are indexed by UUID.

## Endpoints

- [GET Get a shipping method (legacy)](https://docs.sparklayer.io/developers/api/shipping/get-a-shipping-method-legacy.md)
- [GET List shipping methods](https://docs.sparklayer.io/developers/api/shipping/list-all-shipping-methods.md)
- [POST Create a shipping method](https://docs.sparklayer.io/developers/api/shipping/create-a-shipping-method.md)
- [GET Get a shipping method](https://docs.sparklayer.io/developers/api/shipping/get-a-shipping-method.md)
- [PATCH Update a shipping method](https://docs.sparklayer.io/developers/api/shipping/update-a-shipping-method.md)
- [DELETE Delete a shipping method](https://docs.sparklayer.io/developers/api/shipping/delete-a-shipping-method.md)

## Next Steps

- [SparkLayer shipping settings](https://docs.sparklayer.io/help/dashboard/settings.md#shipping): enable SparkLayer
  shipping rates
- [Stock API](https://docs.sparklayer.io/developers/api/stock.md): sync stock levels alongside your prices.