Customers

Addresses

List, create, update, and delete the authenticated customer's shipping and billing 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.

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.

Status: 200 OK.

Errors

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

Request

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

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"
    }
  ]
}

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.

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.

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.

Status: 201 Created.

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.

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"}'

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"
  }
}

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.

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.

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.

Status: 200 OK. Returns the updated address.

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.

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}'

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"
  }
}

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

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.

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.

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.

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.

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"

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.

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.

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

Headers#

Errors#

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

Headers#

Errors#

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

Headers#

Body parameters#

Errors#

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

Headers#

Body parameters#

Errors#

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

Path parameters#

Headers#

Body parameters#

Errors#

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

Path parameters#

Headers#

Body parameters#

Errors#

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

Path parameters#

Headers#

Errors#

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

Path parameters#

Headers#

Errors#

GET /v1/api/customers/me/addresses

Headers

Errors

GET /v1/api/customers/me/addresses

Headers

Errors

POST /v1/api/customers/me/addresses

Headers

Body parameters

Errors

POST /v1/api/customers/me/addresses

Headers

Body parameters

Errors

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

Path parameters

Headers

Body parameters

Errors

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

Path parameters

Headers

Body parameters

Errors

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

Path parameters

Headers

Errors

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

Path parameters

Headers

Errors