API reference

Recurring billing

Subscribe your customers to a plan (plans are created in the dashboard). Each installment is a single-use charge with its own `checkoutUrl`, and paying it creates a regular order. PRO and PREMIUM plans only.

Endpoints

GET/v1/subscription-plansList plans
POST/v1/subscriptionsSubscribe a customer
GET/v1/subscriptions/{id}Retrieve a subscription
POST/v1/subscriptions/{id}/cancelCancel a subscription

The Subscription object

Object fields, as the API returns them.

objectstring
Always subscription.
idstring (uuid)
Subscription id.
planIdstring (uuid)
Plan id.
planNamestring
Plan name.
customerobject
Your customer.
customer.namestring
Name.
customer.emailstringNullable
Email for reminders.
customer.phonestringNullable
WhatsApp, digits only.
localestring
Reminder language.
Possible values:esen
statusstring
Stored status.
Possible values:ACTIVEPAUSEDCANCELLEDENDED
statestring
What you see in the dashboard: CURRENT = up to date; OVERDUE = at least one unpaid overdue installment.
Possible values:CURRENTOVERDUEPAUSEDCANCELLEDENDED
frequencystring
How often it's charged.
Possible values:WEEKLYMONTHLYYEARLY
amountstring (decimal)
Amount of the next installment.
customAmountboolean
true if the amount is this customer's own and not the plan's.
currencystring
Always USD.
startDatestring
Start date.
nextDueDatestringNullable
Due date of the next installment to be generated.
nextInstallmentNumberinteger
Number of the next installment.
totalInstallmentsintegerNullable
The plan's number of installments, or null.
overdueCountinteger
Unpaid overdue installments.
overdueAmountstring (decimal)
What they add up to.
autoChargeMethodstringNullable
Reserved for automatic charging with a saved card. Always null today: each installment is paid through its link.
referencestringNullable
Your reference.
metadataobject
Your data, as you sent it.
sourcestring
Where it was created: dashboard or api_v1.
Possible values:dashboardapi_v1
pausedAtstring (date-time)Nullable
When it was paused.
cancelledAtstring (date-time)Nullable
When it was cancelled.
endedAtstring (date-time)Nullable
When it ended (the last installment was paid).
createdAtstring (date-time)
When it was created.
installmentsInstallment[]
The latest installments, most recent first.

The Subscription object

JSON

{  "object": "subscription",  "id": "3f7a1c9e-2b4d-4e6f-8a1b-5c7d9e0f1a2b",  "planId": "0b8f6c2e-4f0a-4b8e-9a51-2a4c6f1d9e10",  "planName": "Mensualidad",  "customer": {    "name": "Ana Pérez",    "email": "ana@example.com",    "phone": "584121234567"  },  "locale": "es",  "status": "ACTIVE",  "state": "CURRENT",  "frequency": "MONTHLY",  "amount": "30.00",  "customAmount": false,  "currency": "USD",  "startDate": "2026-11-01",  "nextDueDate": "2026-12-05",  "nextInstallmentNumber": 2,  "totalInstallments": null,  "overdueCount": 0,  "overdueAmount": "0.00",  "autoChargeMethod": null,  "reference": "SOCIO-118",  "metadata": {},  "source": "api_v1",  "pausedAt": null,  "cancelledAt": null,  "endedAt": null,  "createdAt": "2026-10-26T15:20:44Z",  "installments": [    {      "id": "8c1d2e3f-4a5b-4c6d-9e7f-0a1b2c3d4e5f",      "number": 1,      "dueDate": "2026-11-05",      "amount": "30.00",      "currency": "USD",      "status": "PENDING",      "overdue": false,      "checkoutUrl": "https://pay.tucapi.com/m4q8z2kx",      "orderId": null,      "paidAt": null,      "createdAt": "2026-11-02T13:00:04Z"    }  ]}

List plans

GET/v1/subscription-plans

Your business's active plans. They're created and edited in the dashboard, under Recurring billing. If your plan doesn't include recurring billing, it returns 403 feature_locked.

Scopeorders:read

Returns

Returns a paginated list of SubscriptionPlan objects.

Error responses

401 403 429

GET /v1/subscription-plans

curl "https://api.business.tucapi.com/v1/subscription-plans" \  -H "Authorization: Bearer $TUCAPI_KEY"

200 Response

JSON

{  "object": "list",  "data": [    {      "id": "0b8f6c2e-4f0a-4b8e-9a51-2a4c6f1d9e10",      "name": "Mensualidad",      "description": null,      "amount": "30.00",      "currency": "USD",      "frequency": "MONTHLY",      "billingDay": 5,      "totalInstallments": null,      "reminderDaysBefore": 3,      "archived": false,      "activeSubscribers": 42,      "totalSubscribers": 47,      "createdAt": "2026-10-20T14:02:11Z"    }  ]}

Subscribe a customer

POST/v1/subscriptions

The first installment is due on the first billing day from startDate and is generated reminderDaysBefore days earlier: that's when you get subscription.installment.created with its checkoutUrl and, if your customer has an email, they get the reminder.

Scopeorders:write

Headers

Idempotency-KeystringOptional
A unique id for the operation. Recommended on every POST. See Idempotency.
Up to 255 characters

Request body

planIdstring (uuid)Required
A plan from GET /subscription-plans.
customerobjectRequired
Your customer.
customer.namestringRequired
Customer name.
Up to 120 characters
customer.emailstringOptional
Where each installment reminder is sent.
customer.phonestringOptional
WhatsApp number with country code. Only the digits are kept (8 to 15).
localestringOptional
Language of the reminders: es or en.
Default: esPossible values:esen
amountstring | numberOptional
Greater than 0, up to 2 decimals, up to 1,000,000. As a string (recommended) or a number.
startDatestringOptional
Start date, YYYY-MM-DD. From 31 days ago up to 2 years ahead. Defaults to today (New York time).
referencestringOptional
Your order or invoice number. Unique per merchant: reusing it returns 409 reference_exists.
Up to 120 characters
metadataobjectOptional
Up to 20 keys and 4 KB. Returned as is.

Returns

Returns a Subscription object.

Error responses

400 401 403 404 409 429

POST /v1/subscriptions

curl -X POST https://api.business.tucapi.com/v1/subscriptions \  -H "Authorization: Bearer $TUCAPI_KEY" \  -H "Content-Type: application/json" \  -H "Idempotency-Key: SOCIO-118" \  -d '{    "planId": "0b8f6c2e-4f0a-4b8e-9a51-2a4c6f1d9e10",    "customer": {      "name": "Ana Pérez",      "email": "ana@example.com",      "phone": "+58 412 123 4567"    },    "locale": "es",    "startDate": "2026-11-01",    "reference": "SOCIO-118"  }'

201 Response

JSON

{  "object": "subscription",  "id": "3f7a1c9e-2b4d-4e6f-8a1b-5c7d9e0f1a2b",  "planId": "0b8f6c2e-4f0a-4b8e-9a51-2a4c6f1d9e10",  "planName": "Mensualidad",  "customer": {    "name": "Ana Pérez",    "email": "ana@example.com",    "phone": "584121234567"  },  "locale": "es",  "status": "ACTIVE",  "state": "CURRENT",  "frequency": "MONTHLY",  "amount": "30.00",  "customAmount": false,  "currency": "USD",  "startDate": "2026-11-01",  "nextDueDate": "2026-11-05",  "nextInstallmentNumber": 1,  "totalInstallments": null,  "overdueCount": 0,  "overdueAmount": "0.00",  "autoChargeMethod": null,  "reference": "SOCIO-118",  "metadata": {},  "source": "api_v1",  "pausedAt": null,  "cancelledAt": null,  "endedAt": null,  "createdAt": "2026-10-26T15:20:44Z",  "installments": []}

Retrieve a subscription

GET/v1/subscriptions/{id}

Returns the subscription with its latest 24 installments, most recent first.

Scopeorders:read

Path parameters

idstring (uuid)Required
Resource id (UUID).

Returns

Returns a Subscription object.

Error responses

401 403 404 429

GET /v1/subscriptions/{id}

curl "https://api.business.tucapi.com/v1/subscriptions/3f7a1c9e-2b4d-4e6f-8a1b-5c7d9e0f1a2b" \  -H "Authorization: Bearer $TUCAPI_KEY"

200 Response

JSON

{  "object": "subscription",  "id": "3f7a1c9e-2b4d-4e6f-8a1b-5c7d9e0f1a2b",  "planId": "0b8f6c2e-4f0a-4b8e-9a51-2a4c6f1d9e10",  "planName": "Mensualidad",  "customer": {    "name": "Ana Pérez",    "email": "ana@example.com",    "phone": "584121234567"  },  "locale": "es",  "status": "ACTIVE",  "state": "CURRENT",  "frequency": "MONTHLY",  "amount": "30.00",  "customAmount": false,  "currency": "USD",  "startDate": "2026-11-01",  "nextDueDate": "2026-12-05",  "nextInstallmentNumber": 2,  "totalInstallments": null,  "overdueCount": 0,  "overdueAmount": "0.00",  "autoChargeMethod": null,  "reference": "SOCIO-118",  "metadata": {},  "source": "api_v1",  "pausedAt": null,  "cancelledAt": null,  "endedAt": null,  "createdAt": "2026-10-26T15:20:44Z",  "installments": [    {      "id": "8c1d2e3f-4a5b-4c6d-9e7f-0a1b2c3d4e5f",      "number": 1,      "dueDate": "2026-11-05",      "amount": "30.00",      "currency": "USD",      "status": "PENDING",      "overdue": false,      "checkoutUrl": "https://pay.tucapi.com/m4q8z2kx",      "orderId": null,      "paidAt": null,      "createdAt": "2026-11-02T13:00:04Z"    }  ]}

Cancel a subscription

POST/v1/subscriptions/{id}/cancel

Stops generating installments and voids the pending ones: their checkoutUrl stops accepting payments. What's already been paid isn't affected. If it was already cancelled or ended, it returns 409 subscription_not_cancellable.

Scopeorders:write

Path parameters

idstring (uuid)Required
Resource id (UUID).

Headers

Idempotency-KeystringOptional
A unique id for the operation. Recommended on every POST. See Idempotency.
Up to 255 characters

Returns

Returns a Subscription object.

Error responses

401 403 404 409 429

POST /v1/subscriptions/{id}/cancel

curl -X POST https://api.business.tucapi.com/v1/subscriptions/3f7a1c9e-2b4d-4e6f-8a1b-5c7d9e0f1a2b/cancel \  -H "Authorization: Bearer $TUCAPI_KEY" \  -H "Idempotency-Key: cancel-3f7a1c9e-2b4d-4e6f-8a1b-5c7d9e0f1a2b"

200 Response

JSON

{  "object": "subscription",  "id": "3f7a1c9e-2b4d-4e6f-8a1b-5c7d9e0f1a2b",  "planId": "0b8f6c2e-4f0a-4b8e-9a51-2a4c6f1d9e10",  "planName": "Mensualidad",  "customer": {    "name": "Ana Pérez",    "email": "ana@example.com",    "phone": "584121234567"  },  "locale": "es",  "status": "CANCELLED",  "state": "CANCELLED",  "frequency": "MONTHLY",  "amount": "30.00",  "customAmount": false,  "currency": "USD",  "startDate": "2026-11-01",  "nextDueDate": null,  "nextInstallmentNumber": 2,  "totalInstallments": null,  "overdueCount": 0,  "overdueAmount": "0.00",  "autoChargeMethod": null,  "reference": "SOCIO-118",  "metadata": {},  "source": "api_v1",  "pausedAt": null,  "cancelledAt": "2026-11-03T10:15:00Z",  "endedAt": null,  "createdAt": "2026-10-26T15:20:44Z",  "installments": [    {      "id": "8c1d2e3f-4a5b-4c6d-9e7f-0a1b2c3d4e5f",      "number": 1,      "dueDate": "2026-11-05",      "amount": "30.00",      "currency": "USD",      "status": "CANCELLED",      "overdue": false,      "checkoutUrl": "https://pay.tucapi.com/m4q8z2kx",      "orderId": null,      "paidAt": null,      "createdAt": "2026-11-02T13:00:04Z"    }  ]}