Marketplace API: Public Business and Product Discovery

The Zippi Marketplace API exposes a fully public surface for discovering businesses, browsing product catalogs, and reading product details — no API key or login is needed. All endpoints sit under the /api/v1 prefix and return a consistent JSON envelope with success, message, and data fields. Monetary values (prices, fees) are always expressed as integers in centavos (1/100 of a Colombian peso, COP).

List Business Categories

Returns the full list of active top-level categories used to organise businesses in the marketplace (e.g. Comidas, Tiendas, Farmacias). GET /api/v1/business-categories No query parameters. No authentication required.

cURL

curl https://api.zippi.app/api/v1/business-categories

Response

Example response

{
  "success": true,
  "message": "OK",
  "data": [
    {
      "id": "cat-food",
      "name": "Comidas",
      "icon": "🍔",
      "active": true
    },
    {
      "id": "cat-store",
      "name": "Tiendas",
      "icon": "🛒",
      "active": true
    }
  ]
}

data

array

List of category objects.

data[].id

string

Slug identifier for the category (e.g. cat-food). Use this value in the category filter on GET /marketplace/businesses.

data[].name

string

Human-readable category name.

data[].icon

string

Emoji icon for UI display.

data[].active

boolean

Whether the category is currently visible to customers.

List Businesses

Returns all active, currently-operating business branches in the marketplace. Results can be filtered, searched, and sorted client-side via query parameters. GET /api/v1/marketplace/businesses No authentication required.

Query Parameters

string

Full-text search across business name, description, category name, and tags. Case-insensitive partial match.

Response

data

array

Ordered array of business-branch cards.

data[].id

string

Composite business reference in the format biz-{businessId}-branch-{branchId}. Pass this value as business_ref to the products endpoint.

data[].name

string

Display name of the branch.

data[].slug

string

URL-safe slug derived from the branch name. Can be used in place of id on the detail endpoint.

data[].businessType

string

Internal business type key (e.g. restaurante, tienda, farmacia).

data[].categoryId

string

Category identifier matching the categories list.

data[].categoryName

string

Human-readable category name.

data[].description

string

Short business description.

data[].rating

number

Average customer rating (0–5).

data[].deliveryTimeMin

integer

Minimum estimated delivery time in minutes.

data[].deliveryTimeMax

integer

Maximum estimated delivery time in minutes.

data[].deliveryFee

integer

Delivery fee in centavos (integer).

data[].serviceFee

integer

Platform service fee in centavos (integer).

data[].isOpen

boolean

Whether the branch is currently accepting orders.

data[].image

string

URL of the business cover image.

data[].logo

string

Two-letter monogram used as a fallback logo in the UI.

data[].neighborhood

string

City or neighbourhood the branch serves.

data[].address

string

Street address of the branch.

data[].phone

string

Contact phone number.

data[].featured

boolean

Whether the branch is featured in the homepage carousel (first 3 results).

data[].popular

boolean

Whether the branch is promoted as popular (first 6 results).

data[].businessId

integer

Internal numeric ID of the parent business entity.

data[].branchId

integer

Internal numeric ID of this branch.

Prices (deliveryFee, serviceFee) are returned as integer centavos. Divide by 100 to display in Colombian pesos (COP). For example, 3500 = $35.00 COP.

Get Business Detail

Returns full detail for a single business branch, including operating hours and branch metadata. GET /api/v1/marketplace/businesses/:slug No authentication required. The :slug path segment accepts either the URL slug (e.g. pizza-express) or the composite id string (biz-12-branch-5).

Path Parameters

slug

string

required

The branch slug or composite biz-{businessId}-branch-{branchId} identifier.

cURL

curl https://api.zippi.app/api/v1/marketplace/businesses/pizza-express

Response

Returns the same business card object as described in the List Businesses response, plus the following additional fields:

data.schedule

string

Operating hours description (e.g. Lun–Sáb 10:00–22:00).

data.whatsapp

string

WhatsApp-ready phone number including country code prefix (e.g. 573001234567).

data.tags

array of strings

Category and feature tags for the business.

Returns 404 if no active, operating branch matches the slug.

Get Business Product Catalog

Returns all active products for a business branch, grouped by product category. GET /api/v1/marketplace/businesses/:business_ref/products No authentication required.

Path Parameters

business_ref

string

required

Accepts any of the following forms:

Composite ref: biz-{businessId}-branch-{branchId} (e.g. biz-12-branch-5)
Numeric branch ID (e.g. 5)
Branch slug (e.g. pizza-express)

cURL

curl https://api.zippi.app/api/v1/marketplace/businesses/biz-12-branch-5/products

Response

data.categories

array

Ordered list of distinct product categories present in this catalog.

data.categories[].id

string

Slugified category name (e.g. entradas).

data.categories[].name

string

Human-readable category label (e.g. Entradas).

data.products

array

Flat list of all active products, sorted alphabetically by name.

data.products[].id

string

Product reference in the format prod-{id}. Use this value as productId when placing an order.

data.products[].businessId

string

Composite business reference (biz-{businessId}-branch-{branchId}).

data.products[].categoryId

string

Category identifier this product belongs to.

data.products[].categoryName

string

Human-readable category name for grouping in the UI.

data.products[].name

string

Product name.

data.products[].description

string

Product description (may be empty string).

data.products[].price

integer

Unit price in centavos (integer). See note below.

data.products[].image

string

URL of the product image (may be empty string).

data.products[].tags

array of strings

Searchable tags, derived from the product’s category.

data.products[].isAvailable

boolean

Whether the product is currently available for ordering.

data.products[].stock

integer

Available stock quantity. Returns 99 when stock is not tracked.

data.products[].optionGroups

array

Option groups (e.g. size, temperature). Currently returns an empty array; options are a planned extension.

data.products[].additionGroups

array

Addition groups (e.g. toppings, extras). Currently returns an empty array; additions are a planned extension.

All price values in product responses are integer centavos. A product priced at 8500 costs $85.00 COP. Never use client-submitted prices in orders — the server always recalculates totals from the catalog.

Example response

{
  "success": true,
  "message": "OK",
  "data": {
    "categories": [
      { "id": "hamburguesas", "name": "Hamburguesas" },
      { "id": "bebidas", "name": "Bebidas" }
    ],
    "products": [
      {
        "id": "prod-101",
        "businessId": "biz-12-branch-5",
        "categoryId": "cat-food",
        "categoryName": "Hamburguesas",
        "name": "Hamburguesa Clásica",
        "description": "Carne de res, lechuga, tomate y salsa especial.",
        "price": 14000,
        "image": "",
        "tags": ["hamburguesas"],
        "isAvailable": true,
        "stock": 99,
        "optionGroups": [],
        "additionGroups": []
      }
    ]
  }
}

Get Product Detail

Returns full detail for a single product, including its option and addition groups. GET /api/v1/marketplace/products/:product_id No authentication required.

Path Parameters

product_id

string

required

The product reference. Accepts either prod-{id} format (e.g. prod-101) or a bare numeric ID (e.g. 101).

cURL

curl https://api.zippi.app/api/v1/marketplace/products/prod-101

Response

Returns a single product object with the same fields described in the catalog response, directly under data.

Example response

{
  "success": true,
  "message": "OK",
  "data": {
    "id": "prod-101",
    "businessId": "biz-12",
    "categoryId": "cat-food",
    "categoryName": "Hamburguesas",
    "name": "Hamburguesa Clásica",
    "description": "Carne de res, lechuga, tomate y salsa especial.",
    "price": 14000,
    "image": "",
    "tags": ["hamburguesas"],
    "isAvailable": true,
    "stock": 99,
    "optionGroups": [],
    "additionGroups": []
  }
}

Returns 404 with {"success": false, "message": "Producto no encontrado"} when the product ID is not found or the product is inactive.

Prices (price) are always integer centavos. Divide by 100 for display. Only products with isAvailable: true can be added to an order — the server rejects items for inactive or non-existent products at checkout.

Authentication

Marketplace & Customer

Business Portal

Operations

Marketplace API: Public Business and Product Discovery

List Business Categories

Response

List Businesses

Query Parameters

Response

Get Business Detail

Path Parameters

Response

Get Business Product Catalog

Path Parameters

Response

Get Product Detail

Path Parameters

Response

Build docs developers (and LLMs) love

Authentication

Marketplace & Customer

Business Portal

Operations

Documentation Index

​List Business Categories

​Response

​List Businesses

​Query Parameters

​Response

​Get Business Detail

​Path Parameters

​Response

​Get Business Product Catalog

​Path Parameters

​Response

​Get Product Detail

​Path Parameters

​Response

Build docs developers (and LLMs) love

List Business Categories

Response

List Businesses

Query Parameters

Response

Get Business Detail

Path Parameters

Response

Get Business Product Catalog

Path Parameters

Response

Get Product Detail

Path Parameters

Response