# Customer

The Customer API lets storefront JavaScript register a customer, sign a customer in and out, and work with the signed-in customer's profile, addresses, and newsletter subscription.

All Ajax API requests should use [locale-aware URLs](/docs/theme/references/ajax-api/#locale-aware-urls) to give visitors a consistent experience.

## Authentication

**Customer session.** Registration, sign-in, the password reset email, the password reset, the sign-in verification code, the newsletter subscription, and the login settings are open to anonymous visitors. Every other endpoint on this page needs a signed-in customer. The session is a cookie that the browser sends automatically after a successful `sign_up` or `sign_in`. Without it, the request returns `401`:

```json
{
  "errors": [
    "Sign in to continue store operations."
  ]
}
```

**CSRF token.** Every request other than `GET` must carry an `X-CSRF-Token` header whose value is the `CSRF-TOKEN` cookie. The cookie is readable from JavaScript, so the examples below take it with this helper:

```javascript
function getCsrfToken() {
  const entry = document.cookie.split('; ').find((item) => item.startsWith('CSRF-TOKEN='));
  return entry ? decodeURIComponent(entry.slice('CSRF-TOKEN='.length)) : '';
}
```

Without the header, the request returns `406` with `{"errors":["CSRF token verify fails"]}`.

**Bot protection.** Registration, sign-in, the password reset email, and the password reset are covered by the store's bot protection. When the server asks for a challenge, it returns `400` with `{"errors":["{\"errors\":[\"empty token\"]}"]}`. Submit the request again with the bot protection token in the `token` field and `version` set to `v3`. In a Shoplazza theme, the `spz-privacy-token` component fills both fields for you. In your own request, read the token from the bot protection service configured for the store (Google reCAPTCHA v3).

**Request format.** Endpoints on this page that send data take an `application/x-www-form-urlencoded` body. The examples below build it with `URLSearchParams`.

## Create a customer account

```text
POST /{locale}/api/customers/sign_up
```

Create a customer account. A successful request also starts a customer session, so the customer is signed in afterwards.

### Example request

**Example request**

```javascript
const body = new URLSearchParams({
  email: 'jane@example.com',
  password: 'your-password',
  first_name: 'Jane',
  last_name: 'Doe',
  newsletter: 'true'
});

fetch(window.SHOPLAZZA.routes.root + '/api/customers/sign_up', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'X-CSRF-Token': getCsrfToken()
  },
  body: body
})
  .then((response) => response.json())
  .then((data) => {
    // do something...
  });
```

### Request parameters

- `email` string

  The email address of the account.
- `password` string

  The password of the account.
- `first_name` string

  The first name of the customer.
- `last_name` string

  The last name of the customer.
- `newsletter` boolean

  Whether the customer subscribes to marketing emails.
- `token` string

  The bot protection token. Required when the store's bot protection asks for a challenge.
- `version` string

  The bot protection version, `v3`. Required together with `token`.

### Response

**Schema | Example**

- `customer` object

  - `id` string

    ID of the customer.
  - `email` string

    Email address of the customer.
  - `first_name` string

    First name of the customer or recipient.
  - `last_name` string

    Last name of the customer or recipient.
  - `phone` string

    Phone number of the customer.
  - `tags` undefined[]

    Tags attached to the object.
  - `name` string

    Full name of the customer.
  - `note` string

    Note attached to the object.
  - `contact` string

    Contact of the customer, either an email address or a phone number.
  - `contact_type` string

    Contact type, either email or phone.
  - `created_by` string
  - `location_id` string
  - `registered_at` string

    Time when the customer completed registration.
  - `noted_at` string
  - `created_at` string

    Creation time, in ISO-8601 format.
  - `source` string

    Where the customer record came from.
  - `free_tax` boolean

    Whether the customer is exempt from taxes.
  - `subscribed` boolean

    Whether the customer is subscribed to marketing messages.
  - `registered` boolean

    Whether the customer has registered an account.
  - `customer_extra_info` object

    Additional statistics about the customer.

    - `finished_order_count` number

      Number of completed orders placed by the customer.
    - `finished_order_total` string

      Total amount of the completed orders placed by the customer.
    - `country` string
    - `country_code` string
    - `province` string

      Province or state of the address.
    - `province_code` string

      Province or state code.
    - `currency_code` string

      Currency code of the order, for example `USD`.
    - `purchase_product_count` number

      Number of products the customer has purchased.
    - `store_customer_id` string
    - `customer_role` string
    - `ext` string
    - `first_order_at` string

      Time when the customer placed the first order.
    - `last_order_at` string

      Time when the customer placed the last order.

```json
{
  "customer": {
    "id": "04f268c8-fea5-4386-abd7-c4fade761257",
    "email": "jane@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "phone": null,
    "tags": [],
    "name": "Jane Doe",
    "note": null,
    "contact": "jane@example.com",
    "contact_type": "email",
    "created_by": "default",
    "location_id": "",
    "registered_at": "2026-09-03T02:48:07Z",
    "noted_at": null,
    "created_at": "2026-09-03T02:48:08Z",
    "source": "sign_up",
    "free_tax": false,
    "subscribed": true,
    "registered": true,
    "customer_extra_info": {
      "finished_order_count": 0,
      "finished_order_total": "0.0",
      "country": null,
      "country_code": null,
      "province": null,
      "province_code": null,
      "currency_code": "USD",
      "purchase_product_count": 0,
      "store_customer_id": "",
      "customer_role": null,
      "ext": null,
      "first_order_at": null,
      "last_order_at": null
    }
  }
}
```

## Sign a customer in

```text
POST /{locale}/api/customers/sign_in
```

Sign a customer in with an email address and a password, and start a customer session.

### Example request

**Example request**

```javascript
const body = new URLSearchParams({
  email: 'jane@example.com',
  password: 'your-password'
});

fetch(window.SHOPLAZZA.routes.root + '/api/customers/sign_in', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'X-CSRF-Token': getCsrfToken()
  },
  body: body
})
  .then((response) => response.json())
  .then((data) => {
    // do something...
  });
```

### Request parameters

- `email` string

  The email address of the account.
- `password` string

  The password of the account.
- `token` string

  The bot protection token. Required when the store's bot protection asks for a challenge.
- `version` string

  The bot protection version, `v3`. Required together with `token`.

### Response

**Schema | Example**

- `customer` object

  - `id` string

    ID of the customer.
  - `email` string

    Email address of the customer.
  - `first_name` string

    First name of the customer or recipient.
  - `last_name` string

    Last name of the customer or recipient.
  - `phone` string

    Phone number of the customer.
  - `tags` undefined[]

    Tags attached to the object.
  - `name` string

    Full name of the customer.
  - `note` string

    Note attached to the object.
  - `contact` string

    Contact of the customer, either an email address or a phone number.
  - `contact_type` string

    Contact type, either email or phone.
  - `created_by` string
  - `location_id` string
  - `registered_at` string

    Time when the customer completed registration.
  - `noted_at` string
  - `created_at` string

    Creation time, in ISO-8601 format.
  - `source` string

    Where the customer record came from.
  - `free_tax` string

    Whether the customer is exempt from taxes.
  - `subscribed` boolean

    Whether the customer is subscribed to marketing messages.
  - `registered` boolean

    Whether the customer has registered an account.
  - `customer_extra_info` object

    Additional statistics about the customer.

    - `finished_order_count` number

      Number of completed orders placed by the customer.
    - `finished_order_total` string

      Total amount of the completed orders placed by the customer.
    - `country` string
    - `country_code` string
    - `province` string

      Province or state of the address.
    - `province_code` string

      Province or state code.
    - `currency_code` string

      Currency code of the order, for example `USD`.
    - `purchase_product_count` number

      Number of products the customer has purchased.
    - `store_customer_id` string
    - `customer_role` string
    - `ext` string
    - `first_order_at` string

      Time when the customer placed the first order.
    - `last_order_at` string

      Time when the customer placed the last order.

```json
{
  "customer": {
    "id": "9fe44049-abab-4fed-ab3d-1bf4ffee8ef5",
    "email": "jane@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "phone": "+1 555-0100",
    "tags": [],
    "name": "Jane Doe",
    "note": null,
    "contact": "jane@example.com",
    "contact_type": "email",
    "created_by": "default",
    "location_id": "",
    "registered_at": "2026-09-03T01:03:32Z",
    "noted_at": null,
    "created_at": "2026-09-02T14:13:31Z",
    "source": "order_create_c",
    "free_tax": null,
    "subscribed": false,
    "registered": true,
    "customer_extra_info": {
      "finished_order_count": 2,
      "finished_order_total": "33.0",
      "country": "United States",
      "country_code": "US",
      "province": "California",
      "province_code": "US-CA",
      "currency_code": "USD",
      "purchase_product_count": 4,
      "store_customer_id": "",
      "customer_role": null,
      "ext": null,
      "first_order_at": "2026-09-03T02:19:44Z",
      "last_order_at": "2026-09-03T02:32:31Z"
    }
  }
}
```

## Sign a customer out

```text
POST /{locale}/api/customers/sign_out
```

End the current customer session. Requires a signed-in customer and takes no parameters.

### Example request

**Example request**

```javascript
fetch(window.SHOPLAZZA.routes.root + '/api/customers/sign_out', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'X-CSRF-Token': getCsrfToken()
  }
})
  .then((response) => response.json())
  .then((data) => {
    // do something...
  });
```

### Response

**Schema | Example**

- `` object

```json
{}
```

## Send a password reset email

```text
POST /{locale}/api/customers/password_reset_email
```

Send a password reset email to a customer. The email carries the verification code that `PATCH /{locale}/api/customers/password_reset` expects.

### Example request

**Example request**

```javascript
const body = new URLSearchParams({ email: 'jane@example.com' });

fetch(window.SHOPLAZZA.routes.root + '/api/customers/password_reset_email', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'X-CSRF-Token': getCsrfToken()
  },
  body: body
})
  .then((response) => response.json())
  .then((data) => {
    // do something...
  });
```

### Request parameters

- `email` string

  The email address of the account.

### Response

**Schema | Example**

- `` object

```json
{}
```

## Reset a customer's password

```text
PATCH /{locale}/api/customers/password_reset
```

Set a new password for a customer with the verification code from the password reset email.

### Example request

**Example request**

```javascript
const body = new URLSearchParams({
  email: 'jane@example.com',
  code: '123456',
  password: 'your-new-password',
  confirm_password: 'your-new-password'
});

fetch(window.SHOPLAZZA.routes.root + '/api/customers/password_reset', {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'X-CSRF-Token': getCsrfToken()
  },
  body: body
})
  .then((response) => response.json())
  .then((data) => {
    // do something...
  });
```

### Request parameters

- `email` string

  The email address of the account.
- `code` string

  The verification code from the password reset email.
- `password` string

  The new password.
- `confirm_password` string

  The new password again. Must match `password`.
- `token` string

  The bot protection token. Required when the store's bot protection asks for a challenge.
- `version` string

  The bot protection version, `v3`. Required together with `token`.

### Response

**Schema | Example**

- `` object

```json
{}
```

## Send a sign-in verification code

```text
POST /{locale}/api/customers/login_email
```

Send a sign-in verification code to a customer's email address, for flows that let a customer sign in with a code instead of a password.

### Example request

**Example request**

```javascript
const body = new URLSearchParams({ email: 'jane@example.com' });

fetch(window.SHOPLAZZA.routes.root + '/api/customers/login_email', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'X-CSRF-Token': getCsrfToken()
  },
  body: body
})
  .then((response) => response.json())
  .then((data) => {
    // do something...
  });
```

### Request parameters

- `email` string

  The email address that receives the code.

### Response

**Schema | Example**

- `` object

```json
{}
```

## Get the store's social sign-in options

```text
GET /{locale}/api/customers/login_settings
```

Get the social sign-in providers the store offers on its login page. Takes no parameters. `login_setting` is `null` when the store offers none.

### Example request

**Example request**

```javascript
fetch(window.SHOPLAZZA.routes.root + '/api/customers/login_settings')
  .then((response) => response.json())
  .then((data) => {
    // do something...
  });
```

### Response

**Schema | Example**

- `login_setting` object

  - `google` boolean

    Whether sign-in with Google is enabled.
  - `apple` boolean

    Whether sign-in with Apple is enabled.
  - `facebook` boolean

    Whether sign-in with Facebook is enabled.

```json
{
  "login_setting": {
    "google": true,
    "apple": true,
    "facebook": true
  }
}
```

## Get the signed-in customer's profile

```text
GET /{locale}/api/customers/show
```

Get the profile of the signed-in customer. Requires a signed-in customer and takes no parameters.

### Example request

**Example request**

```javascript
fetch(window.SHOPLAZZA.routes.root + '/api/customers/show')
  .then((response) => response.json())
  .then((data) => {
    // do something...
  });
```

### Response

**Schema | Example**

- `customer` object

  - `id` string

    ID of the customer.
  - `email` string

    Email address of the customer.
  - `first_name` string

    First name of the customer or recipient.
  - `last_name` string

    Last name of the customer or recipient.
  - `phone` string

    Phone number of the customer.
  - `tags` undefined[]

    Tags attached to the object.
  - `name` string

    Full name of the customer.
  - `note` string

    Note attached to the object.
  - `contact` string

    Contact of the customer, either an email address or a phone number.
  - `contact_type` string

    Contact type, either email or phone.
  - `created_by` string
  - `location_id` string
  - `registered_at` string

    Time when the customer completed registration.
  - `noted_at` string
  - `created_at` string

    Creation time, in ISO-8601 format.
  - `source` string

    Where the customer record came from.
  - `free_tax` string

    Whether the customer is exempt from taxes.
  - `subscribed` boolean

    Whether the customer is subscribed to marketing messages.
  - `registered` boolean

    Whether the customer has registered an account.
  - `customer_extra_info` object

    Additional statistics about the customer.

    - `finished_order_count` number

      Number of completed orders placed by the customer.
    - `finished_order_total` string

      Total amount of the completed orders placed by the customer.
    - `country` string
    - `country_code` string
    - `province` string

      Province or state of the address.
    - `province_code` string

      Province or state code.
    - `currency_code` string

      Currency code of the order, for example `USD`.
    - `purchase_product_count` number

      Number of products the customer has purchased.
    - `store_customer_id` string
    - `customer_role` string
    - `ext` string
    - `first_order_at` string

      Time when the customer placed the first order.
    - `last_order_at` string

      Time when the customer placed the last order.

```json
{
  "customer": {
    "id": "9fe44049-abab-4fed-ab3d-1bf4ffee8ef5",
    "email": "jane@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "phone": "+1 555-0100",
    "tags": [],
    "name": "Jane Doe",
    "note": null,
    "contact": "jane@example.com",
    "contact_type": "email",
    "created_by": "default",
    "location_id": "",
    "registered_at": "2026-09-03T01:03:32Z",
    "noted_at": null,
    "created_at": "2026-09-02T14:13:31Z",
    "source": "newsletter",
    "free_tax": null,
    "subscribed": true,
    "registered": true,
    "customer_extra_info": {
      "finished_order_count": 0,
      "finished_order_total": "0.0",
      "country": null,
      "country_code": null,
      "province": null,
      "province_code": null,
      "currency_code": "USD",
      "purchase_product_count": 0,
      "store_customer_id": "",
      "customer_role": null,
      "ext": null,
      "first_order_at": null,
      "last_order_at": null
    }
  }
}
```

## Update the signed-in customer's profile

```text
PATCH /{locale}/api/customers/update
```

Update the name and the email address of the signed-in customer. Requires a signed-in customer. Send `email` together with the name fields.

### Example request

**Example request**

```javascript
const body = new URLSearchParams({
  email: 'jane@example.com',
  first_name: 'Jane',
  last_name: 'Doe'
});

fetch(window.SHOPLAZZA.routes.root + '/api/customers/update', {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'X-CSRF-Token': getCsrfToken()
  },
  body: body
})
  .then((response) => response.json())
  .then((data) => {
    // do something...
  });
```

### Request parameters

- `email` string

  The email address of the account.
- `first_name` string

  The first name of the customer.
- `last_name` string

  The last name of the customer.

### Response

**Schema | Example**

- `customer` object

  - `email` string

    Email address of the customer.
  - `first_name` string

    First name of the customer or recipient.
  - `last_name` string

    Last name of the customer or recipient.
  - `phone` string

    Phone number of the customer.
  - `id` string

    ID of the customer.
  - `contact_type` string

    Contact type, either email or phone.
  - `contact` string

    Contact of the customer, either an email address or a phone number.
  - `name` string

    Full name of the customer.
  - `tags` undefined[]

    Tags attached to the object.
  - `note` string

    Note attached to the object.
  - `created_by` string
  - `location_id` string
  - `registered_at` string

    Time when the customer completed registration.
  - `noted_at` string
  - `created_at` string

    Creation time, in ISO-8601 format.
  - `source` string

    Where the customer record came from.
  - `free_tax` string

    Whether the customer is exempt from taxes.
  - `subscribed` boolean

    Whether the customer is subscribed to marketing messages.
  - `registered` boolean

    Whether the customer has registered an account.
  - `customer_extra_info` object

    Additional statistics about the customer.

    - `finished_order_count` number

      Number of completed orders placed by the customer.
    - `finished_order_total` string

      Total amount of the completed orders placed by the customer.
    - `country` string
    - `country_code` string
    - `province` string

      Province or state of the address.
    - `province_code` string

      Province or state code.
    - `currency_code` string

      Currency code of the order, for example `USD`.
    - `purchase_product_count` number

      Number of products the customer has purchased.
    - `store_customer_id` string
    - `customer_role` string
    - `ext` string
    - `first_order_at` string

      Time when the customer placed the first order.
    - `last_order_at` string

      Time when the customer placed the last order.

```json
{
  "customer": {
    "email": "jane@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "phone": "+1 555-0100",
    "id": "9fe44049-abab-4fed-ab3d-1bf4ffee8ef5",
    "contact_type": "email",
    "contact": "jane@example.com",
    "name": "Jane Doe",
    "tags": [],
    "note": null,
    "created_by": "default",
    "location_id": "",
    "registered_at": "2026-09-03T01:03:32Z",
    "noted_at": null,
    "created_at": "2026-09-02T14:13:31Z",
    "source": "newsletter",
    "free_tax": null,
    "subscribed": true,
    "registered": true,
    "customer_extra_info": {
      "finished_order_count": 0,
      "finished_order_total": "0.0",
      "country": null,
      "country_code": null,
      "province": null,
      "province_code": null,
      "currency_code": "USD",
      "purchase_product_count": 0,
      "store_customer_id": "",
      "customer_role": null,
      "ext": null,
      "first_order_at": null,
      "last_order_at": null
    }
  }
}
```

## Subscribe an email address to marketing emails

```text
POST /{locale}/api/customers/newsletters
```

Subscribe an email address to the store's marketing emails. Open to anonymous visitors.

### Example request

**Example request**

```javascript
const body = new URLSearchParams({ email: 'jane@example.com' });

fetch(window.SHOPLAZZA.routes.root + '/api/customers/newsletters', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'X-CSRF-Token': getCsrfToken()
  },
  body: body
})
  .then((response) => response.json())
  .then((data) => {
    // do something...
  });
```

### Request parameters

- `email` string

  The email address to subscribe.

### Response

**Schema | Example**

- `id` string

  ID of the customer that was subscribed.

```json
{
  "id": "9fe44049-abab-4fed-ab3d-1bf4ffee8ef5"
}
```

## List a customer's addresses

```text
GET /{locale}/api/customers/addresses
```

List the addresses of the signed-in customer. Requires a signed-in customer.

### Example request

**Example request**

```javascript
fetch(window.SHOPLAZZA.routes.root + '/api/customers/addresses?per_page=40')
  .then((response) => response.json())
  .then((data) => {
    // do something...
  });
```

### Request parameters

- `per_page` number

  The number of addresses to return.

### Response

**Schema | Example**

- `count` number

  Number of addresses returned.
- `addresses` object[]

  List of the customer addresses.

  *   Array \[

  - `id` string

    ID of the address.
  - `first_name` string

    First name of the customer or recipient.
  - `last_name` string

    Last name of the customer or recipient.
  - `phone` string

    Phone number associated with the address.
  - `email` string

    Email address associated with the address.
  - `country` string

    Country name of the address.
  - `country_code` string

    ISO country code of the address.
  - `province` string

    Province or state of the address.
  - `province_code` string

    Province or state code.
  - `area` string

    Area or district of the address.
  - `city` string

    City of the address.
  - `company` string

    Company name of the address.
  - `zip` string

    Postal or ZIP code.
  - `gender` string

    Gender of the recipient.
  - `phone_area_code` string

    Area code of the phone number.
  - `address` string

    Street address of the recipient.
  - `address1` string

    Primary street address.
  - `is_default` boolean

    Whether this is the customer's default address.
  - `created_at` string

    Creation time, in ISO-8601 format.
  *   \]

```json
{
  "count": 1,
  "addresses": [
    {
      "id": "f4892e84-0d09-4370-8144-37a21a01f2f6",
      "first_name": "Jane",
      "last_name": "Doe",
      "phone": null,
      "email": "jane@example.com",
      "country": "United States",
      "country_code": "US",
      "province": "California",
      "province_code": "US-CA",
      "area": null,
      "city": "Los Angeles",
      "company": null,
      "zip": "90001",
      "gender": null,
      "phone_area_code": null,
      "address": "123 Main St",
      "address1": "123 Main St",
      "is_default": true,
      "created_at": "2026-09-03T01:07:23Z"
    }
  ]
}
```

## Create an address

```text
POST /{locale}/api/customers/addresses
```

Add an address to the signed-in customer's address book. Requires a signed-in customer. Send `country` and `country_code` together.

### Example request

**Example request**

```javascript
const body = new URLSearchParams({
  first_name: 'Jane',
  last_name: 'Doe',
  address: '123 Main St',
  address1: 'Apt 4',
  city: 'Los Angeles',
  province: 'California',
  province_code: 'CA',
  country: 'United States',
  country_code: 'US',
  zip: '90001',
  email: 'jane@example.com',
  is_default: '1'
});

fetch(window.SHOPLAZZA.routes.root + '/api/customers/addresses', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'X-CSRF-Token': getCsrfToken()
  },
  body: body
})
  .then((response) => response.json())
  .then((data) => {
    // do something...
  });
```

### Request parameters

- `first_name` string

  The first name of the recipient.
- `last_name` string

  The last name of the recipient.
- `address` string

  The first line of the street address.
- `address1` string

  The second line of the street address, such as an apartment number.
- `city` string

  The city.
- `province` string

  The name of the province or state.
- `province_code` string

  The code of the province or state, such as `CA`.
- `country` string

  The name of the country, such as `United States`.
- `country_code` string

  The two-letter code of the country, such as `US`.
- `zip` string

  The postal code.
- `email` string

  The email address of the recipient.
- `is_default` number

  Whether this becomes the default address, `1` or `0`.

### Response

**Schema | Example**

- `address` object

  - `id` string

    ID of the address.
  - `first_name` string

    First name of the customer or recipient.
  - `last_name` string

    Last name of the customer or recipient.
  - `phone` string

    Phone number associated with the address.
  - `email` string

    Email address associated with the address.
  - `country` string

    Country name of the address.
  - `country_code` string

    ISO country code of the address.
  - `province` string

    Province or state of the address.
  - `province_code` string

    Province or state code.
  - `area` string

    Area or district of the address.
  - `city` string

    City of the address.
  - `company` string

    Company name of the address.
  - `zip` string

    Postal or ZIP code.
  - `gender` string

    Gender of the recipient.
  - `phone_area_code` string

    Area code of the phone number.
  - `address` string

    Street address of the recipient.
  - `address1` string

    Primary street address.
  - `is_default` boolean

    Whether this is the customer's default address.
  - `created_at` string

    Creation time, in ISO-8601 format.

```json
{
  "address": {
    "id": "f4892e84-0d09-4370-8144-37a21a01f2f6",
    "first_name": "Jane",
    "last_name": "Doe",
    "phone": null,
    "email": "jane@example.com",
    "country": "United States",
    "country_code": "US",
    "province": "California",
    "province_code": "US-CA",
    "area": null,
    "city": "Los Angeles",
    "company": null,
    "zip": "90001",
    "gender": null,
    "phone_area_code": null,
    "address": "123 Main St",
    "address1": "123 Main St",
    "is_default": true,
    "created_at": "2026-09-03T01:07:23Z"
  }
}
```

## Get an address

```text
GET /{locale}/api/customers/addresses/{address_id}
```

Get one address of the signed-in customer. Requires a signed-in customer.

### Example request

**Example request**

```javascript
fetch(window.SHOPLAZZA.routes.root + '/api/customers/addresses/f4892e84-0d09-4370-8144-37a21a01f2f6')
  .then((response) => response.json())
  .then((data) => {
    // do something...
  });
```

### Request parameters

- `address_id` string

  The id of the address.

### Response

**Schema | Example**

- `address` object

  - `id` string

    ID of the address.
  - `first_name` string

    First name of the customer or recipient.
  - `last_name` string

    Last name of the customer or recipient.
  - `phone` string

    Phone number associated with the address.
  - `email` string

    Email address associated with the address.
  - `country` string

    Country name of the address.
  - `country_code` string

    ISO country code of the address.
  - `province` string

    Province or state of the address.
  - `province_code` string

    Province or state code.
  - `area` string

    Area or district of the address.
  - `city` string

    City of the address.
  - `company` string

    Company name of the address.
  - `zip` string

    Postal or ZIP code.
  - `gender` string

    Gender of the recipient.
  - `phone_area_code` string

    Area code of the phone number.
  - `address` string

    Street address of the recipient.
  - `address1` string

    Primary street address.
  - `is_default` boolean

    Whether this is the customer's default address.
  - `created_at` string

    Creation time, in ISO-8601 format.

```json
{
  "address": {
    "id": "f4892e84-0d09-4370-8144-37a21a01f2f6",
    "first_name": "Jane",
    "last_name": "Doe",
    "phone": null,
    "email": "jane@example.com",
    "country": "United States",
    "country_code": "US",
    "province": "California",
    "province_code": "US-CA",
    "area": null,
    "city": "Los Angeles",
    "company": null,
    "zip": "90001",
    "gender": null,
    "phone_area_code": null,
    "address": "123 Main St",
    "address1": "123 Main St",
    "is_default": true,
    "created_at": "2026-09-03T01:07:23Z"
  }
}
```

## Update an address

```text
PATCH /{locale}/api/customers/addresses/{address_id}
```

Update one address of the signed-in customer. Requires a signed-in customer. Send `country` and `country_code` together.

### Example request

**Example request**

```javascript
const body = new URLSearchParams({
  first_name: 'Jane',
  last_name: 'Doe',
  address: '456 Oak Ave',
  city: 'Los Angeles',
  province: 'California',
  province_code: 'CA',
  country: 'United States',
  country_code: 'US',
  zip: '90002'
});

fetch(window.SHOPLAZZA.routes.root + '/api/customers/addresses/f4892e84-0d09-4370-8144-37a21a01f2f6', {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'X-CSRF-Token': getCsrfToken()
  },
  body: body
})
  .then((response) => response.json())
  .then((data) => {
    // do something...
  });
```

### Request parameters

- `address_id` string

  The id of the address.
- `first_name` string

  The first name of the recipient.
- `last_name` string

  The last name of the recipient.
- `address` string

  The first line of the street address.
- `city` string

  The city.
- `province` string

  The name of the province or state.
- `province_code` string

  The code of the province or state, such as `CA`.
- `country` string

  The name of the country, such as `United States`.
- `country_code` string

  The two-letter code of the country, such as `US`.
- `zip` string

  The postal code.

### Response

**Schema | Example**

- `address` object

  - `id` string

    ID of the address.
  - `first_name` string

    First name of the customer or recipient.
  - `last_name` string

    Last name of the customer or recipient.
  - `country` string

    Country name of the address.
  - `country_code` string

    ISO country code of the address.
  - `province` string

    Province or state of the address.
  - `province_code` string

    Province or state code.
  - `city` string

    City of the address.
  - `zip` string

    Postal or ZIP code.
  - `email` string

    Email address associated with the address.
  - `gender` string

    Gender of the recipient.
  - `phone` string

    Phone number associated with the address.
  - `area` string

    Area or district of the address.
  - `company` string

    Company name of the address.
  - `phone_area_code` string

    Area code of the phone number.
  - `address` string

    Street address of the recipient.
  - `address1` string

    Primary street address.
  - `is_default` boolean

    Whether this is the customer's default address.
  - `created_at` string

    Creation time, in ISO-8601 format.

```json
{
  "address": {
    "id": "f4892e84-0d09-4370-8144-37a21a01f2f6",
    "first_name": "Jane",
    "last_name": "Doe",
    "country": "United States",
    "country_code": "US",
    "province": "California",
    "province_code": "US-CA",
    "city": "Los Angeles",
    "zip": "90001",
    "email": "jane@example.com",
    "gender": null,
    "phone": null,
    "area": null,
    "company": null,
    "phone_area_code": null,
    "address": "123 Main St",
    "address1": "123 Main St",
    "is_default": true,
    "created_at": "2026-09-03T01:07:23Z"
  }
}
```

## Delete an address

```text
DELETE /{locale}/api/customers/addresses/{address_id}
```

Delete one address of the signed-in customer. Requires a signed-in customer.

### Example request

**Example request**

```javascript
fetch(window.SHOPLAZZA.routes.root + '/api/customers/addresses/f4892e84-0d09-4370-8144-37a21a01f2f6', {
  method: 'DELETE',
  headers: {
    'X-CSRF-Token': getCsrfToken()
  }
})
  .then((response) => response.json())
  .then((data) => {
    // do something...
  });
```

### Request parameters

- `address_id` string

  The id of the address.

### Response

**Schema | Example**

- `` object

```json
{}
```

## Set the default address

```text
POST /{locale}/api/customers/addresses/{address_id}/default
```

Make one address the default address of the signed-in customer. Requires a signed-in customer.

### Example request

**Example request**

```javascript
fetch(window.SHOPLAZZA.routes.root + '/api/customers/addresses/f4892e84-0d09-4370-8144-37a21a01f2f6/default', {
  method: 'POST',
  headers: {
    'X-CSRF-Token': getCsrfToken()
  }
})
  .then((response) => response.json())
  .then((data) => {
    // do something...
  });
```

### Request parameters

- `address_id` string

  The id of the address.

### Response

**Schema | Example**

- `` object

```json
{}
```

## Get the store's address form settings

```text
GET /{locale}/api/customers/address_settings
```

Get how the store's address form is configured: how the name fields are laid out, which optional fields are shown or hidden, and which contact fields are required. Requires a signed-in customer and takes no parameters.

### Example request

**Example request**

```javascript
fetch(window.SHOPLAZZA.routes.root + '/api/customers/address_settings')
  .then((response) => response.json())
  .then((data) => {
    // do something...
  });
```

### Response

**Schema | Example**

- `email` string

  Display setting of the email field in the address form.
- `name` string

  How the name fields are laid out in the address form.
- `phone` string

  Display setting of the phone field in the address form.
- `company` string

  Display setting of the company field in the address form, for example `hidden`.
- `address1` string

  Display setting of the street address field in the address form.
- `name_requirement` string

  Which name field is required, for example `last_name`.
- `contact_details` string

  How contact fields are collected in the address form.

```json
{
  "email": "jane@example.com",
  "name": "separate",
  "phone": "+1 555-0100",
  "company": "hidden",
  "address1": "123 Main St",
  "name_requirement": "last_name",
  "contact_details": "multiple"
}
```