Address Book — Manage Shipping and Billing Addresses

Your address book stores shipping and billing addresses that you can attach to orders at checkout. Each address can be independently flagged as the default for shipping, for billing, or for both. The API returns addresses in reverse chronological order (newest first) and automatically manages default promotion when an address is deleted.

Address public IDs (prefixed with adr_) are what you pass when placing an order. Save them in your frontend after creation to reference them during checkout without fetching the full list.

The first address you create is automatically set as both the default shipping and the default billing address, regardless of the is_default_shipping and is_default_billing values in the request body.

List Addresses

Retrieve a paginated list of your saved addresses, ordered newest first. GET /users/me/addresses

Query Parameters

integer

default:"1"

Page number (1-based).

integer

default:"20"

Number of addresses to return per page. Minimum 1, maximum 100.

curl -X GET "https://api.example.com/api/v1/users/me/addresses?page=1&limit=20" \
  --cookie "session=<your-session-cookie>"

const response = await fetch(
  "https://api.example.com/api/v1/users/me/addresses?page=1&limit=20",
  { credentials: "include" }
);
const { data, meta } = await response.json();

import requests

resp = requests.get(
    "https://api.example.com/api/v1/users/me/addresses",
    params={"page": 1, "limit": 20},
    cookies={"session": "<your-session-cookie>"},
)
result = resp.json()

Response — 200 OK

{
  "success": true,
  "data": [
    {
      "public_id": "adr_01H",
      "recipient_name": "Jane Doe",
      "phone_number": "+14155552671",
      "label": "Home",
      "country": "USA",
      "state": "CA",
      "city": "San Francisco",
      "address_1": "123 Market St",
      "address_2": "Apt 4B",
      "zip_code": "94105",
      "is_default_shipping": true,
      "is_default_billing": true,
      "created_at": "2024-01-15T10:30:00.000Z",
      "updated_at": "2024-01-15T10:30:00.000Z"
    }
  ],
  "meta": {
    "total": 1,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  }
}

Create an Address

Add a new address to your address book. The required fields are recipient_name, phone_number, country, state, city, and address_1. All other fields are optional. POST /users/me/addresses

Obtain a CSRF token from GET /auth/csrf-token and pass it in the x-csrf-token header before this and all other write requests.

Request Body

string

required

Full name of the person receiving the delivery. 1–100 characters.

string

required

Contact phone number for the recipient. Up to 20 characters (e.g. +14155552671).

string

required

Country name or code (e.g. USA, GB). 1–100 characters.

string

required

State, province, or region. 1–100 characters.

string

required

City or locality. 1–100 characters.

string

required

Primary street address line. Minimum 1 character.

string

Friendly label for this address, e.g. Home or Office. Up to 50 characters.

string

Secondary address line for apartment, suite, unit, etc. (e.g. Apt 4B).

string

Postal or ZIP code. Up to 20 characters.

boolean

default:"false"

Set this address as your default shipping address. Setting this to true clears the flag from whichever address currently holds it.

boolean

default:"false"

Set this address as your default billing address. Setting this to true clears the flag from whichever address currently holds it.

# Step 1 — get CSRF token
CSRF=$(curl -s -X GET https://api.example.com/api/v1/auth/csrf-token \
  --cookie "session=<your-session-cookie>" | jq -r '.data.csrf_token')

# Step 2 — create address
curl -X POST https://api.example.com/api/v1/users/me/addresses \
  --cookie "session=<your-session-cookie>" \
  -H "x-csrf-token: $CSRF" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_name": "Jane Doe",
    "phone_number": "+14155552671",
    "label": "Home",
    "country": "USA",
    "state": "CA",
    "city": "San Francisco",
    "address_1": "123 Market St",
    "address_2": "Apt 4B",
    "zip_code": "94105",
    "is_default_shipping": true,
    "is_default_billing": true
  }'

const { data: csrfData } = await fetch(
  "https://api.example.com/api/v1/auth/csrf-token",
  { credentials: "include" }
).then((r) => r.json());

const response = await fetch(
  "https://api.example.com/api/v1/users/me/addresses",
  {
    method: "POST",
    credentials: "include",
    headers: {
      "Content-Type": "application/json",
      "x-csrf-token": csrfData.csrf_token,
    },
    body: JSON.stringify({
      recipient_name: "Jane Doe",
      phone_number: "+14155552671",
      label: "Home",
      country: "USA",
      state: "CA",
      city: "San Francisco",
      address_1: "123 Market St",
      address_2: "Apt 4B",
      zip_code: "94105",
      is_default_shipping: true,
      is_default_billing: true,
    }),
  }
);
const { data } = await response.json();
console.log(data.public_id); // "adr_01H"

import requests

s = requests.Session()
s.cookies.set("session", "<your-session-cookie>")

csrf = s.get(
    "https://api.example.com/api/v1/auth/csrf-token"
).json()["data"]["csrf_token"]

resp = s.post(
    "https://api.example.com/api/v1/users/me/addresses",
    headers={"x-csrf-token": csrf},
    json={
        "recipient_name": "Jane Doe",
        "phone_number": "+14155552671",
        "label": "Home",
        "country": "USA",
        "state": "CA",
        "city": "San Francisco",
        "address_1": "123 Market St",
        "address_2": "Apt 4B",
        "zip_code": "94105",
        "is_default_shipping": True,
        "is_default_billing": True,
    },
)
print(resp.json()["data"]["public_id"])  # "adr_01H"

Response — 201 Created

{
  "success": true,
  "data": {
    "public_id": "adr_01H",
    "recipient_name": "Jane Doe",
    "phone_number": "+14155552671",
    "label": "Home",
    "country": "USA",
    "state": "CA",
    "city": "San Francisco",
    "address_1": "123 Market St",
    "address_2": "Apt 4B",
    "zip_code": "94105",
    "is_default_shipping": true,
    "is_default_billing": true,
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-15T10:30:00.000Z"
  }
}

Show Response fields

string

required

Unique address identifier prefixed with adr_. Use this when placing orders.

string

required

Full name of the delivery recipient.

string

required

Contact number for the recipient at this address.

string

Optional friendly label, e.g. Home or Work.

string

required

Country for this address.

string

required

State, province, or region.

string

required

City or locality.

string

required

Primary street address line.

string

Secondary address line (apartment, suite, etc.). May be null.

string

Postal or ZIP code.

boolean

required

Whether this address is used by default for shipping at checkout.

boolean

required

Whether this address is used by default for billing at checkout.

string

required

ISO 8601 UTC timestamp of when the address was created.

string

required

ISO 8601 UTC timestamp of the last update.

Error Responses

Status	Meaning
`400`	A required field is missing or fails validation.
`401`	Missing or expired session cookie.
`409`	A default flag conflict that could not be resolved automatically.

Get a Single Address

Retrieve one address from your address book by its public ID. GET /users/me/addresses/{address_public_id}

curl -X GET https://api.example.com/api/v1/users/me/addresses/adr_01H \
  --cookie "session=<your-session-cookie>"

const response = await fetch(
  "https://api.example.com/api/v1/users/me/addresses/adr_01H",
  { credentials: "include" }
);
const { data } = await response.json();

Response — 200 OK

Returns a single Address object identical in shape to the creation response.

Status	Meaning
`401`	Missing or expired session cookie.
`404`	Address not found or does not belong to your account.

Update an Address

Partially update an existing address. Supply only the fields you want to change — all others remain unchanged. Default flag changes trigger automatic promotion or clearing of the existing defaults. PATCH /users/me/addresses/{address_public_id} The request body accepts the same fields as Create an Address, all optional. At minimum, send one field to change.

CSRF=$(curl -s -X GET https://api.example.com/api/v1/auth/csrf-token \
  --cookie "session=<your-session-cookie>" | jq -r '.data.csrf_token')

curl -X PATCH https://api.example.com/api/v1/users/me/addresses/adr_01H \
  --cookie "session=<your-session-cookie>" \
  -H "x-csrf-token: $CSRF" \
  -H "Content-Type: application/json" \
  -d '{"label": "Office", "address_1": "456 Mission St"}'

const { data: csrfData } = await fetch(
  "https://api.example.com/api/v1/auth/csrf-token",
  { credentials: "include" }
).then((r) => r.json());

const response = await fetch(
  "https://api.example.com/api/v1/users/me/addresses/adr_01H",
  {
    method: "PATCH",
    credentials: "include",
    headers: {
      "Content-Type": "application/json",
      "x-csrf-token": csrfData.csrf_token,
    },
    body: JSON.stringify({ label: "Office", address_1: "456 Mission St" }),
  }
);

Response — 200 OK

Returns the full updated address object.

Status	Meaning
`400`	Validation error on one of the supplied fields.
`401`	Missing or expired session cookie.
`404`	Address not found or does not belong to your account.
`409`	Default flag conflict.

Delete an Address

Soft-delete an address from your address book. The address is removed from your active list and can no longer be used for new orders. DELETE /users/me/addresses/{address_public_id}

When you delete an address that is currently set as a default (shipping or billing), the next oldest address in your book is automatically promoted to hold that default flag — so your checkout flow is never left without a default.

CSRF=$(curl -s -X GET https://api.example.com/api/v1/auth/csrf-token \
  --cookie "session=<your-session-cookie>" | jq -r '.data.csrf_token')

curl -X DELETE https://api.example.com/api/v1/users/me/addresses/adr_01H \
  --cookie "session=<your-session-cookie>" \
  -H "x-csrf-token: $CSRF"

const { data: csrfData } = await fetch(
  "https://api.example.com/api/v1/auth/csrf-token",
  { credentials: "include" }
).then((r) => r.json());

await fetch(
  "https://api.example.com/api/v1/users/me/addresses/adr_01H",
  {
    method: "DELETE",
    credentials: "include",
    headers: { "x-csrf-token": csrfData.csrf_token },
  }
);
// 204 No Content on success

Response — 204 No Content

No response body is returned.

Status	Meaning
`401`	Missing or expired session cookie.
`404`	Address not found or does not belong to your account.

Auth & Sessions

Account

Catalog

Cart & Checkout

Reviews

Address Book — Manage Shipping and Billing Addresses

List Addresses

Query Parameters

Response — 200 OK

Create an Address

Request Body

Response — 201 Created

Error Responses

Get a Single Address

Response — 200 OK

Update an Address

Response — 200 OK

Delete an Address

Response — 204 No Content

​List Addresses

​Query Parameters

​Response — 200 OK

​Create an Address

​Request Body

​Response — 201 Created

​Error Responses

​Get a Single Address

​Response — 200 OK

​Update an Address

​Response — 200 OK

​Delete an Address

​Response — 204 No Content

List Addresses

Query Parameters

Response — 200 OK

Create an Address

Request Body

Response — 201 Created

Error Responses

Get a Single Address

Response — 200 OK

Update an Address

Response — 200 OK

Delete an Address

Response — 204 No Content