Skip to content
API referenceCustomers API

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, 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: 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: 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.
Build with AI: ready-made prompts and MCP setup
POST
/api/v2/customers/{lookupBy}/{identifier}/addresses

Adds an address to the customer and returns it with 200.

  • Send external_id (your ID for the address), id, or both. Without id, SparkLayer generates one. An id or external_id another address already has fails.
  • country_code is a 2-letter ISO 3166-1 code, such as GB. region_code is optional, but if you send it, it must be a region of that country.
  • is_default_shipping or is_default_billing set to true makes it the customer's default.

Authorization

bearerAuth
AuthorizationBearer <token>

Send Authorization: Bearer <access_token>, together with your Site-Id header, on every request. Get the token from POST /api/auth/token with your Site ID in the Site-Id header and a JSON body (not form-encoded, so standard OAuth 2.0 client libraries don't work): {"grant_type": "client_credentials", "client_id": "…", "client_secret": "…"}. Tokens are valid for 3,600 seconds and there is no refresh token: request a new one shortly before it expires. Create API credentials in the SparkLayer Dashboard under Settings > API. See Authentication.

In: header

Path Parameters

lookupBy*string

What identifier is: sparklayer (the customer's SparkLayer ID), platform (their ID on your eCommerce platform) or email (their email address).

Value in

  • "sparklayer"
  • "platform"
  • "email"
identifier*string

The customer's ID or email address, of the kind set by lookupBy. SparkLayer IDs are UUIDs; legacy cu_ IDs work too, except for shopping lists and favourites. Email lookups are exact and case-sensitive: URL-encode the address, with + as %2B.

Header Parameters

Site-Id*string

Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard.

Length1 <= length

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

id*string

SparkLayer Customer Address ID

Formatuuid
legacy_id?|

Legacy SparkLayer Customer Address ID

title?|

Title

Lengthlength <= 30
first_name?string

First Name

Lengthlength <= 50
last_name?string

Last Name

Lengthlength <= 50
company?|

Company

Lengthlength <= 128
address_line1?string

Address Line 1

Length1 <= length <= 255
address_line2?|

Address Line 2

Lengthlength <= 255
city?string

City

Length1 <= length <= 128
region_code?|

The region within the country, such as CA for California. Optional, but if you send it, it must be a region of country_code.

Lengthlength <= 10
postal_code?string

Postal Code

Lengthlength <= 20
country_code?string

The 2-letter ISO 3166-1 country code, such as GB.

Lengthlength <= 2
phone?|

Phone

Lengthlength <= 20
external_id?|

The identifier for the address on the e-commerce platform

Length1 <= length <= 124
is_default_shipping?boolean
is_default_billing?boolean
valid_for_purchase_id?|

A temporary address (typically used for drop shipping) only valid for a purchase ID

Formatuuid

Response Body

application/json

application/problem+json

curl -X POST "https://app.sparklayer.io/api/v2/customers/platform/7843024560291/addresses" \  -H "Authorization: Bearer <ACCESS_TOKEN>" \  -H "Site-Id: jones-climbing" \  -H "Content-Type: application/json" \  -d '{    "id": "9151f21f-43ae-43b4-92f3-f4af67cdf544",    "legacy_id": "ca_47",    "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_code": "CA",    "postal_code": "12345",    "country_code": "US",    "phone": "+44 (0) 123456789",    "external_id": "123456789",    "is_default_shipping": true,    "is_default_billing": true,    "valid_for_purchase_id": "3f2b8c1e-5d4a-4e6f-9b7c-1a2d3e4f5a6b"  }'
{  "id": "9151f21f-43ae-43b4-92f3-f4af67cdf544",  "legacy_id": "ca_47",  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z",  "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_name": "USA",  "country_code": "US",  "phone": "+44 (0) 123456789",  "external_id": "123456789",  "is_default_shipping": true,  "is_default_billing": true,  "valid_for_purchase_id": "64bd7a6d-6c6e-4483-b017-db631805fab6"}

GETList a customer's addresses

Returns all the customer's addresses, as a single array.

GETGet a customer address

Returns one of the customer's addresses.