Skip to content
Ignite endpoints

Create a customer address

For AI assistants: the facts every SparkLayer API call needs
  • 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 409s 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.
  • Ignite: With Ignite, SparkLayer calls endpoints that your service implements (the Ignite spec), and your service calls the SparkLayer APIs above for everything else.
  • Read the docs as Markdown: Add .md to any page URL. Index of every page: docs.sparklayer.io/llms.txt. Every API operation, compactly: docs.sparklayer.io/llms-api.txt. The developer guides in full: 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.
Build with AI: ready-made prompts and MCP setup

Implemented by your integration

This is an Ignite endpoint: your integration service implements it and SparkLayer calls it. Use this reference to build and test your implementation.
POST/v1/{siteEnv}/{siteId}/customers/{customer_external_id}/addresses

Create a new "address" for a customer on the specific platform.

Path Parameters

siteEnv*string

The SparkLayer environment the request is for, such as live. Store it, with the site ID, when SparkLayer connects your platform.

siteId*string

The SparkLayer site ID the request is for, such as bobs-store. Store it, with the environment, when SparkLayer connects your platform.

Length1 <= length
customer_external_id*string

The customer's ID on your platform.

Length1 <= length

Request Body

application/json

Address

TypeScript Definitions

Use the request body type in TypeScript.

title?|
Lengthlength <= 30
first_name?|
Lengthlength <= 50
last_name?|
Lengthlength <= 50
company?|
Lengthlength <= 128
address_line1?string
Lengthlength <= 255
address_line2?|
Lengthlength <= 255
city?string
Lengthlength <= 128
region_name?|
Lengthlength <= 128
region_code?|
Lengthlength <= 10
postal_code?|
Lengthlength <= 20
country_code?string

Two letter country code as defined by ISO 3166-2

Lengthlength <= 2
phone?string
Lengthlength <= 20
is_default_shipping?boolean
is_default_billing?boolean
is_temporary?boolean

Whether the address is temporary for the duration of a cart. This value is only relevant to platforms that create the order address automatically on order creation (or conversion from draft to normal order as in the case of our Shopify integration). In such cases we will want the integration to ensure this address does not get created in SparkLayer when the platform notifes the integration of a new customer address.

Response Body

application/json

curl -X POST "https://ignite.example.com/v1/live/bobs-store/customers/CUS1234/addresses" \  -H "Content-Type: application/json" \  -d '{    "title": "Mr",    "first_name": "Bob",    "last_name": "Jones",    "company": "Tom Jones Climbing Ltd",    "address_line1": "Example Industrial Estate",    "address_line2": "North Country",    "city": "Cityland",    "region_name": "California",    "region_code": "CA",    "postal_code": "12345",    "country_code": "US",    "phone": "+44 (0) 123456789",    "is_default_shipping": true,    "is_default_billing": true,    "is_temporary": true  }'
{  "title": "Mr",  "first_name": "Bob",  "last_name": "Jones",  "company": "Tom Jones Climbing Ltd",  "address_line1": "Example Industrial Estate",  "address_line2": "North Country",  "city": "Cityland",  "region_name": "California",  "region_code": "CA",  "postal_code": "12345",  "country_code": "US",  "phone": "+44 (0) 123456789",  "is_default_shipping": true,  "is_default_billing": true,  "customer_address_external_id": "string"}

PATCHUpdate a sub-account

Update the details of an existing customer sub-account. This allows changing the account's first name, last name and role. This does not allow for the email to be updated.

PUTUpdate a customer address

Update a customer address on the specific platform.