Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/CRISTIANCAMACH34/Zippi/llms.txt

Use this file to discover all available pages before exploring further.

The Settlements endpoints expose the financial liquidation records that summarize what a business earns from a period’s orders after Zippi’s commission and payment gateway fees are deducted. All monetary amounts are integers in centavos (COP) — never floats. Settlements are immutable once generated: they represent a locked financial snapshot that can be audited and reproduced at any future point.
Settlement records are immutable once generated. The amounts bruto, comision_zippi, fee_pasarela, and neto cannot be edited via any API endpoint after the settlement is created. Disputes or corrections are handled through a separate adjustment workflow by finance_admin or city_admin.

​
How settlement amounts are calculated

For each settlement period, the net payout to the business is computed as: 
Bruto (gross revenue from orders)
  − Comisión Zippi      (configurable percentage, versioned per business)
  − Fee de pasarela     (Wompi / Nequi / transfer gateway fee)
  − Ajustes             (refunds, reversals, promotional adjustments)
  = Neto a liquidar     (amount transferred to the business)
Every component is calculated using integer arithmetic in centavos and is stored alongside the version/rate of the commission that was applied. Changing the commission rate creates a new version with a fecha_vigencia_desde; it does not retroactively alter any already-generated settlement.
Commission rates are versioned. The tasa_comision field on the Negocio model stores the current rate (e.g. "12.00" for 12%). Each settlement record stores the exact rate that was applied at generation time, ensuring full reproducibility during financial audits months or years later.

​
GET /api/v1/business/settlements

Returns a paginated list of settlement periods for the authenticated business scope. Supports filtering by date range and branch. 
curl -X GET "https://api.zippi.app/api/v1/business/settlements?from_date=2024-01-01&to_date=2024-01-31&page=1&page_size=20" \
  -H "Authorization: Bearer <token>"
Required roles: business_owner, business_admin, cashier, super_admin, or platform_admin (module: settlements). Query parameters
​
from_date
string
ISO 8601 date (e.g. 2024-01-01). Returns settlements whose period starts on or after this date.
​
to_date
string
ISO 8601 date (e.g. 2024-01-31). Returns settlements whose period ends on or before this date.
​
branch_id
string
Filter settlements for a specific branch. When omitted, all branches in the business scope are included.
​
page
integer
default:"1"
Page number, 1-indexed.
​
page_size
integer
default:"20"
Records per page. Recommended maximum: 100.
Response 200 OK 
{
  "success": true,
  "data": {
    "items": [
      {
        "id_liquidacion": "liq_20240131",
        "periodo_inicio": "2024-01-01",
        "periodo_fin": "2024-01-31",
        "branch_id": "br_01",
        "bruto_centavos": 45000000,
        "comision_zippi_centavos": 5400000,
        "tasa_comision_aplicada": "12.00",
        "fee_pasarela_centavos": 225000,
        "ajustes_centavos": -50000,
        "neto_centavos": 39325000,
        "estado": "generada",
        "fecha_generacion": "2024-02-01T03:00:00Z"
      }
    ],
    "total": 3,
    "page": 1,
    "page_size": 20
  }
}
​
id_liquidacion
string
Unique identifier for the settlement record.
​
periodo_inicio
string
ISO 8601 date marking the start of the settlement period.
​
periodo_fin
string
ISO 8601 date marking the end of the settlement period.
​
branch_id
string | null
Branch scope of the settlement. null for business-level aggregated settlements.
​
bruto_centavos
integer
Gross revenue from all completed orders in the period, in centavos. Always an integer.
​
comision_zippi_centavos
integer
Zippi commission deducted, in centavos. Computed as bruto × tasa_comision_aplicada / 100.
​
tasa_comision_aplicada
string
Decimal string of the commission rate that was active when this settlement was generated (e.g. "12.00" for 12%). Immutable after generation.
​
fee_pasarela_centavos
integer
Payment gateway fees (Wompi, Nequi, etc.) deducted, in centavos.
​
ajustes_centavos
integer
Net adjustments in centavos (negative = deductions for refunds/reversals; positive = credits). May be 0.
​
neto_centavos
integer
Net amount to be transferred to the business: bruto − comision_zippi − fee_pasarela + ajustes. Always an integer in centavos.
​
estado
string
Settlement lifecycle state. Values: generada (generated, awaiting transfer), pagada (transferred to business), en_disputa (under review), ajustada (corrected by finance admin).
​
fecha_generacion
string
ISO 8601 UTC datetime when the settlement record was created.

​
GET /api/v1/business/settlements/:id

Returns the full detail of a single settlement, including the list of order IDs included in the period, a breakdown of all fee components, and the audit trail of who generated it. 
curl -X GET https://api.zippi.app/api/v1/business/settlements/liq_20240131 \
  -H "Authorization: Bearer <token>"
Response 200 OK 
{
  "success": true,
  "data": {
    "id_liquidacion": "liq_20240131",
    "periodo_inicio": "2024-01-01",
    "periodo_fin": "2024-01-31",
    "branch_id": "br_01",
    "bruto_centavos": 45000000,
    "comision_zippi_centavos": 5400000,
    "tasa_comision_aplicada": "12.00",
    "fee_pasarela_centavos": 225000,
    "ajustes_centavos": -50000,
    "neto_centavos": 39325000,
    "estado": "pagada",
    "fecha_generacion": "2024-02-01T03:00:00Z",
    "fecha_pago": "2024-02-03T10:30:00Z",
    "ordenes_incluidas": [1001, 1002, 1045, 1088],
    "total_ordenes": 147,
    "generado_por": "system_job",
    "version_comision": "v4"
  }
}
​
ordenes_incluidas
array
Sampled list of id_pedido values included in this settlement. For large periods, only the first and last N order IDs may be returned here; the full list is available via the export endpoint.
​
total_ordenes
integer
Total count of orders included in the period’s calculation.
​
generado_por
string
Actor that triggered settlement generation: system_job for scheduled generation, or the user_id of a finance admin who triggered it manually.
​
version_comision
string
Internal version tag of the commission schedule applied. Use this to look up the exact rate table in the platform audit log.
​
fecha_pago
string | null
ISO 8601 UTC datetime when the net amount was transferred to the business. null if the settlement is still in generada state.

Build docs developers (and LLMs) love

Get started for freeTalk to us