Subscription) is a recurring charge that automatically generates a series of debts, one per cycle. You define what to charge (amount, frequency, debtor, and duration) and TapiPay generates the cycles and resolves all of the internal complexity for you.
When to use it: charges that repeat over time (monthly payments, credit installments, periodic plans). For a single charge use a debt; to charge without a known debtor, use a payment link.
Upfront generation of cycles
When you create the subscription, TapiPay calculates the dates of all cycles and generates the debts upfront (there is no process that creates one cycle per month). The generation of those debts happens asynchronously: the subscription is returned inACTIVE status as soon as the calculation and queuing finish successfully.
If the generation of the debts fails, the subscription is automatically reverted so that you can retry with the same
externalSubscriptionId without duplicating charges.Create a subscription
Main fields
string
required
Natural key of the subscription. Unique per organization. If you repeat it, the API responds
409 RESOURCE_CONFLICT.string | object
required
The debtor. Send one of the two (not both), just like in a debt. In v1 each subscription has exactly one debtor.
number
required
Amount per cycle in pesos, with up to 2 decimal places (minimum
0.01).string
required
Interval unit:
day, week, month, or year.integer
required
Number of units per cycle. For example,
intervalUnit: "month" + intervalCount: 3 is quarterly.string
required
Start date in
YYYY-MM-DD format.integer
Number of cycles to generate (maximum 520). Mutually exclusive with
endDate.string
End date (
YYYY-MM-DD), later than startDate. Mutually exclusive with totalCycles.object
Override of the billing day:
{ day, month? }. Only applies to month or year intervals. See below.boolean
default:"false"
If
true, the debtor must pay the cycles in chronological order.description, productName, allowOverduePayment, allowPartialPayments, autopay, and paymentMethods with the same behavior as a debt. See Payment methods.
Frequencies with intervalUnit + intervalCount
Billing day (billingDay)
By default, the billing day is inferred from the startDate (anniversary model): if the subscription starts on the 15th, all charges fall on the 15th. The billingDay override decouples the billing day from the startDate.
End of month: if the configured day exceeds the last day of the month (for example, 31 in February), the charge is made on the last day of the month; the following month returns to the original day.
Indefinite duration
If you do not sendtotalCycles or endDate, the subscription stays ACTIVE and only the debt for the first cycle is generated (to avoid generating charges without limit). Define totalCycles or endDate when you want to generate all cycles upfront.
The response
The scheduling data travels nested in thescheduling object.
Lifecycle
Each debt generated by the subscription has its own lifecycle (
PENDING, PAID, etc.). Cancelling the subscription does not automatically cancel the debts already generated. See Debts.Payment order (enforcePaymentOrder)
With enforcePaymentOrder: true, the debtor cannot pay a cycle if there are earlier unpaid cycles. Attempting it returns 422 BUSINESS_RULE_VIOLATION. They must settle them in chronological order.
Endpoints
Try it in the API Reference
Explore each endpoint with its interactive playground.