# Addresses · Customer API

> Customer API reference for addresses: GET /addresses, POST /addresses, PATCH /addresses/{id}, DELETE /addresses/{id}, ….

> Markdown version of https://kanorio.com/en/developers/customer-api/addresses. Append `.md` to any developer docs URL for this format. Index: https://kanorio.com/llms.txt · MCP: https://app.kanorio.com/api/mcp

Base URL: `https://{site}/api/v1/customer` · [Errors](https://kanorio.com/en/developers/basics/errors) · [Pagination](https://kanorio.com/en/developers/basics/pagination)

### List saved addresses

`GET /addresses`

- Stability: beta

Shipping and billing addresses in the customer's address book. Each kind has one default.

**Response** (200)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `addresses` | object[] | yes | — |
| `addresses[].id` | string | yes | — |
| `addresses[].kind` | "SHIPPING" \| "BILLING" | yes | — |
| `addresses[].countryCode` | string | yes | — |
| `addresses[].recipientName` | string | yes | — |
| `addresses[].phone` | string \| null | yes | — |
| `addresses[].addressLine1` | string | yes | — |
| `addresses[].addressLine2` | string \| null | yes | — |
| `addresses[].locality` | string \| null | yes | — |
| `addresses[].region` | string \| null | yes | — |
| `addresses[].postalCode` | string \| null | yes | — |
| `addresses[].isDefault` | boolean | yes | The default address of its kind. |
| `addresses[].createdAt` | string | yes | — |

```bash
curl -X GET "https://{site}/api/v1/customer/addresses" \
  -H "Authorization: Bearer $KANORIO_CUSTOMER_TOKEN"
```

### Add an address

`POST /addresses`

- Stability: beta

Fields and required parts follow the country's postal format (the same registry the checkout and form address fields use). An address identical to an existing one of the same kind returns that one instead of creating a duplicate. The first address of a kind becomes the default.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | "SHIPPING" \| "BILLING" | no | — |
| `address` | object | yes | — |
| `address.countryCode` | string | yes | ISO 3166-1 alpha-2; decides which parts are required. |
| `address.recipientName` | string | yes | — |
| `address.phone` | string \| null | no | E.164, or a national number of the address country. |
| `address.addressLine1` | string | yes | — |
| `address.addressLine2` | string \| null | no | — |
| `address.locality` | string \| null | no | City / district. |
| `address.region` | string \| null | no | State / province / prefecture. |
| `address.postalCode` | string \| null | no | — |
| `setDefault` | boolean | no | — |

**Response** (200)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `address` | object | yes | — |
| `address.id` | string | yes | — |
| `address.kind` | "SHIPPING" \| "BILLING" | yes | — |
| `address.countryCode` | string | yes | — |
| `address.recipientName` | string | yes | — |
| `address.phone` | string \| null | yes | — |
| `address.addressLine1` | string | yes | — |
| `address.addressLine2` | string \| null | yes | — |
| `address.locality` | string \| null | yes | — |
| `address.region` | string \| null | yes | — |
| `address.postalCode` | string \| null | yes | — |
| `address.isDefault` | boolean | yes | The default address of its kind. |
| `address.createdAt` | string | yes | — |
| `created` | boolean | no | — |

**Errors**

| Code | Status | When |
| --- | --- | --- |
| `ADDRESS_INVALID` | 400 | — |
| `ADDRESS_LIMIT_REACHED` | 403 | — |

```bash
curl -X POST "https://{site}/api/v1/customer/addresses" \
  -H "Authorization: Bearer $KANORIO_CUSTOMER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Replace an address

`PATCH /addresses/{id}`

- Stability: beta

The whole address is replaced. When the result equals another saved address of the same kind, the two are merged into that one.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | — |

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `address` | object | yes | — |
| `address.countryCode` | string | yes | ISO 3166-1 alpha-2; decides which parts are required. |
| `address.recipientName` | string | yes | — |
| `address.phone` | string \| null | no | E.164, or a national number of the address country. |
| `address.addressLine1` | string | yes | — |
| `address.addressLine2` | string \| null | no | — |
| `address.locality` | string \| null | no | City / district. |
| `address.region` | string \| null | no | State / province / prefecture. |
| `address.postalCode` | string \| null | no | — |

**Response** (200)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `address` | object | yes | — |
| `address.id` | string | yes | — |
| `address.kind` | "SHIPPING" \| "BILLING" | yes | — |
| `address.countryCode` | string | yes | — |
| `address.recipientName` | string | yes | — |
| `address.phone` | string \| null | yes | — |
| `address.addressLine1` | string | yes | — |
| `address.addressLine2` | string \| null | yes | — |
| `address.locality` | string \| null | yes | — |
| `address.region` | string \| null | yes | — |
| `address.postalCode` | string \| null | yes | — |
| `address.isDefault` | boolean | yes | The default address of its kind. |
| `address.createdAt` | string | yes | — |
| `created` | boolean | no | — |

**Errors**

| Code | Status | When |
| --- | --- | --- |
| `NOT_FOUND` | 404 | — |
| `ADDRESS_INVALID` | 400 | — |

```bash
curl -X PATCH "https://{site}/api/v1/customer/addresses/{id}" \
  -H "Authorization: Bearer $KANORIO_CUSTOMER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Remove an address

`DELETE /addresses/{id}`

- Stability: beta

When the default of a kind is removed, the most recently added address of that kind becomes the default.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | — |

**Errors**

| Code | Status | When |
| --- | --- | --- |
| `NOT_FOUND` | 404 | — |

```bash
curl -X DELETE "https://{site}/api/v1/customer/addresses/{id}" \
  -H "Authorization: Bearer $KANORIO_CUSTOMER_TOKEN"
```

### Make an address the default of its kind

`POST /addresses/{id}/default`

- Stability: beta

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | — |

**Response** (200)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `address` | object | yes | — |
| `address.id` | string | yes | — |
| `address.kind` | "SHIPPING" \| "BILLING" | yes | — |
| `address.countryCode` | string | yes | — |
| `address.recipientName` | string | yes | — |
| `address.phone` | string \| null | yes | — |
| `address.addressLine1` | string | yes | — |
| `address.addressLine2` | string \| null | yes | — |
| `address.locality` | string \| null | yes | — |
| `address.region` | string \| null | yes | — |
| `address.postalCode` | string \| null | yes | — |
| `address.isDefault` | boolean | yes | The default address of its kind. |
| `address.createdAt` | string | yes | — |
| `created` | boolean | no | — |

**Errors**

| Code | Status | When |
| --- | --- | --- |
| `NOT_FOUND` | 404 | — |

```bash
curl -X POST "https://{site}/api/v1/customer/addresses/{id}/default" \
  -H "Authorization: Bearer $KANORIO_CUSTOMER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```
