Address Book API — Manage Saved Delivery Addresses

The address book API lets authenticated users save, update, and delete delivery addresses for faster checkout. All five endpoints are scoped to the current session — users can only read and modify their own addresses. Requests without a valid session cookie are rejected with 401.

Addresses are not referenced by orders. When a user completes checkout, the delivery details are copied as an immutable snapshot directly onto the order record. This means deleting or editing an address in the address book has no effect on existing orders — the original delivery information is permanently preserved on each order.

List addresses

Returns all delivery addresses saved by the authenticated user.

curl https://api.avanzarintimeshop.com/api/v1/addresses \
  -H "Cookie: better-auth.session_token=<your-session-token>"

Requires: valid session cookie (requireSession middleware).

Response

addresses

Address[]

required

All addresses belonging to the authenticated user.

Show Address object

string (UUID)

Unique address identifier.

userId

string

The owner’s user ID. Always matches the authenticated user.

recipientName

string

Full name of the delivery recipient.

phone

string

Local phone number for delivery coordination.

province

string

Cuban province (e.g., "La Habana").

municipality

string

Municipality within the province.

addressLine

string

Full street address.

reference

string | null

Optional landmark or delivery hint.

createdAt

string (ISO 8601)

Timestamp when the address was saved.

updatedAt

string (ISO 8601)

Timestamp of the last update.

Example response — 200 OK

{
  "addresses": [
    {
      "id": "addr-0001-0000-0000-0000-000000000001",
      "userId": "user-abc123",
      "recipientName": "María García",
      "phone": "+53-52345678",
      "province": "La Habana",
      "municipality": "Plaza de la Revolución",
      "addressLine": "Calle 23 #456 entre J e I, Vedado",
      "reference": "Edificio azul, apartamento 3B",
      "createdAt": "2024-10-01T09:00:00.000Z",
      "updatedAt": "2024-10-01T09:00:00.000Z"
    }
  ]
}

Get a single address

Returns one address by its UUID. Returns 404 if the address does not exist or belongs to a different user.

curl https://api.avanzarintimeshop.com/api/v1/addresses/addr-0001-0000-0000-0000-000000000001 \
  -H "Cookie: better-auth.session_token=<your-session-token>"

Requires: valid session cookie (requireSession middleware).

Path parameters

string (UUID)

required

Unique identifier of the address to retrieve. Returns 404 if not found or not owned by the authenticated user.

Example response — 200 OK

{
  "address": {
    "id": "addr-0001-0000-0000-0000-000000000001",
    "userId": "user-abc123",
    "recipientName": "María García",
    "phone": "+53-52345678",
    "province": "La Habana",
    "municipality": "Plaza de la Revolución",
    "addressLine": "Calle 23 #456 entre J e I, Vedado",
    "reference": "Edificio azul, apartamento 3B",
    "createdAt": "2024-10-01T09:00:00.000Z",
    "updatedAt": "2024-10-01T09:00:00.000Z"
  }
}

Create an address

Saves a new delivery address for the authenticated user. Returns the created address with its assigned id and timestamps.

curl -X POST https://api.avanzarintimeshop.com/api/v1/addresses \
  -H "Cookie: better-auth.session_token=<your-session-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "recipientName": "María García",
    "phone": "+53-52345678",
    "province": "La Habana",
    "municipality": "Plaza de la Revolución",
    "addressLine": "Calle 23 #456 entre J e I, Vedado",
    "reference": "Edificio azul, apartamento 3B"
  }'

Requires: valid session cookie (requireSession middleware).

Request body

recipientName

string

required

Full name of the person who will receive deliveries at this address. Minimum 1 character.

phone

string

required

Local Cuban phone number for delivery coordination. Minimum 1 character.

province

string

required

Cuban province for the delivery destination (e.g., "La Habana", "Santiago de Cuba"). Minimum 1 character.

municipality

string

required

Municipality within the selected province (e.g., "Plaza de la Revolución"). Minimum 1 character.

addressLine

string

required

Full street address including street number, street name, and neighborhood (e.g., "Calle 23 #456 entre J e I, Vedado"). Minimum 1 character.

reference

string

Optional delivery landmark or hint (e.g., "Edificio azul, apartamento 3B"). Helps delivery agents locate the exact destination.

Example response — 201 Created

{
  "address": {
    "id": "addr-0002-0000-0000-0000-000000000001",
    "userId": "user-abc123",
    "recipientName": "María García",
    "phone": "+53-52345678",
    "province": "La Habana",
    "municipality": "Plaza de la Revolución",
    "addressLine": "Calle 23 #456 entre J e I, Vedado",
    "reference": "Edificio azul, apartamento 3B",
    "createdAt": "2024-11-20T11:30:00.000Z",
    "updatedAt": "2024-11-20T11:30:00.000Z"
  }
}

Update an address

Partially updates an existing address. All fields are optional — only send the fields you want to change. Returns 404 if the address does not exist or is not owned by the authenticated user.

curl -X PATCH https://api.avanzarintimeshop.com/api/v1/addresses/addr-0002-0000-0000-0000-000000000001 \
  -H "Cookie: better-auth.session_token=<your-session-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+53-55987654",
    "reference": "Casa verde con reja negra"
  }'

Requires: valid session cookie (requireSession middleware).

Path parameters

string (UUID)

required

Unique identifier of the address to update. Returns 404 if not found or not owned by the authenticated user.

Request body

All fields are optional for PATCH. Only provided fields are updated; omitted fields retain their current values.

recipientName

string

Updated recipient name.

phone

string

Updated phone number.

province

string

Updated province.

municipality

string

Updated municipality.

addressLine

string

Updated street address.

reference

string

Updated delivery landmark or hint.

Example response — 200 OK

{
  "address": {
    "id": "addr-0002-0000-0000-0000-000000000001",
    "userId": "user-abc123",
    "recipientName": "María García",
    "phone": "+53-55987654",
    "province": "La Habana",
    "municipality": "Plaza de la Revolución",
    "addressLine": "Calle 23 #456 entre J e I, Vedado",
    "reference": "Casa verde con reja negra",
    "createdAt": "2024-11-20T11:30:00.000Z",
    "updatedAt": "2024-11-20T14:15:00.000Z"
  }
}

Delete an address

Permanently deletes an address from the user’s address book. Returns 204 No Content on success with an empty body. Returns 404 if the address does not exist or is not owned by the authenticated user.

curl -X DELETE https://api.avanzarintimeshop.com/api/v1/addresses/addr-0002-0000-0000-0000-000000000001 \
  -H "Cookie: better-auth.session_token=<your-session-token>"

Requires: valid session cookie (requireSession middleware).

Path parameters

string (UUID)

required

Unique identifier of the address to delete. Returns 404 if not found or not owned by the authenticated user.

Response — 204 No Content Empty body. The address has been permanently removed from the address book.

HTTP	Condition
`204`	Address deleted successfully.
`401`	No valid session cookie.
`404`	Address not found or not owned by the authenticated user.

Overview

Public Endpoints

Admin Endpoints

Address Book API — Manage Saved Delivery Addresses

List addresses

Response

Get a single address

Path parameters

Create an address

Request body

Update an address

Path parameters

Request body

Delete an address

Path parameters

Build docs developers (and LLMs) love

Overview

Public Endpoints

Admin Endpoints

Documentation Index

​List addresses

​Response

​Get a single address

​Path parameters

​Create an address

​Request body

​Update an address

​Path parameters

​Request body

​Delete an address

​Path parameters

Build docs developers (and LLMs) love

List addresses

Response

Get a single address

Path parameters

Create an address

Request body

Update an address

Path parameters

Request body

Delete an address

Path parameters