# Build with AI URL: https://docs.sparklayer.io/developers/build-with-ai Build SparkLayer integrations with Claude, ChatGPT, Cursor or Claude Code: prompts for common jobs, Markdown docs, OpenAPI specs and the docs MCP server. > **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 ` and `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/.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. These docs are built to work with AI assistants such as Claude, ChatGPT and Cursor. There are three ways in: - **Start from a ready-made prompt** for a common job, such as syncing prices from your ERP. - **Point your assistant at the docs.** Every page has a Markdown version, and each API has an OpenAPI spec to download. - **Connect the docs MCP server**, so your assistant can search and read the docs while it writes code. ## Ready-made prompts Pick a job, add a line about your setup, and open the prompt in your assistant. Each prompt tells the assistant which pages to read, the facts every SparkLayer API call depends on, and what a production-ready result looks like: credentials in environment variables, retries, logging, a dry run and tests. ### Sync prices from your ERP Push price lists and SKU prices from your ERP or PIM into SparkLayer on a schedule. ```text I want you to build a scheduled job that keeps my B2B price lists and prices in SparkLayer in step with my ERP, using SparkLayer, the B2B ordering platform. My setup: [describe your system, language and hosting] Before writing any code, read these SparkLayer docs (Markdown versions): - https://docs.sparklayer.io/developers/authentication.md: getting and using an access token - https://docs.sparklayer.io/developers/api/pricing.md: how price lists and prices fit together - https://docs.sparklayer.io/developers/api/pricing/get-price-lists-v2.md: listing existing price lists (paginated) - https://docs.sparklayer.io/developers/api/pricing/create-a-price-list.md: creating missing price lists - https://docs.sparklayer.io/developers/api/pricing/update-pricing-by-price-list.md: updating the prices in one price list - https://docs.sparklayer.io/developers/api/pricing/update-pricing-for-multiple-price-lists.md: updating prices across price lists in one call - https://docs.sparklayer.io/developers/api/sync-log.md: recording each sync so it shows in the SparkLayer Dashboard - https://docs.sparklayer.io/developers/errors.md: error format and retries - https://docs.sparklayer.io/developers/pagination.md: paging through price lists If you can use MCP, connect to the SparkLayer docs MCP server (https://docs.sparklayer.io/mcp) to search the docs and fetch any API operation. Facts that 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 ` and `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. Steps: 1. Read the price lists and prices (including any quantity price breaks) from my ERP. 2. Fetch every SparkLayer price list with `GET /api/v2/price-lists`, following the pagination. 3. Create any price list that exists in my ERP but not in SparkLayer with `POST /api/v1/price-lists`, as the Pricing API docs describe for price lists managed by an external system. 4. Send the prices for each price list with `PATCH /api/v1/price-lists/{slug}/pricing`, or several price lists at once with `PATCH /api/v1/batch-update-pricing`, matching products by SKU and keeping each request within the documented limits. 5. Record each run with the Sync Logging API: a full sync for a complete run, a partial sync for changes only. Requirements: - Keep credentials (Site ID, Client ID, Client Secret) in environment variables or a secrets manager, never in code. - Cache the access token and request a new one shortly before it expires. - Retry 5xx, 429 (honouring Retry-After) and concurrent-update 409 responses with exponential backoff; on a 401, get a new token once and retry. Log every failed request with its status, `title` and `detail`. - Make each run safe to repeat, so a failed run can simply be run again. - Add a dry-run mode that logs what would change without calling the write endpoints. - Only send prices that changed since the last successful run, if my ERP can tell me. - Report SKUs that SparkLayer rejects, with the reason from the error response. - Use only endpoints, fields and SDK methods that the docs define. If something I need isn't documented, say so instead of guessing. Start by asking me anything you need to know about my setup. Then give me a short plan, the complete code, how to configure and run it, and how to test it against the SparkLayer test environment first. ``` ### Keep stock levels in sync Send stock levels per SKU and location from your ERP or WMS every few minutes. ```text I want you to build a scheduled job that keeps SparkLayer stock levels in step with my stock system, using SparkLayer, the B2B ordering platform. My setup: [describe your system, language and hosting] Before writing any code, read these SparkLayer docs (Markdown versions): - https://docs.sparklayer.io/developers/authentication.md: getting and using an access token - https://docs.sparklayer.io/developers/api/stock.md: stock levels and stock locations - https://docs.sparklayer.io/developers/api/stock/list-stock-locations.md: the stock locations SparkLayer knows about - https://docs.sparklayer.io/developers/api/stock/update-stock-levels.md: updating stock for many SKUs in one call - https://docs.sparklayer.io/developers/api/sync-log.md: recording each sync - https://docs.sparklayer.io/developers/errors.md: error format and retries If you can use MCP, connect to the SparkLayer docs MCP server (https://docs.sparklayer.io/mcp) to search the docs and fetch any API operation. Facts that 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 ` and `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. Steps: 1. Read current stock levels per SKU (and per warehouse, if I have several) from my stock system. 2. Map my warehouses to SparkLayer stock locations from `GET /api/v1/stock-locations`, and tell me if any are missing rather than guessing. 3. Send the levels with `POST /api/v1/batch-update-stock`, matching products by SKU, in batches within the documented limits. 4. Record each run with the Sync Logging API. Requirements: - Keep credentials (Site ID, Client ID, Client Secret) in environment variables or a secrets manager, never in code. - Cache the access token and request a new one shortly before it expires. - Retry 5xx, 429 (honouring Retry-After) and concurrent-update 409 responses with exponential backoff; on a 401, get a new token once and retry. Log every failed request with its status, `title` and `detail`. - Make each run safe to repeat, so a failed run can simply be run again. - Add a dry-run mode that logs what would change without calling the write endpoints. - Send only SKUs whose stock changed since the last run, if my system can tell me. - Never send a negative stock level unless the docs say it is allowed. - Use only endpoints, fields and SDK methods that the docs define. If something I need isn't documented, say so instead of guessing. Start by asking me anything you need to know about my setup. Then give me a short plan, the complete code, how to configure and run it, and how to test it against the SparkLayer test environment first. ``` ### Send B2B orders to your ERP Pick up new and updated B2B orders from SparkLayer and create them in your ERP. ```text I want you to build a job that picks up new and updated B2B orders from SparkLayer and creates or updates them in my ERP, using SparkLayer, the B2B ordering platform. My setup: [describe your system, language and hosting] Before writing any code, read these SparkLayer docs (Markdown versions): - https://docs.sparklayer.io/developers/authentication.md: getting and using an access token - https://docs.sparklayer.io/developers/api/purchasing.md: what a purchase is and how orders, quotes and carts differ - https://docs.sparklayer.io/developers/api/purchasing/get-purchases.md: listing orders with filters - https://docs.sparklayer.io/developers/api/purchasing/get-purchase.md: fetching one order in full - https://docs.sparklayer.io/developers/pagination.md: offset paging through purchases - https://docs.sparklayer.io/developers/errors.md: error format and retries If you can use MCP, connect to the SparkLayer docs MCP server (https://docs.sparklayer.io/mcp) to search the docs and fetch any API operation. Facts that 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 ` and `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. Steps: 1. List orders with `GET /api/v1/purchases`, filtered to orders updated since the last successful run (use the documented date filters, not my own), paging with `limit` and `offset`. 2. Fetch each order in full if the list response lacks fields I need, and map it to my ERP's sales order format, including lines, prices, tax, shipping and the customer. 3. Create the order in my ERP, or update it if it was already sent, keyed on the SparkLayer order ID so nothing is created twice. 4. Store the timestamp of the last order processed and resume from it on the next run. Requirements: - Keep credentials (Site ID, Client ID, Client Secret) in environment variables or a secrets manager, never in code. - Cache the access token and request a new one shortly before it expires. - Retry 5xx, 429 (honouring Retry-After) and concurrent-update 409 responses with exponential backoff; on a 401, get a new token once and retry. Log every failed request with its status, `title` and `detail`. - Make each run safe to repeat, so a failed run can simply be run again. - Add a dry-run mode that logs what would change without calling the write endpoints. - Don't write anything back to SparkLayer unless the docs show an endpoint for it. - Show me the field mapping as a table before writing the code. - Use only endpoints, fields and SDK methods that the docs define. If something I need isn't documented, say so instead of guessing. Start by asking me anything you need to know about my setup. Then give me a short plan, the complete code, how to configure and run it, and how to test it against the SparkLayer test environment first. ``` ### Import order history Load past orders from your ERP so B2B customers can see and reorder them. ```text I want you to build a one-off import (that can be re-run safely) of historic orders from my system into SparkLayer, using SparkLayer, the B2B ordering platform. My setup: [describe your system, language and hosting] Before writing any code, read these SparkLayer docs (Markdown versions): - https://docs.sparklayer.io/developers/authentication.md: getting and using an access token - https://docs.sparklayer.io/developers/api/purchasing.md: purchases, identifiers and what customers see - https://docs.sparklayer.io/developers/api/purchasing/create-update-purchase.md: creating or updating a purchase by your own ID - https://docs.sparklayer.io/developers/api/purchasing/create-or-update-a-purchase-transaction.md: recording payments against a purchase - https://docs.sparklayer.io/developers/errors.md: error format and retries If you can use MCP, connect to the SparkLayer docs MCP server (https://docs.sparklayer.io/mcp) to search the docs and fetch any API operation. Facts that 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 ` and `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. Steps: 1. Read my historic orders, their lines and their customers. 2. Create or update each one with `PUT /api/v1/purchases/{lookupBy}/{identifier}`, using my own order number as the identifier so running the import twice doesn't duplicate anything. 3. If my system has payments, record them with `PUT /api/v1/purchases/{lookupBy}/{identifier}/transactions`. 4. Write a report of orders that failed, with the reason. Requirements: - Keep credentials (Site ID, Client ID, Client Secret) in environment variables or a secrets manager, never in code. - Cache the access token and request a new one shortly before it expires. - Retry 5xx, 429 (honouring Retry-After) and concurrent-update 409 responses with exponential backoff; on a 401, get a new token once and retry. Log every failed request with its status, `title` and `detail`. - Make each run safe to repeat, so a failed run can simply be run again. - Add a dry-run mode that logs what would change without calling the write endpoints. - Process orders in batches and let me resume from where a run stopped. - Use only endpoints, fields and SDK methods that the docs define. If something I need isn't documented, say so instead of guessing. Start by asking me anything you need to know about my setup. Then give me a short plan, the complete code, how to configure and run it, and how to test it against the SparkLayer test environment first. ``` ### Give key accounts their own prices Create a price list per customer from your ERP contract prices, and check what a customer pays. ```text I want you to build customer-specific prices from my ERP's contract prices, kept up to date, using SparkLayer, the B2B ordering platform. My setup: [describe your system, language and hosting] Before writing any code, read these SparkLayer docs (Markdown versions): - https://docs.sparklayer.io/developers/authentication.md: getting and using an access token - https://docs.sparklayer.io/developers/api/pricing.md: price lists, including customer-specific ones - https://docs.sparklayer.io/help/pricing/customer-pricing.md: how a price list is linked to one customer on each platform - https://docs.sparklayer.io/developers/api/pricing/create-a-price-list.md: creating a price list - https://docs.sparklayer.io/developers/api/pricing/update-pricing-by-price-list.md: setting its prices - https://docs.sparklayer.io/developers/api/core/get-customer-specific-pricing.md: checking the prices a customer gets - https://docs.sparklayer.io/developers/errors.md: error format and retries If you can use MCP, connect to the SparkLayer docs MCP server (https://docs.sparklayer.io/mcp) to search the docs and fetch any API operation. Facts that 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 ` and `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. Steps: 1. For each customer with contract prices in my ERP, create (or reuse) a price list for them and send its prices by SKU. 2. Link the price list to the customer the way the docs describe for my eCommerce platform. If that step can't be done through the API, tell me exactly what to set up instead. 3. Check the result for a sample customer with `POST /api/v1/fetch-customer-pricing`. Requirements: - Keep credentials (Site ID, Client ID, Client Secret) in environment variables or a secrets manager, never in code. - Cache the access token and request a new one shortly before it expires. - Retry 5xx, 429 (honouring Retry-After) and concurrent-update 409 responses with exponential backoff; on a 401, get a new token once and retry. Log every failed request with its status, `title` and `detail`. - Make each run safe to repeat, so a failed run can simply be run again. - Add a dry-run mode that logs what would change without calling the write endpoints. - Name price lists so each one clearly maps to its customer. - Use only endpoints, fields and SDK methods that the docs define. If something I need isn't documented, say so instead of guessing. Start by asking me anything you need to know about my setup. Then give me a short plan, the complete code, how to configure and run it, and how to test it against the SparkLayer test environment first. ``` ### Upload invoices and documents Attach invoices, certificates and other files so B2B customers can download them. ```text I want you to build a job that uploads documents from my system to SparkLayer so customers can see them, using SparkLayer, the B2B ordering platform. My setup: [describe your system, language and hosting] Before writing any code, read these SparkLayer docs (Markdown versions): - https://docs.sparklayer.io/developers/authentication.md: getting and using an access token - https://docs.sparklayer.io/developers/api/files.md: how files, uploads and metadata work - https://docs.sparklayer.io/developers/api/files/create-a-new-file.md: creating a file and getting its upload URL - https://docs.sparklayer.io/developers/api/files/query-files-by-metadata.md: finding files you already uploaded - https://docs.sparklayer.io/developers/errors.md: error format and retries If you can use MCP, connect to the SparkLayer docs MCP server (https://docs.sparklayer.io/mcp) to search the docs and fetch any API operation. Facts that 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 ` and `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. Steps: 1. For each new document, create the file with `POST /api/v1/files`, with the metadata the docs describe for linking it to a customer or order. 2. Upload the file to the URL that response returns, exactly as the Files API docs describe. 3. Before uploading, check by metadata whether the document already exists, so nothing is uploaded twice. Requirements: - Keep credentials (Site ID, Client ID, Client Secret) in environment variables or a secrets manager, never in code. - Cache the access token and request a new one shortly before it expires. - Retry 5xx, 429 (honouring Retry-After) and concurrent-update 409 responses with exponential backoff; on a 401, get a new token once and retry. Log every failed request with its status, `title` and `detail`. - Make each run safe to repeat, so a failed run can simply be run again. - Add a dry-run mode that logs what would change without calling the write endpoints. - Handle files that fail SparkLayer's checks after upload (see the `410` status in the errors guide). - Use only endpoints, fields and SDK methods that the docs define. If something I need isn't documented, say so instead of guessing. Start by asking me anything you need to know about my setup. Then give me a short plan, the complete code, how to configure and run it, and how to test it against the SparkLayer test environment first. ``` ### Build a headless B2B storefront Use the JavaScript SDK in your own frontend for B2B prices, cart and account. ```text I want you to build B2B pricing, cart and account features in my own frontend with the SparkLayer JavaScript SDK, using SparkLayer, the B2B ordering platform. My setup: [describe your system, language and hosting] Before writing any code, read these SparkLayer docs (Markdown versions): - https://docs.sparklayer.io/developers/javascript-sdk.md: what the SDK does - https://docs.sparklayer.io/developers/javascript-sdk/headless.md: loading and initialising the SDK yourself - https://docs.sparklayer.io/developers/javascript-sdk/reference/methods.md: every SDK method - https://docs.sparklayer.io/developers/javascript-sdk/reference/options.md: every option - https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md: reacting to cart changes - https://docs.sparklayer.io/developers/javascript-sdk/products-and-pricing.md: showing B2B prices, price breaks and pack sizes - https://docs.sparklayer.io/developers/javascript-sdk/cart.md: adding to and reading the cart - https://docs.sparklayer.io/developers/frontend.md: the Core Script and where it is configured If you can use MCP, connect to the SparkLayer docs MCP server (https://docs.sparklayer.io/mcp) to search the docs and fetch any API operation. Steps: 1. Load and initialise the SDK as the headless guide describes, once, on the client only. 2. Show B2B prices on product pages with the documented pricing methods, including price breaks and pack sizes. 3. Add to cart and read the cart with the documented cart methods, and react to cart changes with the `onCartUpdate` hook. 4. Wrap the SDK in a small typed module for my framework, waiting for it to be ready before calling it. Requirements: - Use only the SDK methods, options and hooks in the reference. - Prefer documented options, hooks and custom slots. Customising SparkLayer's own components is fine too: keep HTML changes targeted and note what to check after SparkLayer updates. - Use only endpoints, fields and SDK methods that the docs define. If something I need isn't documented, say so instead of guessing. Start by asking me anything you need to know about my setup. Then give me a short plan, the complete code, how to configure and run it, and how to test it against the SparkLayer test environment first. ``` ### Add a custom checkout rule Block checkout until the cart meets your own rule, with a clear message. ```text I want you to build a custom checkout validation rule using the SparkLayer JavaScript SDK, using SparkLayer, the B2B ordering platform. My setup: [describe your system, language and hosting] Before writing any code, read these SparkLayer docs (Markdown versions): - https://docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md: the `onCheckoutValidation` hook - https://docs.sparklayer.io/developers/javascript-sdk/reference/types.md: the cart types - https://docs.sparklayer.io/developers/javascript-sdk/checkout.md: working checkout validation examples - https://docs.sparklayer.io/developers/javascript-sdk/setup.md: adding hooks without overwriting existing options - https://docs.sparklayer.io/help/storefront/storefront-options.md: where Core Script settings go If you can use MCP, connect to the SparkLayer docs MCP server (https://docs.sparklayer.io/mcp) to search the docs and fetch any API operation. Steps: 1. Implement the rule in the `onCheckoutValidation` hook, returning the documented error format. 2. Show customers a clear message that explains how to fix their cart. 3. Add the code to my theme in the place the docs describe, without overwriting existing `sparkOptions`. Requirements: - Keep the hook fast: avoid network calls on every check unless the rule needs them. - Use only endpoints, fields and SDK methods that the docs define. If something I need isn't documented, say so instead of guessing. Start by asking me anything you need to know about my setup. Then give me a short plan, the complete code, how to configure and run it, and how to test it against the SparkLayer test environment first. ``` ### Connect a new platform with Ignite Build the service that connects an unsupported commerce platform to SparkLayer. ```text I want you to build an Ignite integration service that connects my commerce platform to SparkLayer, using SparkLayer, the B2B ordering platform. My setup: [describe your system, language and hosting] Before writing any code, read these SparkLayer docs (Markdown versions): - https://docs.sparklayer.io/ignite.md: what Ignite is and how the pieces fit - https://docs.sparklayer.io/ignite/platform-connection.md: connecting a store - https://docs.sparklayer.io/ignite/authentication.md: customer authentication - https://docs.sparklayer.io/ignite/data-sync.md: syncing products, customers and orders - https://docs.sparklayer.io/ignite/endpoints-overview.md: every endpoint your service implements If you can use MCP, connect to the SparkLayer docs MCP server (https://docs.sparklayer.io/mcp) to search the docs and fetch any API operation. Facts that 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 ` and `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. Steps: 1. Implement the endpoints in the Ignite spec (https://docs.sparklayer.io/openapi/ignite.yaml) that my platform needs, starting with the platform connection and authentication. 2. Implement data sync for products, customers and orders as the Ignite docs describe. 3. Implement checkout: calculating tax and shipping, and completing the checkout on my platform. 4. Write integration tests for each endpoint with example requests from the spec. Requirements: - Keep credentials (Site ID, Client ID, Client Secret) in environment variables or a secrets manager, never in code. - Cache the access token and request a new one shortly before it expires. - Retry 5xx, 429 (honouring Retry-After) and concurrent-update 409 responses with exponential backoff; on a 401, get a new token once and retry. Log every failed request with its status, `title` and `detail`. - Make each run safe to repeat, so a failed run can simply be run again. - Add a dry-run mode that logs what would change without calling the write endpoints. - Where the docs leave something open (for example how SparkLayer authenticates its calls to your service), list it as a question for SparkLayer rather than assuming. - Use only endpoints, fields and SDK methods that the docs define. If something I need isn't documented, say so instead of guessing. Start by asking me anything you need to know about my setup. Then give me a short plan, the complete code, how to configure and run it, and how to test it against the SparkLayer test environment first. ``` Each prompt asks the assistant to start with questions and a plan, and to test against the SparkLayer [test environment](https://docs.sparklayer.io/developers/authentication.md#environments) first. Review the code before you run it on your live store. ## Point any assistant at the docs Paste one of these links into your assistant, or add it to your tool's documentation sources: | Resource | What's in it | Link | | --- | --- | --- | | Any page, as Markdown | Add `.md` to a page's URL, or request it with `Accept: text/markdown` | [/developers/quickstart.md](https://docs.sparklayer.io/developers/quickstart.md) | | `llms.txt` | Every page with a one-line summary, plus the facts below | [/llms.txt](https://docs.sparklayer.io/llms.txt) | | API index | Every API operation, compactly, with links to each operation | [/llms-api.txt](https://docs.sparklayer.io/llms-api.txt) | | Developer docs | The developer guides in full, with the API index | [/developers/llms.txt](https://docs.sparklayer.io/developers/llms.txt) | | OpenAPI specs | One spec per API, in YAML and JSON, for code generation and tools. The index lists them all | `https://docs.sparklayer.io/openapi/index.json` | Developer pages also open with a **For AI assistants** panel: the facts below, so an assistant gets them from whichever page you share. ## The facts your assistant needs These apply to every SparkLayer API call. They come from [Authentication](https://docs.sparklayer.io/developers/authentication.md), [Errors](https://docs.sparklayer.io/developers/errors.md) and [Pagination](https://docs.sparklayer.io/developers/pagination.md). - **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 ` and `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/.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. ## Connect the docs MCP server The docs MCP server lets an assistant search these docs, read any page and look up API operations while it writes your code. It's free, read-only and needs no account. The server URL is: ```text title="MCP server" https://docs.sparklayer.io/mcp ``` **Claude Code:** Run this once in your project: ```bash title="Terminal" claude mcp add --transport http sparklayer-docs https://docs.sparklayer.io/mcp ``` **Claude:** In Claude, open **Settings** > **Connectors**, choose **Add custom connector**, and enter the server URL. Then turn the connector on in your chat. **Cursor:** Add the server to `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` for every project): ```json title=".cursor/mcp.json" { "mcpServers": { "sparklayer-docs": { "url": "https://docs.sparklayer.io/mcp" } } } ``` **VS Code:** Add the server to `.vscode/mcp.json` in your project, then start it from the file: ```json title=".vscode/mcp.json" { "servers": { "sparklayer-docs": { "type": "http", "url": "https://docs.sparklayer.io/mcp" } } } ``` **ChatGPT:** In ChatGPT, add a connector with the server URL from **Settings** > **Apps & Connectors**. Custom connectors need developer mode, which your workspace admin may need to turn on. The server has tools to search the docs, read a page, list pages, and look up API operations and specs. Your assistant decides when to use them. ## Get better results - **Start in the test environment.** Create an API key in [Test mode](https://docs.sparklayer.io/developers/authentication.md#environments) and point your code at `https://test.app.sparklayer.io` until it works. - **Ask for a plan first.** A short plan and field mapping are quicker to correct than finished code. - **Generate types from the specs.** Tools such as `openapi-typescript` or `openapi-generator` turn the OpenAPI specs (listed at `https://docs.sparklayer.io/openapi/index.json`) into typed clients, so your assistant can't invent fields. - **Keep credentials out of chats.** Give the assistant variable names, such as `SPARKLAYER_CLIENT_SECRET`, never the real values. - **Check against the reference.** If an assistant uses an endpoint or field you can't find in the [API reference](https://docs.sparklayer.io/developers/api.md), ask it where it came from. ## Next steps - [Quickstart](https://docs.sparklayer.io/developers/quickstart.md): Make your first API call in five minutes - [API reference](https://docs.sparklayer.io/developers/api.md): Every endpoint, with examples - [JavaScript SDK](https://docs.sparklayer.io/developers/javascript-sdk.md): Storefront examples to start from, and a prompt for SDK work