# Core API

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

Manage customer groups, discounts, shipping methods and settings with the Core API, delete customers and look up customer-specific pricing.

> **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 Core API manages the configuration that controls how your B2B customers buy: customer groups, discounts, shipping methods and settings. It also lets you remove customers and check the prices a specific customer would pay.

## What the Core API covers

| Area | What you can do |
| --- | --- |
| Customer groups | List, create, update and delete customer groups, which can nest under a parent group |
| Discounts | List, create, update and delete discounts, and set the order in which they apply |
| Shipping | List, create, update and delete the shipping methods offered at checkout |
| Settings | Read and update global settings, such as price list selection, payment methods and order validation, and override them per customer group |
| Customers | Delete a customer, and fetch the prices a customer would pay for a list of SKUs |

## Where other data comes from

Products and customers aren't created through the Core API. SparkLayer syncs them from your eCommerce platform — through a built-in integration such as [Shopify](https://docs.sparklayer.io/help/platforms/shopify.md) or through [Ignite](https://docs.sparklayer.io/ignite.md) for other platforms.

For other B2B data, use the dedicated API:

| Data | API |
| --- | --- |
| Price lists and prices | [Pricing API](https://docs.sparklayer.io/developers/api/pricing.md) |
| Stock levels and stock locations | [Stock API](https://docs.sparklayer.io/developers/api/stock.md) |
| Orders, quotes and purchase transactions shown in My Account | [Purchasing API](https://docs.sparklayer.io/developers/api/purchasing.md) |
| Carts and orders placed on behalf of a customer | [Ordering API](https://docs.sparklayer.io/developers/api/ordering.md) |
| Files such as order attachments | [Files API](https://docs.sparklayer.io/developers/api/files.md) |
| Data sync status and errors | [Sync Logging API](https://docs.sparklayer.io/developers/api/sync-log.md) |

See the [API overview](https://docs.sparklayer.io/developers/api.md) for base URLs and authentication.

## Endpoints

- [DELETE Delete a customer](https://docs.sparklayer.io/developers/api/core/delete-a-customer.md)
- [POST Get customer-specific pricing](https://docs.sparklayer.io/developers/api/core/get-customer-specific-pricing.md)
- [GET List discounts](https://docs.sparklayer.io/developers/api/core/list-of-discounts.md)
- [POST Create a discount](https://docs.sparklayer.io/developers/api/core/create-a-discount.md)
- [PATCH Update discount priorities](https://docs.sparklayer.io/developers/api/core/update-discount-priorities.md)
- [GET Get a discount](https://docs.sparklayer.io/developers/api/core/get-a-discount.md)
- [PATCH Update a discount](https://docs.sparklayer.io/developers/api/core/update-a-discount.md)
- [DELETE Delete a discount](https://docs.sparklayer.io/developers/api/core/delete-a-discount.md)
- [GET List shipping methods](https://docs.sparklayer.io/developers/api/core/list-of-shipping-methods.md)
- [POST Create a shipping method](https://docs.sparklayer.io/developers/api/core/create-a-shipping-method.md)
- [GET Get a shipping method](https://docs.sparklayer.io/developers/api/core/get-a-shipping-method.md)
- [PATCH Update a shipping method](https://docs.sparklayer.io/developers/api/core/update-a-shipping-method.md)
- [DELETE Delete a shipping method](https://docs.sparklayer.io/developers/api/core/delete-a-shipping-method.md)
- [GET List global settings](https://docs.sparklayer.io/developers/api/core/list-global-settings.md)
- [PATCH Update global settings](https://docs.sparklayer.io/developers/api/core/update-global-setting.md)
- [GET List customer group settings](https://docs.sparklayer.io/developers/api/core/list-customer-group-settings.md)
- [PATCH Update customer group settings](https://docs.sparklayer.io/developers/api/core/update-customer-group-setting.md)
- [GET List customer groups](https://docs.sparklayer.io/developers/api/core/list-customer-groups.md)
- [POST Create a customer group](https://docs.sparklayer.io/developers/api/core/new-customer-group.md)
- [PATCH Update a customer group](https://docs.sparklayer.io/developers/api/core/update-customer-group.md)
- [DELETE Delete a customer group](https://docs.sparklayer.io/developers/api/core/delete-customer-group.md)
- [POST Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md)

## Next steps

- [Authentication](https://docs.sparklayer.io/developers/authentication.md): get an access token for your requests.
- [Pricing API](https://docs.sparklayer.io/developers/api/pricing.md): sync price lists and prices.