Saltar al contenido principal
El Billing Engine de Z2Pay es el motor de cobranza recurrente de la plataforma. Crea suscripciones que generan facturas en cada ciclo, y cada factura cobrada se convierte en una transacción en el PSP (visible en el dashboard con origen billing).
La API de Billing utiliza una URL base propia, diferente de la Core API. En los ejemplos de esta sección la base es https://billing-api.sandbox.z2pay.com. La autenticación es la misma que en el resto de la plataforma: el header x-api-key con tu clave de sandbox. Consulta Autenticación y Entornos.

​
El modelo: Plan → Precio → Suscripción → Factura

La recurrencia se construye a partir de cuatro recursos encadenados. Entender esta cadena es el primer paso para integrar.

Plan (Plan)

El catálogo de la oferta recurrente: nombre, código y los componentes que la conforman. Comienza en draft, se publica (active) y puede archivarse (archived).

Precio (Price)

Una versión de precio de un componente del plan: define unitAmount (en centavos), currency y la recurrence (cada cuánto se cobra). Versionado — crear un nuevo Precio desactiva el anterior de la misma moneda/recurrencia.

Suscripción (Subscription)

Vincula un cliente a un plan (o a ítems sueltos). Es el contrato vigente: tiene estado, método de pago predeterminado, fecha de la próxima factura y ciclos.

Factura (Invoice)

El documento de cobro de un ciclo. Nace de una suscripción, se cobra a través del PSP y transiciona entre open, paid, past_due, etc.
No es necesario crear un Plan para tener una suscripción. Es posible crear una suscripción con ítems sueltos (inline), informando description y unitAmount directamente — en ese caso recurrence y currency pasan a ser obligatorios en el cuerpo de la suscripción. El camino a través del Plan es el recomendado cuando vendes la misma oferta a muchos clientes.

​
Cómo funcionan los ciclos

Una vez que la suscripción existe, el planificador del Billing se encarga del resto. En cada ciclo genera la próxima factura, dispara el cobro a través del PSP y actualiza el estado de la suscripción según el resultado.
1

Creación

Creas la suscripción (POST /subscriptions). Si se informa un defaultPaymentMethodRef, nace lista para cobrar; sin método de pago, nace como incomplete.
2

Generación de la factura

Por defecto (invoiceGenerationMode=just_in_time) el planificador genera una factura por ciclo. En upfront, todas las maxCycles facturas se emiten al momento de la creación (cada una con su propio vencimiento).
3

Cobro

Con collectionMethod=charge_automatically (por defecto), el Billing cobra el método de pago predeterminado. Cada cobro se convierte en una transacción en el PSP con origin=billing. Con send_invoice, la factura simplemente se emite para que el cliente la pague.
4

Próximo ciclo

Una vez pagada la factura, el planificador avanza la suscripción al siguiente ciclo y repite — hasta alcanzar maxCycles (si está definido) o hasta la cancelación.
Para probar ciclos sin esperar, utiliza los recursos de simulación del sandbox. Consulta Sandbox: simular y Ciclos y cobranza.

​
Endpoints principales

Visión consolidada de los recursos de Billing. Cada grupo tiene su propia página de referencia con los campos completos del cuerpo y ejemplos. Todas las rutas requieren el header x-api-key.

​
Planes y Precios

MétodoRutaDescripción
POST/plansCrea un plan (estado inicial draft).
GET/plansLista planes (paginado, con filtros).
GET/plans/:idDetalla un plan.
PATCH/plans/:idActualiza campos del plan.
POST/plans/:id/publishPublica el plan (draft → active).
POST/plans/:id/archiveArchiva el plan.
GET/plans/:id/templateDevuelve el plan + componentes con el Precio actual de cada uno.
GET/plans/:id/itemsLista los componentes del plan.
POST/plans/:id/itemsAgrega un componente al plan.
PATCH/plans/:id/items/:itemIdActualiza un componente.
DELETE/plans/:id/items/:itemIdArchiva un componente.
GET/plans/:id/pricesLista las versiones de Precio del plan.
POST/plans/:id/pricesCrea una nueva versión de Precio.
POST/plans/:id/prices/:priceId/archiveArchiva una versión de Precio.
POST/plans/:id/chargesCrea componente + Precio inicial de forma atómica.
Detalles y campos: Planes y Precios.

​
Suscripciones

MétodoRutaDescripción
POST/subscriptionsCrea una suscripción.
GET/subscriptionsLista suscripciones (paginado, con filtros).
GET/subscriptions/:idDetalla una suscripción.
GET/subscriptions/:id/itemsLista los ítems activos de la suscripción.
POST/subscriptions/:id/cancelCancela (inmediato o al final del ciclo).
POST/subscriptions/:id/uncancelDeshace una cancelación programada.
POST/subscriptions/:id/pausePausa la suscripción.
POST/subscriptions/:id/resumeReanuda una suscripción pausada.
Detalles y campos: Suscripciones.

​
Facturas

MétodoRutaDescripción
GET/invoicesLista facturas (paginado, con filtros).
GET/invoices/:idDetalla una factura.
GET/invoices/:id/line-itemsLista los ítems de línea de la factura.
Detalles y campos: Facturas.
Los endpoints de creación y de acción (POST .../publish, POST .../cancel, POST .../pause, etc.) aceptan el header opcional Idempotency-Key. Reenviar la misma solicitud con la misma clave devuelve el mismo resultado, sin duplicar la operación. Consulta Convenciones.

​
Primer contacto (sandbox)

Un GET rápido para confirmar que tu clave de sandbox alcanza la API de Billing y lista las suscripciones existentes (la lista vendrá vacía si aún no creaste ninguna). 
curl https://billing-api.sandbox.z2pay.com/subscriptions \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"
Respuesta (lista paginada): 
{
  "data": [
    {
      "id": "sub_8KzQp2vR7nML3xY",
      "customerId": "cust_4Tg9hLm0bWqA",
      "status": "active",
      "currency": "BRL",
      "collectionMethod": "charge_automatically",
      "nextInvoiceAt": "2026-07-24T12:00:00.000-03:00"
    }
  ],
  "page": 1,
  "limit": 20,
  "total": 1
}
Los campos y el formato exacto de la respuesta de cada recurso están documentados en las páginas de referencia específicas. La respuesta anterior es ilustrativa para que reconozcas la forma de la lista paginada — consulta Suscripciones para el objeto completo.

​
Errores

Los endpoints de Billing siguen el mismo patrón de error de la plataforma. Estados comunes en esta sección:
  • 404 — recurso no encontrado (suscripción, plan, precio o cliente inexistente).
  • 409 — operación inválida para el estado actual (ej.: cancelar una suscripción ya cancelada, pausar una suscripción upfront, o conflicto de validación al crear).
  • 400 — cuerpo inválido (ej.: campos obligatorios ausentes o combinación de campos no permitida).
Formato completo y tabla de códigos en Errores.

​
Ver también

Planes y Precios

Construye el catálogo de tu oferta recurrente.

Suscripciones

Crea, cancela, pausa y reanuda contratos.

Facturas

Consulta los cobros generados en cada ciclo.

Ciclos y cobranza

Comprende la generación de facturas, el cobro y el avance de ciclo.

Clientes

La suscripción siempre apunta a un cliente.

Webhooks

Recibe notificaciones de factura pagada, fallo de cobro y cambios de estado.