Subscriptions

A subscription (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 in ACTIVE 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

curl --request POST \
  --url 'https://tapipay-facade.homo.tapila.cloud/subscriptions' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'x-authorization-token: YOUR_TAPI_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "externalSubscriptionId": "SUB-2026-007",
    "externalClientId": "CLI-00042",
    "amount": 999.00,
    "currency": "MXN",
    "intervalUnit": "month",
    "intervalCount": 1,
    "startDate": "2026-06-15",
    "totalCycles": 12,
    "productName": "Gym Plan"
  }'

Main fields

string

required

Natural key of the subscription. Unique per organization. If you repeat it, the API responds 409 RESOURCE_CONFLICT. See Idempotency.

string | object

required

The debtor. One of the two is required and they are mutually exclusive (do not send 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, in exact lowercase. It is case-sensitive: MONTH returns 400.

integer

required

Number of units per cycle, an integer greater than or equal to 1. For example, intervalUnit: "month" + intervalCount: 3 is quarterly.

string

required

Start date in YYYY-MM-DD format (a valid calendar date).

string

required

Name of the product being charged. If the name already exists in your organization, it is reused; otherwise the product is created inline. See Inline creation.

integer

Number of cycles to generate, from 1 to 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 valid with month or year intervals, and month (from 1 to 12) only with year. See below.

boolean

default:"false"

If true, the debtor must pay the cycles in chronological order.

boolean

default:"true"

If false, the cycles cannot be paid after their due date.

boolean

default:"true"

Enables partial payments on the generated debts.

boolean

default:"false"

Requests autopay for the cycles. autopay: true and paymentMethods are mutually exclusive: sending both returns 400.

string[]

Payment methods enabled for the cycles. Mutually exclusive with autopay: true. See Payment methods.

string

Description of the subscription. Must be a string (otherwise 400).

object

Data from your own system. Must be a flat object (a scalar returns 400) and cannot use reserved keys (description, paymentMethods, productName, externalProductId, debtExpirationDate, overduePayment, allowPartialPayments, recurringDebt, debtReference); otherwise 400. It is stored on the generated debts.

Validation rules

Booleans (autopay, allowOverduePayment, allowPartialPayments, enforcePaymentOrder) only accept a literal true or false: "true", 1, etc. return 400 with details[].
Undeclared fields are ignored.
If the schedule (intervalUnit, intervalCount, startDate, totalCycles, endDate, billingDay) is invalid, the API responds 400 and nothing is created: not the subscription, the product, or the inline contact.

See API conventions for the rules shared by all endpoints.

Idempotency

Subscription creation does not use the Idempotency-Key header. The idempotency key is externalSubscriptionId: repeating it returns 409 RESOURCE_CONFLICT and no new subscription is created. The generated debts use externalRequestId = <externalSubscriptionId>-cycle-<n>, with n starting at 0 (the debt of the first cycle is -cycle-0).

Frequencies with `intervalUnit` + `intervalCount`

Frequency	`intervalUnit`	`intervalCount`
Weekly	`week`	`1`
Biweekly	`week`	`2`
Monthly	`month`	`1`
Quarterly	`month`	`3`
Every 45 days	`day`	`45`
Yearly	`year`	`1`

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. In the response, scheduling.billingDay always shows the effective billing day: if you did not send it, it is inferred from the startDate as { day } for month and { day, month } for year. For day and week it is null.

billingDay is only valid for month or year intervals. The month subfield only applies to year intervals.

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.

Cycle 1: 2026-01-31   (January has 31)
Cycle 2: 2026-02-28   (February has 28 in 2026)
Cycle 3: 2026-03-31   (returns to the original day)
Cycle 4: 2026-04-30   (April has 30)

Indefinite duration

If you do not send totalCycles 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 the scheduling object.

{
  "data": {
    "subscriptionId": "sub_839d28e1-a175-40c7-a54b-55f6c17b7964",
    "externalSubscriptionId": "SUB-2026-007",
    "status": "ACTIVE",
    "scheduling": {
      "intervalUnit": "month",
      "intervalCount": 1,
      "startDate": "2026-06-15",
      "totalCycles": 12,
      "endDate": null,
      "billingDay": { "day": 15 }
    },
    "externalClientId": "CLI-00042",
    "amount": 999.00,
    "currency": "MXN",
    "paymentUrl": "https://app.tapipay.la/s/acme-corp/portal/aB3dE5fG7h/debts",
    "enforcePaymentOrder": false,
    "autopay": false,
    "allowOverduePayment": true,
    "allowPartialPayments": true,
    "paymentMethods": ["CASH", "CARD"],
    "description": "Gym Plan",
    "additionalData": { "source": "crm" },
    "contact": {
      "contactId": "con_9aL3kP2m",
      "externalClientId": "CLI-00042",
      "createdInline": false
    },
    "product": {
      "productId": "prd_42",
      "name": "Gym Plan",
      "active": true,
      "createdInline": true
    },
    "createdAt": "2026-06-03T18:15:00.000Z",
    "updatedAt": "2026-06-03T18:15:00.000Z"
  },
  "requestId": "req_a1b2c3d4"
}

description, additionalData, and paymentMethods are only present when they have a value.
scheduling.totalCycles and scheduling.endDate are always present, with null when they do not apply.
paymentUrl is the portal URL shared by all cycles. It is an opaque URL: do not parse it or build it by hand. To open a specific cycle, use the paymentUrl of each debt in GET /subscriptions/{id}/debts.
contact.contactId always has the con_ prefix, also when the contact was created inline with contactData.
createdInline on contact and product indicates whether they were created inline when the subscription was created, and it is kept in later reads.

Lifecycle

Status	Meaning
`PROCESSING`	Transitory state while the debts are generated when creating the subscription.
`ACTIVE`	Active. The debts for the cycles have already been generated.
`PAUSED`	Manually paused. Can be resumed.
`CANCELLED`	Manually cancelled. Final state.
`ENDED`	Completed its schedule: the `endDate` or the due date of the last `totalCycles` cycle has passed. Final state. An `ACTIVE` subscription whose end date has already passed is returned as `ENDED`.

Each debt generated by the subscription has its own lifecycle (PENDING, PAID, etc.). Pausing or cancelling the subscription cancels its pending debts. See Pause, resume, and cancel and 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.

List subscriptions

GET /subscriptions returns your subscriptions sorted by externalSubscriptionId descending, with the standard pagination (page, limit). Filters:

Parameter	Description
`status`	`PROCESSING`, `ACTIVE`, `PAUSED`, `CANCELLED`, or `ENDED`. It is case-sensitive: an invalid value returns `400` (`Invalid status filter ...`). Empty is ignored.
`externalClientId`	Debtor, exact match. Combined with `status` (both must match). Empty or blank returns `400 INVALID_REQUEST`.

With no results, the response is 200 with data: []. meta.total and meta.hasMore count only the filtered items.

With the status filter, meta.total may be approximate: the filter is applied again after the actual status is calculated (for example, an expired ACTIVE subscription comes back as ENDED).

Update a subscription

PATCH /subscriptions/{id} modifies amount, description, enforcePaymentOrder, allowOverduePayment, autopay, paymentMethods, and additionalData.

Only amount is also applied to the debts already generated, keeping their partial payments and their allowPartialPayments. Cancelled debts are not modified. The other fields only change the subscription.
additionalData is a flat object with the same rules as on creation.
An empty body or a non-editable field returns 400. Invalid types and values (non-numeric amount, non-literal booleans, paymentMethods outside the enum, autopay: true together with paymentMethods) return 400 with details[].
companyCode in the body is taken as context, not as a field to modify.
A CANCELLED or ENDED subscription cannot be modified: 422 BUSINESS_RULE_VIOLATION.
If the subscription is updated but updating one of its already generated debts fails, the API responds 207 with the error envelope: error.code is PARTIAL_UPDATE and error.message says how many debts were not synced (no details). The subscription itself was updated.

Pause, resume, and cancel

Action	Effect	Errors
`POST /subscriptions/{id}/pause`	Pauses the charges and cancels all pending debts generated. Pausing an already paused subscription returns `200` with no changes.	`422` if the status does not allow pausing.
`POST /subscriptions/{id}/resume`	Only from `PAUSED`. Generates new debts with `externalRequestId = <externalSubscriptionId>-resume-<n>-cycle-<m>`, so their `debtId` values differ from the original ones.	`422` from any other status (it is not idempotent).
`POST /subscriptions/{id}/cancel`	Cancels the subscription and its pending debts. Cancelling an already cancelled subscription returns `200`.	`422 BUSINESS_RULE_VIOLATION` from `ENDED`.

Debts cancelled by pausing or cancelling are no longer listed in GET /subscriptions/{id}/debts or GET /debts, but you can still read them with GET /debts/{id}.

Subscription debts

GET /subscriptions/{id}/debts returns the generated debts, with the standard pagination.

The externalRequestId of each debt is <externalSubscriptionId>-cycle-<n> (with n starting at 0), or <externalSubscriptionId>-resume-<n>-cycle-<m> for those generated on resume.
It does not include cancelled debts (same as GET /debts) and meta.total counts only the listed ones.
The paymentUrl of each debt is an opaque URL that opens that cycle directly.

Endpoints

Method	Path	Description
`POST`	`/subscriptions`	Create a subscription.
`GET`	`/subscriptions/{id}`	Retrieve a subscription.
`GET`	`/subscriptions`	List subscriptions.
`PATCH`	`/subscriptions/{id}`	Update editable fields (`amount`, `description`, `enforcePaymentOrder`, `allowOverduePayment`, `autopay`, `paymentMethods`, `additionalData`).
`POST`	`/subscriptions/{id}/pause`	Pause.
`POST`	`/subscriptions/{id}/resume`	Resume.
`POST`	`/subscriptions/{id}/cancel`	Cancel.
`GET`	`/subscriptions/{id}/debts`	List the generated debts.

Try it in the API Reference

Explore each endpoint with its interactive playground.

Get started

What's new

Concepts

Resources

Payment portal

Webhooks

Upfront generation of cycles

Create a subscription

Main fields

Validation rules

Idempotency

Frequencies with `intervalUnit` + `intervalCount`

Billing day (`billingDay`)

Indefinite duration

The response

Lifecycle

Payment order (`enforcePaymentOrder`)

List subscriptions

Update a subscription

Pause, resume, and cancel

Subscription debts

Endpoints

Try it in the API Reference

​Upfront generation of cycles

​Create a subscription

​Main fields

​Validation rules

​Idempotency

​Frequencies with intervalUnit + intervalCount

​Billing day (billingDay)

​Indefinite duration

​The response

​Lifecycle

​Payment order (enforcePaymentOrder)

​List subscriptions

​Update a subscription

​Pause, resume, and cancel

​Subscription debts

​Endpoints

Try it in the API Reference

Upfront generation of cycles

Create a subscription

Main fields

Validation rules

Idempotency

Frequencies with `intervalUnit` + `intervalCount`

Billing day (`billingDay`)

Indefinite duration

The response

Lifecycle

Payment order (`enforcePaymentOrder`)

List subscriptions

Update a subscription

Pause, resume, and cancel

Subscription debts

Endpoints