Skip to main content
The Z2Pay Billing Engine is the platform’s recurring billing engine. It creates subscriptions that generate invoices each cycle, and every charged invoice becomes a transaction in the PSP (visible in the dashboard with the billing origin).
The Billing API uses its own base URL, separate from the Core API. In the examples in this section the base is https://billing-api.sandbox.z2pay.com. Authentication is the same as the rest of the platform: the x-api-key header with your sandbox key. See Authentication and Environments.

​
The model: Plan → Price → Subscription → Invoice

Recurring billing is built on four chained resources. Understanding this chain is the first step to integrating.

Plan

The catalog of the recurring offer: name, code, and the components it is made of. Starts in draft, is published (active), and can be archived (archived).

Price

A price version of a plan component: defines unitAmount (in cents), currency, and the recurrence (how often it charges). Versioned — creating a new Price deactivates the previous one for the same currency/recurrence.

Subscription

Links a customer to a plan (or to standalone items). It is the live contract: it has a status, a default payment method, the next invoice date, and cycles.

Invoice

The billing document for one cycle. It is born from a subscription, charged via the PSP, and transitions between open, paid, past_due, etc.
You do not need to create a Plan to have a subscription. It is possible to create a subscription with standalone items (inline), providing description and unitAmount directly — in that case recurrence and currency become required in the subscription body. The Plan path is recommended when you sell the same offer to many customers.

​
How cycles work

Once the subscription exists, the Billing scheduler takes care of the rest. Each cycle it generates the next invoice, triggers the charge via the PSP, and updates the subscription status based on the result.
1

Creation

You create the subscription (POST /subscriptions). If a defaultPaymentMethodRef is provided, it is ready to charge from the start; without a payment method, it is created as incomplete.
2

Invoice generation

By default (invoiceGenerationMode=just_in_time) the scheduler generates one invoice per cycle. In upfront mode, all maxCycles invoices are issued at creation time (each with its own due date).
3

Charging

With collectionMethod=charge_automatically (default), Billing charges the default payment method. Each charge becomes a PSP transaction with origin=billing. With send_invoice, the invoice is only issued for the customer to pay manually.
4

Next cycle

Once the invoice is paid, the scheduler advances the subscription to the next cycle and repeats — until maxCycles is reached (if set) or until cancellation.
To test cycles without waiting, use the sandbox simulation features. See Sandbox: simulate and Cycles and billing.

​
Main endpoints

A consolidated view of the Billing resources. Each group has its own reference page with complete body fields and examples. All routes require the x-api-key header.

​
Plans and Prices

MethodRouteDescription
POST/plansCreates a plan (initial status draft).
GET/plansLists plans (paginated, with filters).
GET/plans/:idRetrieves a plan’s details.
PATCH/plans/:idUpdates plan fields.
POST/plans/:id/publishPublishes the plan (draft → active).
POST/plans/:id/archiveArchives the plan.
GET/plans/:id/templateReturns the plan and its components with the current Price for each.
GET/plans/:id/itemsLists the plan’s components.
POST/plans/:id/itemsAdds a component to the plan.
PATCH/plans/:id/items/:itemIdUpdates a component.
DELETE/plans/:id/items/:itemIdArchives a component.
GET/plans/:id/pricesLists the plan’s Price versions.
POST/plans/:id/pricesCreates a new Price version.
POST/plans/:id/prices/:priceId/archiveArchives a Price version.
POST/plans/:id/chargesCreates a component and its initial Price atomically.
Details and fields: Plans and Prices.

​
Subscriptions

MethodRouteDescription
POST/subscriptionsCreates a subscription.
GET/subscriptionsLists subscriptions (paginated, with filters).
GET/subscriptions/:idRetrieves a subscription’s details.
GET/subscriptions/:id/itemsLists the subscription’s active items.
POST/subscriptions/:id/cancelCancels (immediately or at end of cycle).
POST/subscriptions/:id/uncancelUndoes a scheduled cancellation.
POST/subscriptions/:id/pausePauses the subscription.
POST/subscriptions/:id/resumeResumes a paused subscription.
Details and fields: Subscriptions.

​
Invoices

MethodRouteDescription
GET/invoicesLists invoices (paginated, with filters).
GET/invoices/:idRetrieves an invoice’s details.
GET/invoices/:id/line-itemsLists the invoice’s line items.
Details and fields: Invoices.
The creation and action endpoints (POST .../publish, POST .../cancel, POST .../pause, etc.) accept the optional Idempotency-Key header. Resending the same request with the same key returns the same result without duplicating the operation. See Conventions.

​
First call (sandbox)

A quick GET to confirm that your sandbox key can reach the Billing API and to list existing subscriptions (the list will be empty if you have not created any yet). 
curl https://billing-api.sandbox.z2pay.com/subscriptions \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"
Response (paginated list): 
{
  "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
}
The exact fields and response format for each resource are documented in the specific reference pages. The response above is illustrative so you can recognize the shape of a paginated list — see Subscriptions for the complete object.

​
Errors

The Billing endpoints follow the same error pattern as the rest of the platform. Common statuses in this section:
  • 404 — resource not found (subscription, plan, price, or customer does not exist).
  • 409 — operation invalid for the current state (e.g., cancelling an already-cancelled subscription, pausing an upfront subscription, or a validation conflict on creation).
  • 400 — invalid body (e.g., required fields missing or a forbidden combination of fields).
Full format and error code table in Errors.

​
See also

Plans and Prices

Build the catalog for your recurring offer.

Subscriptions

Create, cancel, pause, and resume contracts.

Invoices

Query the charges generated each cycle.

Cycles and billing

Understand invoice generation, charging, and cycle advancement.

Customers

A subscription always points to a customer.

Webhooks

Receive notifications for paid invoices, charge failures, and status changes.