Addresses

Customer saved delivery addresses: list them, create new ones, pick a default, and delete. Paths are relative to the /api/v1 prefix; all routes require Authorization: Bearer {token}.

See Common errors.

Endpoints

Method	URI	Role	Description
`GET`	`/addresses`	any	List the caller's saved addresses
`POST`	`/addresses`	any	Create a saved address (max 10)
`PUT`	`/addresses/{addressId}/default`	any	Mark an address as the default
`DELETE`	`/addresses/{addressId}`	any	Delete a saved address

Every endpoint is scoped to the authenticated user; addresses owned by other users are never returned and resolve as NotFound.

GET /addresses

Lists the caller's saved addresses, the default first (is_default desc) then oldest first (created_at asc).

Response 200

{
  "items": [
    {
      "id": 5,
      "user_id": 1,
      "label": "Casa",
      "address": "Av. Principal, Las Mercedes",
      "latitude": 10.487,
      "longitude": -66.88,
      "is_default": true,
      "created_at": "2026-06-26T12:00:00.000000Z",
      "updated_at": "2026-06-26T12:00:00.000000Z"
    }
  ]
}

items is an empty array when the user has no saved addresses.

POST /addresses

Creates a saved address for the caller. A user may keep at most 10 addresses. When isDefault is true, any previous default is cleared.

Request body

Field	Type	Required	Rules
`label`	string	yes	1–40 chars
`address`	string	yes	3–280 chars
`latitude`	number	yes	between −90 and 90
`longitude`	number	yes	between −180 and 180
`isDefault`	boolean	no	defaults to `false`

Response 201 — { "address": { … } } (the created address, same shape as an items entry).

Errors

Status	Body	When
`409`	`{ "error": "TooMany", "message": "Máximo 10 direcciones." }`	The user already has 10 addresses

PUT /addresses/{addressId}/default

Marks the given address as the caller's default, clearing the previous default.

Response 200 — { "address": { … } } (the refreshed address, now is_default: true).

Errors

Status	Body	When
`404`	`{ "error": "NotFound" }`	Unknown address, or it belongs to another user

DELETE /addresses/{addressId}

Deletes one of the caller's saved addresses.

Response 204 No Content.

Errors

Status	Body	When
`404`	`{ "error": "NotFound" }`	Unknown address, or it belongs to another user

Examples

# Create a saved address and make it the default
curl -X POST /api/v1/addresses \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"label": "Casa", "address": "Av. Principal, Las Mercedes", "latitude": 10.487, "longitude": -66.88, "isDefault": true}'

# Switch the default to another address
curl -X PUT /api/v1/addresses/5/default -H "Authorization: Bearer {token}"