Customer Profile, Addresses, and Favorites API Reference

The Customer Profile API provides registered customers with full control over their account data: personal details, saved delivery addresses, and favorited businesses. Every endpoint in this group is protected by the require_customer guard, which validates the customer JWT and enforces that each customer can only read and modify their own data.

All endpoints below require a valid customer JWT issued at login. Include it as Authorization: Bearer {token} on every request. Tokens expire after the number of minutes configured in JWT_ACCESS_TOKEN_EXPIRES_MINUTES (default: 4 minutes as set in .env.example). Use the refresh flow to obtain a new access token without re-authenticating.

Personalized Home

Returns a personalized homepage payload for the logged-in customer, including business recommendations, featured businesses, and recent order suggestions. GET /api/v1/customer/home

This endpoint does not require authentication at the route level — it is publicly accessible. However, when a customer JWT is present the response may be personalised in future versions. Currently it returns the same marketplace home data regardless of authentication state.

cURL

curl https://api.zippi.app/api/v1/customer/home \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response

data.categories

array

Active business categories. Same shape as GET /api/v1/business-categories.

data.featuredBusinesses

array

Up to 3 featured business-branch cards.

data.popularBusinesses

array

Up to 6 popular business-branch cards.

data.nearBusinesses

array

Up to 4 nearby business-branch cards (first 4 in alphabetical order).

Businesses with active promotions. May be empty.

data.openBusinesses

array

All branches currently in OPERANDO state.

Get Customer Profile

Returns the current customer’s name, email, and phone. GET /api/v1/customer/profile Requires customer JWT.

cURL

curl https://api.zippi.app/api/v1/customer/profile \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response

data.id

string

Customer ID as a string (numeric).

data.name

string

Full name of the customer.

data.phone

string

Phone number (unique identifier for the customer record).

data.email

string | null

Email address, or null if not set.

data.notes

string | null

Internal notes on the customer record (notas), or null if none have been set.

data.createdAt

string

ISO 8601 UTC timestamp of account creation.

Example response

{
  "success": true,
  "message": "OK",
  "data": {
    "id": "7",
    "name": "Laura Gómez",
    "phone": "3001234567",
    "email": "laura@example.com",
    "notes": null,
    "createdAt": "2024-11-03T14:22:00"
  }
}

Update Customer Profile

Updates the authenticated customer’s name and/or email address. Phone number cannot be changed through this endpoint. PUT /api/v1/customer/profile Requires customer JWT.

Request Body

name

string

New display name. Trimmed and truncated to 120 characters. Omit to leave unchanged.

string | null

New email address. Pass an empty string or null to clear the email field. Omit to leave unchanged.

cURL

curl -X PUT https://api.zippi.app/api/v1/customer/profile \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "name": "Laura M. Gómez",
    "email": "laura.new@example.com"
  }'

Response

Returns the full updated profile object. Same shape as Get Customer Profile.

List Saved Addresses

Returns all delivery addresses saved to the customer’s account, with the default address first. GET /api/v1/customer/addresses Requires customer JWT.

cURL

curl https://api.zippi.app/api/v1/customer/addresses \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response

data

array

Array of address objects, ordered with the default address first, then by creation date ascending.

data[].id

string

Address ID as a string (numeric).

data[].address

string

Street address text (direccion_texto).

data[].reference

string | null

Optional delivery reference or landmark.

data[].lat

number | null

Latitude coordinate, or null if not set.

data[].lng

number | null

Longitude coordinate, or null if not set.

data[].isDefault

boolean

Whether this is the customer’s currently selected default delivery address.

Example response

{
  "success": true,
  "message": "OK",
  "data": [
    {
      "id": "14",
      "address": "Cra 15 # 93-47, Apto 301",
      "reference": "Edificio azul, portería lateral",
      "lat": 4.6765,
      "lng": -74.0478,
      "isDefault": true
    },
    {
      "id": "21",
      "address": "Cl 85 # 11-32, Oficina 502",
      "reference": null,
      "lat": null,
      "lng": null,
      "isDefault": false
    }
  ]
}

Create Address

Saves a new delivery address to the customer’s account. POST /api/v1/customer/addresses Requires customer JWT.

Request Body

address

string

required

Full street address text. This field is required — a missing or empty address returns HTTP 422.

reference

string

Optional delivery reference, landmark, or apartment/floor details.

lat

number

Latitude coordinate (−90 to 90). Optional but recommended for accurate courier routing.

lng

number

Longitude coordinate (−180 to 180). Optional but recommended for accurate courier routing.

isDefault

boolean

When true, this address becomes the default and all other saved addresses are demoted. Defaults to false.

cURL

curl -X POST https://api.zippi.app/api/v1/customer/addresses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "address": "Av. El Dorado # 68C-61",
    "reference": "Torre Norte, piso 8",
    "lat": 4.6534,
    "lng": -74.1057,
    "isDefault": false
  }'

Response

Returns the created address object. HTTP 201 on success. Same shape as an element of the list addresses response.

Update Address

Updates an existing saved address. Only provided fields are changed. PUT /api/v1/customer/addresses/:id Requires customer JWT. The address must belong to the authenticated customer.

Path Parameters

integer

required

Numeric ID of the address to update.

Request Body

address

string

New street address text. Omit to leave unchanged.

reference

string | null

New reference text. Pass an empty string or null to clear it.

cURL

curl -X PUT https://api.zippi.app/api/v1/customer/addresses/14 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "address": "Cra 15 # 93-47, Apto 401",
    "reference": "Edificio azul, portería principal"
  }'

Response

Returns the full updated address object. Returns 404 if the address ID does not exist or belongs to a different customer.

Delete Address

Permanently removes a saved address from the customer’s account. DELETE /api/v1/customer/addresses/:id Requires customer JWT. The address must belong to the authenticated customer.

Path Parameters

integer

required

Numeric ID of the address to delete.

cURL

curl -X DELETE https://api.zippi.app/api/v1/customer/addresses/21 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response

{
  "success": true,
  "message": "OK",
  "data": null
}

Returns 404 if the address does not exist or belongs to a different customer.

Set Default Address

Marks one saved address as the default delivery address. All other addresses for this customer are demoted to non-default atomically. POST /api/v1/customer/addresses/:id/default Requires customer JWT.

Path Parameters

integer

required

Numeric ID of the address to promote as default.

cURL

curl -X POST https://api.zippi.app/api/v1/customer/addresses/14/default \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response

Returns the promoted address object with isDefault: true. Returns 404 if the address does not exist or belongs to a different customer.

Example response

{
  "success": true,
  "message": "OK",
  "data": {
    "id": "14",
    "address": "Cra 15 # 93-47, Apto 301",
    "reference": "Edificio azul, portería lateral",
    "lat": 4.6765,
    "lng": -74.0478,
    "isDefault": true
  }
}

List Favorite Businesses

Returns the lists of businesses and products the customer has marked as favorites. Favorites are stored as customer metadata and updated through the frontend. GET /api/v1/customer/favorites Requires customer JWT.

cURL

curl https://api.zippi.app/api/v1/customer/favorites \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response

data.businesses

array of strings

List of favorited business reference IDs (e.g. ["biz-12-branch-5", "biz-8-branch-2"]). May be empty.

data.products

array of strings

List of favorited product reference IDs (e.g. ["prod-101", "prod-205"]). May be empty.

Example response

{
  "success": true,
  "message": "OK",
  "data": {
    "businesses": ["biz-12-branch-5", "biz-8-branch-2"],
    "products": ["prod-101"]
  }
}

The require_customer guard enforces strict ownership — a customer JWT can only access, modify, or delete data that belongs to that customer’s own account. Attempting to access another customer’s addresses or profile will return HTTP 403 or 404 (fail-closed).

Authentication

Marketplace & Customer

Business Portal

Operations

Customer Profile, Addresses, and Favorites API Reference

Personalized Home

Response

Get Customer Profile

Response

Update Customer Profile

Request Body

Response

List Saved Addresses

Response

Create Address

Request Body

Response

Update Address

Path Parameters

Request Body

Response

Delete Address

Path Parameters

Response

Set Default Address

Path Parameters

Response

List Favorite Businesses

Response

Build docs developers (and LLMs) love

Authentication

Marketplace & Customer

Business Portal

Operations

Documentation Index

​Personalized Home

​Response

​Get Customer Profile

​Response

​Update Customer Profile

​Request Body

​Response

​List Saved Addresses

​Response

​Create Address

​Request Body

​Response

​Update Address

​Path Parameters

​Request Body

​Response

​Delete Address

​Path Parameters

​Response

​Set Default Address

​Path Parameters

​Response

​List Favorite Businesses

​Response

Build docs developers (and LLMs) love

Personalized Home

Response

Get Customer Profile

Response

Update Customer Profile

Request Body

Response

List Saved Addresses

Response

Create Address

Request Body

Response

Update Address

Path Parameters

Request Body

Response

Delete Address

Path Parameters

Response

Set Default Address

Path Parameters

Response

List Favorite Businesses

Response