Spree SDK

import { createClient } from '@spree/sdk'

const client = createClient({
  baseUrl: 'https://your-store.com',
  publishableKey: '<api-key>',
})

const addresses = await client.carts.addresses.list(
  'cart_abc123',
  {},
  {
    token: '<token>',
  },
)

{
  "data": [
    {
      "id": "addr_UkLWZg9DAJ",
      "label": null,
      "first_name": "John",
      "last_name": "Doe",
      "full_name": "John Doe",
      "address1": "362 Lovely Street",
      "address2": "Northwest",
      "postal_code": "10118",
      "city": "New York",
      "phone": "555-555-0199",
      "company": "Company",
      "country_name": "United States",
      "country_code": "US",
      "state_text": "NY",
      "state_code": "NY",
      "quick_checkout": false,
      "is_default_billing": false,
      "is_default_shipping": true,
      "state_abbr": "NY",
      "country_iso": "US",
      "state_name": "New York",
      "owner": {
        "id": "cust_UkLWZg9DAJ",
        "type": "customer",
        "name": null
      }
    },
    {
      "id": "addr_gbHJdmfrXB",
      "label": null,
      "first_name": "John",
      "last_name": "Doe",
      "full_name": "John Doe",
      "address1": "363 Lovely Street",
      "address2": "Northwest",
      "postal_code": "10118",
      "city": "New York",
      "phone": "555-555-0199",
      "company": "Company",
      "country_name": "United States",
      "country_code": "US",
      "state_text": "NY",
      "state_code": "NY",
      "quick_checkout": false,
      "is_default_billing": true,
      "is_default_shipping": false,
      "state_abbr": "NY",
      "country_iso": "US",
      "state_name": "New York",
      "owner": {
        "id": "cust_UkLWZg9DAJ",
        "type": "customer",
        "name": null
      }
    },
    {
      "id": "addr_EfhxLZ9ck8",
      "label": null,
      "first_name": "John",
      "last_name": "Doe",
      "full_name": "John Doe",
      "address1": "364 Lovely Street",
      "address2": "Northwest",
      "postal_code": "10118",
      "city": "New York",
      "phone": "555-555-0199",
      "company": "Company",
      "country_name": "United States",
      "country_code": "US",
      "state_text": "NY",
      "state_code": "NY",
      "quick_checkout": false,
      "is_default_billing": false,
      "is_default_shipping": false,
      "state_abbr": "NY",
      "country_iso": "US",
      "state_name": "New York",
      "owner": {
        "id": "cust_UkLWZg9DAJ",
        "type": "customer",
        "name": null
      }
    }
  ],
  "meta": {
    "page": 1,
    "limit": 25,
    "count": 3,
    "pages": 1,
    "from": 1,
    "to": 3,
    "in": 3,
    "previous": null,
    "next": null
  }
}

{
  "error": {
    "code": "authentication_required",
    "message": "Authentication required"
  }
}

{
  "error": {
    "code": "record_not_found",
    "message": "Cart not found"
  }
}

List addresses this cart may use

Everything a checkout address step may offer for this cart: the buyer’s own address book, plus the address book of the company set as the cart’s company_id — that company’s own sites and the ones it inherits from the companies above it. Only addresses in a country the cart’s market sells to are listed.

Requires a signed-in customer, unlike the rest of the cart endpoints. The response is the account’s address books rather than the cart’s own data, so a guest cart token is not accepted here. A guest cart has neither book and would get an empty list in any case.

Each entry carries the owner it was filed under — the customer, or the company node that owns the site — so a picker can group and label them from one response. An inherited site names the node above, not the one the cart is for.

Any address returned here is accepted as shipping_address_id or billing_address_id on the cart, so the picker and the cart cannot disagree. Curating either book stays with /store/customers/me/addresses and /store/companies/{company_id}/addresses.

GET

api

store

carts

{cart_id}

addresses

Spree SDK

import { createClient } from '@spree/sdk'

const client = createClient({
  baseUrl: 'https://your-store.com',
  publishableKey: '<api-key>',
})

const addresses = await client.carts.addresses.list(
  'cart_abc123',
  {},
  {
    token: '<token>',
  },
)

{
  "data": [
    {
      "id": "addr_UkLWZg9DAJ",
      "label": null,
      "first_name": "John",
      "last_name": "Doe",
      "full_name": "John Doe",
      "address1": "362 Lovely Street",
      "address2": "Northwest",
      "postal_code": "10118",
      "city": "New York",
      "phone": "555-555-0199",
      "company": "Company",
      "country_name": "United States",
      "country_code": "US",
      "state_text": "NY",
      "state_code": "NY",
      "quick_checkout": false,
      "is_default_billing": false,
      "is_default_shipping": true,
      "state_abbr": "NY",
      "country_iso": "US",
      "state_name": "New York",
      "owner": {
        "id": "cust_UkLWZg9DAJ",
        "type": "customer",
        "name": null
      }
    },
    {
      "id": "addr_gbHJdmfrXB",
      "label": null,
      "first_name": "John",
      "last_name": "Doe",
      "full_name": "John Doe",
      "address1": "363 Lovely Street",
      "address2": "Northwest",
      "postal_code": "10118",
      "city": "New York",
      "phone": "555-555-0199",
      "company": "Company",
      "country_name": "United States",
      "country_code": "US",
      "state_text": "NY",
      "state_code": "NY",
      "quick_checkout": false,
      "is_default_billing": true,
      "is_default_shipping": false,
      "state_abbr": "NY",
      "country_iso": "US",
      "state_name": "New York",
      "owner": {
        "id": "cust_UkLWZg9DAJ",
        "type": "customer",
        "name": null
      }
    },
    {
      "id": "addr_EfhxLZ9ck8",
      "label": null,
      "first_name": "John",
      "last_name": "Doe",
      "full_name": "John Doe",
      "address1": "364 Lovely Street",
      "address2": "Northwest",
      "postal_code": "10118",
      "city": "New York",
      "phone": "555-555-0199",
      "company": "Company",
      "country_name": "United States",
      "country_code": "US",
      "state_text": "NY",
      "state_code": "NY",
      "quick_checkout": false,
      "is_default_billing": false,
      "is_default_shipping": false,
      "state_abbr": "NY",
      "country_iso": "US",
      "state_name": "New York",
      "owner": {
        "id": "cust_UkLWZg9DAJ",
        "type": "customer",
        "name": null
      }
    }
  ],
  "meta": {
    "page": 1,
    "limit": 25,
    "count": 3,
    "pages": 1,
    "from": 1,
    "to": 3,
    "in": 3,
    "previous": null,
    "next": null
  }
}

{
  "error": {
    "code": "authentication_required",
    "message": "Authentication required"
  }
}

{
  "error": {
    "code": "record_not_found",
    "message": "Cart not found"
  }
}

Filters

Filter with q[<attribute>_<predicate>]=value, for example q[address1_cont]=…. Send a list as q[<attribute>_in][]=a&q[<attribute>_in][]=b. How filters work.

Attribute	Kind	Predicates
`address1`	Text	`eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank`
`address2`	Text	`eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank`
`city`	Text	`eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank`
`company`	Text	`eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank`
`country_code`	One of the `CountryCode` codes	`eq` `not_eq` `in` `not_in` `null` `not_null`
`created_at`	Date and time	`eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null`
`first_name`	Text	`eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank`
`id`	Prefixed ID	`eq` `not_eq` `in` `not_in` `null` `not_null`
`last_name`	Text	`eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank`
`phone`	Text	`eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank`
`postal_code`	Text	`eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank`
`state_code`	Text	`eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank`
`updated_at`	Date and time	`eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null`

Sort by: address1, address2, city, company, country_code, created_at, first_name, id, last_name, phone, postal_code, state_code, updated_at. Prefix a field with - to sort descending.

Authorizations

x-spree-api-key

string

header

required

Publishable API key for store access

Authorization

string

header

required

JWT token for authenticated customers

Headers

x-spree-api-key

string

required

Authorization

string

required

Path Parameters

cart_id

string

required

Cart prefixed ID

Query Parameters

page

integer

limit

integer

object

Attribute filters, as q[<attribute>_<predicate>]=value. See Filters above for the list.

Response

addresses found

data

object[]

Show child attributes

API basics

Endpoints

List addresses this cart may use

Filters

Authorizations

Headers

Path Parameters

Query Parameters

Response

​Filters

Authorizations

Headers

Path Parameters

Query Parameters

Response

Filters