# Addresses

Every customer has a list of addresses, each typed `shipping` or `billing`. At most one address per type is the default, and the API enforces this transactionally: setting `is_default: true` on an address clears the previous default of the same type in the same operation. All four endpoints are customer-authenticated (tenant API key plus `X-Customer-Token`); listing needs the `customers:read` scope, writes need `customers:write`.

The address object:

| Field | Type | Description |
| --- | --- | --- |
| `id` | string (uuid) | Address id. |
| `type` | string | `shipping` or `billing`. |
| `label` | string or null | Customer-facing label, for example `Home`. |
| `is_default` | boolean | Whether this is the default address of its type. |
| `name` | string | Recipient name. |
| `street` | string | Street and house number. |
| `postal_code` | string | Postal code. |
| `city` | string | City. |
| `country` | string | ISO 3166-1 alpha-2 country code, exactly 2 characters (for example `NL`). |
| `phone` | string or null | Phone number. |

## GET /v1/api/customers/me/addresses

List the authenticated customer's addresses. Default addresses are ordered first. The list is not paginated; the response is a plain `data` array.

### Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `X-Customer-Token` | string | Yes | Customer session token. |

No query parameters.

```bash title="Request"
curl https://api.borkol.com/v1/api/customers/me/addresses \
  -H "Authorization: Bearer {api_key}" \
  -H "X-Customer-Token: 13|Gh7rS2uX5vWy8zAbCdEfGhIjKlMnOpQrStUvWxYz"
```

Status: `200 OK`.

```json title="Response"
{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "type": "shipping",
      "label": "Home",
      "is_default": true,
      "name": "Jane Doe",
      "street": "Keizersgracht 123",
      "postal_code": "1015 CJ",
      "city": "Amsterdam",
      "country": "NL",
      "phone": "+31612345678"
    }
  ]
}
```

### Errors

- `401` `{"message":"Invalid customer token."}` when `X-Customer-Token` is missing or invalid.

## POST /v1/api/customers/me/addresses

Create an address for the authenticated customer. If `is_default` is `true`, the previous default of the same type is cleared atomically in the same transaction.

### Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `X-Customer-Token` | string | Yes | Customer session token. |

### Body parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | string | No | `shipping` or `billing`. Default `shipping`. |
| `label` | string or null | No | Label, maximum 50 characters. |
| `is_default` | boolean | No | Make this the default address of its type. |
| `name` | string | Yes | Recipient name, maximum 150 characters. |
| `street` | string | Yes | Street and house number, maximum 255 characters. |
| `postal_code` | string | Yes | Postal code, maximum 20 characters. |
| `city` | string | Yes | City, maximum 100 characters. |
| `country` | string | Yes | ISO 3166-1 alpha-2 code, exactly 2 characters. |
| `phone` | string or null | No | Phone number, maximum 50 characters. |

```bash title="Request"
curl -X POST https://api.borkol.com/v1/api/customers/me/addresses \
  -H "Authorization: Bearer {api_key}" \
  -H "X-Customer-Token: 13|Gh7rS2uX5vWy8zAbCdEfGhIjKlMnOpQrStUvWxYz" \
  -H "Content-Type: application/json" \
  -d '{"type":"shipping","label":"Home","is_default":true,"name":"Jane Doe","street":"Keizersgracht 123","postal_code":"1015 CJ","city":"Amsterdam","country":"NL","phone":"+31612345678"}'
```

Status: `201 Created`.

```json title="Response"
{
  "data": {
    "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "type": "shipping",
    "label": "Home",
    "is_default": true,
    "name": "Jane Doe",
    "street": "Keizersgracht 123",
    "postal_code": "1015 CJ",
    "city": "Amsterdam",
    "country": "NL",
    "phone": "+31612345678"
  }
}
```

### Errors

- `422` for field validation failures, for example `errors.country` `["The country field must be 2 characters."]`.
- `401` `{"message":"Invalid customer token."}` when `X-Customer-Token` is missing or invalid.

## PATCH /v1/api/customers/me/addresses/{id}

Partially update one of the authenticated customer's addresses. Same fields as create, all optional; only the fields you send are changed. If the resulting address is default (either because you set `is_default: true` or the address already was default and you changed its `type`), the previous default of the resulting type is cleared in the same transaction.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | Yes | Address id. Must belong to the authenticated customer. |

### Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `X-Customer-Token` | string | Yes | Customer session token. |

### Body parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | string | No | `shipping` or `billing`. |
| `label` | string or null | No | Label, maximum 50 characters. |
| `is_default` | boolean | No | Make this the default address of its type. |
| `name` | string | No | Recipient name, maximum 150 characters. |
| `street` | string | No | Street, maximum 255 characters. |
| `postal_code` | string | No | Postal code, maximum 20 characters. |
| `city` | string | No | City, maximum 100 characters. |
| `country` | string | No | ISO 3166-1 alpha-2 code, exactly 2 characters. |
| `phone` | string or null | No | Phone number, maximum 50 characters. |

```bash title="Request"
curl -X PATCH https://api.borkol.com/v1/api/customers/me/addresses/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d \
  -H "Authorization: Bearer {api_key}" \
  -H "X-Customer-Token: 13|Gh7rS2uX5vWy8zAbCdEfGhIjKlMnOpQrStUvWxYz" \
  -H "Content-Type: application/json" \
  -d '{"label":"Office","is_default":false}'
```

Status: `200 OK`. Returns the updated address.

```json title="Response"
{
  "data": {
    "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "type": "shipping",
    "label": "Office",
    "is_default": false,
    "name": "Jane Doe",
    "street": "Keizersgracht 123",
    "postal_code": "1015 CJ",
    "city": "Amsterdam",
    "country": "NL",
    "phone": "+31612345678"
  }
}
```

### Errors

- `404` when the address does not exist or belongs to another customer.
- `422` for field validation failures.
- `401` `{"message":"Invalid customer token."}` when `X-Customer-Token` is missing or invalid.

## DELETE /v1/api/customers/me/addresses/{id}

Delete one of the authenticated customer's addresses (soft delete: it disappears from the API but is retained internally).

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | Yes | Address id. Must belong to the authenticated customer. |

### Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `X-Customer-Token` | string | Yes | Customer session token. |

```bash title="Request"
curl -X DELETE https://api.borkol.com/v1/api/customers/me/addresses/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d \
  -H "Authorization: Bearer {api_key}" \
  -H "X-Customer-Token: 13|Gh7rS2uX5vWy8zAbCdEfGhIjKlMnOpQrStUvWxYz"
```

Status: `204 No Content`. The response has no body.

### Errors

- `404` when the address does not exist or belongs to another customer.
- `401` `{"message":"Invalid customer token."}` when `X-Customer-Token` is missing or invalid.