# Recurring billing

> MCP tools to read recurring plans, subscribers and their payments, and to pause, reactivate or delete a subscriber.

- kind: mcp-tool
- status: stable
- access: destructive
- last_verified: 2026-10-20
- url: https://tilopay.com/en/developers/agentes/mcp/recurrentes

## What it covers [#que-cubre]

Four read-only tools over recurring billing plans and their subscribers, plus one sensitive tool that pauses, reactivates or deletes a subscriber. That last one affects future charges: ask for human confirmation before running it.

## Tools [#herramientas]

### List recurring plans [#tilopay-recurring-list-plans]

- `tilopay_recurring_list_plans`
- Access: Read only
- API operation: `POST /api/v1/getPlansRepeat` — https://tilopay.com/en/developers/api/recurrentes/planes/get-plans

Lists the recurring billing plans configured in Tilopay.

**Parameters**

No parameters.

**Returns**

`{ result }`

Raw Tilopay API response under the `result` key.

### Recurring plan detail [#tilopay-recurring-get-plan]

- `tilopay_recurring_get_plan`
- Access: Read only
- API operation: `POST /api/v1/getPlanRepeat` — https://tilopay.com/en/developers/api/recurrentes/planes/get-plan

Returns the detail of a recurring billing plan by its ID.

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | Plan ID |
| `include_qr` | boolean | — | Include the plan's base64 QR (false by default; use it only if the merchant asks for the QR) |

**Returns**

`{ result }`

Raw Tilopay API response under the `result` key.

### Subscriber detail [#tilopay-recurring-get-subscriber]

- `tilopay_recurring_get_subscriber`
- Access: Read only
- API operation: `POST /api/v1/getSuscriptorRepeat` — https://tilopay.com/en/developers/api/recurrentes/suscriptores/get-suscriptor-plan

Returns the detail of a subscriber of a recurring plan by its ID.

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | Subscriber ID |

**Returns**

`{ result }`

Raw Tilopay API response under the `result` key.

### Find a subscriber by name or email [#tilopay-recurring-find-subscriber]

- `tilopay_recurring_find_subscriber`
- Access: Read only

Searches for a subscriber by name or email across all recurring plans at once. Use it before pausing, reactivating or editing someone when you do not have their ID.

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | yes | Subscriber name or email |

**Returns**

`{ result }`

result = matching subscribers, each with its plan_id and plan.

### Subscriber payments [#tilopay-recurring-subscriber-payments]

- `tilopay_recurring_subscriber_payments`
- Access: Read only
- API operation: `POST /api/v1/getSuscriptorPayments` — https://tilopay.com/en/developers/api/recurrentes/suscriptores/suscriptor-payments

Lists the payments made by a recurring subscriber.

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | Subscriber ID |

**Returns**

`{ result }`

Raw Tilopay API response under the `result` key.

### Failed recurring charges [#tilopay-recurring-failed-payments]

- `tilopay_recurring_failed_payments`
- Access: Read only
- API operation: `POST /api/v1/getSuscriptorPayments` — https://tilopay.com/en/developers/api/recurrentes/suscriptores/suscriptor-payments

Lists the latest recurring charges that failed (plan, subscriber, amount, date and reason in plain language). A single call is enough.

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer | — | Maximum charges (10 by default) |
| `startDate` | string | — | From, "YYYY-MM-DD HH:mm:ss" |
| `endDate` | string | — | To, "YYYY-MM-DD HH:mm:ss" |

**Returns**

`{ total, source, failures[] }`

failures = declined recurring charges, with plan, subscriber, amount, currency and decline reason; total = how many were found; source = the API route they were obtained from. It combines the query of plans, subscribers and their payments.

### Pause, reactivate or delete a subscriber [#tilopay-recurring-manage-subscriber]

- `tilopay_recurring_manage_subscriber`
- Access: Sensitive
- Requires confirmation: https://tilopay.com/en/developers/agentes/mcp/permisos#confirmaciones
- API operation: `POST /api/v1/pauseSuscriptorRepeat, /reactiveSuscriptorRepeat o /deleteSuscriptorRepeat` — https://tilopay.com/en/developers/api/recurrentes/suscriptores/pause-suscriptor-plan

Pauses, reactivates or deletes a subscriber of a recurring plan in Tilopay. Sensitive operation: it affects future charges.

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `idSubscriber` | string | yes | Subscriber ID |
| `action` | string (pause | reactivate | delete) | yes | Action to perform |
| `confirmation_code` | string | — | 6-digit code received by email to authorize the operation |

**Returns**

`{ result }`

Raw response of the endpoint matching the action: pause, reactivate or delete.

### Create subscription plan [#tilopay-recurring-create-plan]

- `tilopay_recurring_create_plan`
- Access: Write
- API operation: `POST /api/v1/createPlanRepeat` — https://tilopay.com/en/developers/api/recurrentes/planes/create-plan

Creates a recurring billing plan (subscription) in Tilopay with its title, currency, frequency and modalities (name and amount). Returns the ID of the created plan; then use tilopay_recurring_subscription_url to get the link customers use to subscribe.

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `title` | string | yes | Plan title |
| `modality` | array<object> | yes | Plan modalities (at least one): name and amount per cycle |
| `frequency` | string (diario | semanal | mensual | anual | quincenal | bimestral | trimestral | cuatrimestral | semestral) | yes | Charge frequency |
| `description` | string | — | Plan description |
| `currency` | string | — | ISO 4217 currency, e.g. USD or CRC. If omitted, the merchant's country currency is used. |
| `first_amount` | number | — | Amount of the initial payment (0 if there is none) |
| `trial_days` | integer | — | Free trial days (0 if there is no trial) |
| `attempts` | integer | — | Retries on a failed charge (1 by default) |
| `end_at` | string | — | Plan end date in DD-MM-YYYY format (optional) |
| `thanks_url` | string | — | Thank-you URL after subscribing (optional) |
| `webhook_subscribe` | string | — | Webhook when a customer subscribes (optional) |
| `webhook_payment` | string | — | Webhook when a payment is charged (optional) |
| `webhook_rejected` | string | — | Webhook when a charge is declined (optional) |
| `webhook_unsubscribe` | string | — | Webhook when a subscription is cancelled (optional) |
| `webhook_reactive` | string | — | Webhook when a subscription is reactivated (optional) |

**Returns**

`{ result, currency, frequency }`

result = API response with the created plan; currency and frequency = the currency and frequency the plan ended up with.

### Edit subscription plan [#tilopay-recurring-edit-plan]

- `tilopay_recurring_edit_plan`
- Access: Write
- API operation: `POST /api/v1/editPlanRepeat` — https://tilopay.com/en/developers/api/recurrentes/planes/edit-plan

Edits an existing plan; this is not a partial update. title and frequency are required. Omitted fields are sent with defaults: empty description, first_amount 0, no free trial, attempts 1, empty webhooks and thank-you URL; omitted status is sent as 1 (active). The agent should read the plan with tilopay_recurring_get_plan and resend all fields. Optional modality keeps the price when omitted.

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | Plan ID |
| `title` | string | yes | Plan title |
| `frequency` | string (diario | semanal | mensual | anual | quincenal | bimestral | trimestral | cuatrimestral | semestral) | yes | Charge frequency |
| `modality` | array<object> | — | Optional array of {title: string (maximum 60 characters), amount: number > 0}; omitted keeps the price. |
| `currency` | string | — | ISO 4217 currency |
| `description` | string | — | Plan description; omitted sends an empty string |
| `first_amount` | number | — | Initial payment; omitted sends 0 |
| `trial_days` | integer | — | Free trial days; omitted sends no free trial |
| `attempts` | integer | — | Retries on a failed charge; omitted sends 1 |
| `status` | string (inactive | active | closed_to_new) | — | Status: inactive, active or closed_to_new; omitted sends 1 (active) |
| `end_at` | string | — | Plan end date in DD-MM-YYYY format (optional) |
| `thanks_url` | string | — | Thank-you URL; omitted sends an empty string |
| `webhook_subscribe` | string | — | Webhook on subscribe; omitted sends an empty string |
| `webhook_payment` | string | — | Webhook when a payment is charged; omitted sends an empty string |
| `webhook_rejected` | string | — | Webhook when a charge is declined; omitted sends an empty string |
| `webhook_unsubscribe` | string | — | Webhook on cancellation; omitted sends an empty string |
| `webhook_reactive` | string | — | Webhook on reactivation; omitted sends an empty string |

**Returns**

`{ result }`

result = API response editing the plan; omitted fields are sent with defaults, except modality, which keeps the price.

### Delete subscription plan [#tilopay-recurring-delete-plan]

- `tilopay_recurring_delete_plan`
- Access: Sensitive
- Requires confirmation: https://tilopay.com/en/developers/agentes/mcp/permisos#confirmaciones
- API operation: `POST /api/v1/deletePlanRepeat` — https://tilopay.com/en/developers/api/recurrentes/planes/delete-plan

Deletes a recurring billing plan in Tilopay. It affects the plan's future charges: confirm with the merchant before running it.

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | Plan ID |

**Returns**

`{ result }`

result = API response deleting the plan. The plan's subscribers stop being charged.

### Subscription link for a plan [#tilopay-recurring-subscription-url]

- `tilopay_recurring_subscription_url`
- Access: Read only
- API operation: `POST /api/v1/recurrentUrl` — https://tilopay.com/en/developers/api/recurrentes/suscriptores/consult-url

Returns the link a customer uses to sign up for a recurring plan (or renew it if the email is already subscribed). Deliver the full URL, without shortening it.

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | Plan ID |
| `email` | string | — | Customer email; if already subscribed it returns the renewal link |

**Returns**

`{ url, result }`

url = subscription link for the plan, to share with the customer; result = the raw API response.

### Edit a plan's subscriber [#tilopay-recurring-edit-subscriber]

- `tilopay_recurring_edit_subscriber`
- Access: Sensitive
- Requires confirmation: https://tilopay.com/en/developers/agentes/mcp/permisos#confirmaciones
- API operation: `POST /api/v1/editSuscriptorRepeat` — https://tilopay.com/en/developers/api/recurrentes/suscriptores/edit-suscriptor-plan

Changes subscriber status (active, paused or deleted), expire (YYYY-MM-DD), modality (modality ID), amount (greater than 0) and planId; only present fields are sent. If planId is missing, it is looked up. Owners and employees can use it. No email code is required; tilopay_recurring_manage_subscriber provides second-factor pause, reactivation or deletion.

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | Subscriber ID |
| `status` | string (active | paused | deleted) | — | New subscriber status |
| `expire` | string | — | Plan expiration date for that subscriber in YYYY-MM-DD format |
| `modality` | string | — | Modality ID |
| `amount` | number | — | Amount greater than 0 |
| `planId` | string | — | Plan ID; looked up if missing |

**Returns**

`{ result }`

result = API response editing the present subscriber fields.

### Create discount coupon [#tilopay-recurring-create-coupon]

- `tilopay_recurring_create_coupon`
- Access: Write
- API operation: `POST /api/v1/createCoupon` — https://tilopay.com/en/developers/api/recurrentes/cupones/create-coupon

Creates a discount coupon for a subscription plan: percentage or fixed amount, expiration date, allowed emails and usage limits.

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `planId` | string | yes | Recurring plan ID |
| `discount_type` | string (percentage | fixed) | yes | Discount type: percentage or fixed |
| `discount` | number | yes | Discount value |
| `expire` | string | yes | Coupon expiration date in YYYY-MM-DD format |
| `allow_existing_users` | boolean | — | true if already registered customers can also use it (false = new customers only) |
| `emails` | array<string> | — | Authorized emails; if omitted, any email can use it |
| `usage` | integer | — | Total number of uses |
| `renews` | integer | — | Renewals valid with the coupon |
| `renews_by_user` | integer | — | Uses per single customer |

**Returns**

`{ result }`

result = API response with the discount coupon created for the plan.

### A plan's coupons [#tilopay-recurring-list-coupons]

- `tilopay_recurring_list_coupons`
- Access: Read only
- API operation: `POST /api/v1/getRepeatCoupons` — https://tilopay.com/en/developers/api/recurrentes/cupones/get-coupons

Lists the discount coupons associated with a subscription plan.

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `planId` | string | yes | Recurring plan ID |

**Returns**

`{ result }`

result = the plan's coupons as returned by the API.

### Coupon detail [#tilopay-recurring-get-coupon]

- `tilopay_recurring_get_coupon`
- Access: Read only
- API operation: `POST /api/v1/getCoupon` — https://tilopay.com/en/developers/api/recurrentes/cupones/get-coupon

Returns the detail of a discount coupon by its ID.

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | Coupon ID |

**Returns**

`{ result }`

result = coupon detail as returned by the API.

### Delete a coupon [#tilopay-recurring-delete-coupon]

- `tilopay_recurring_delete_coupon`
- Access: Sensitive
- Requires confirmation: https://tilopay.com/en/developers/agentes/mcp/permisos#confirmaciones
- API operation: `POST /api/v1/deleteCoupon` — https://tilopay.com/en/developers/api/recurrentes/cupones/delete-coupon

Deletes a discount coupon of a subscription plan.

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | Coupon ID |

**Returns**

`{ result }`

result = API response deleting the coupon.

### Start step by step for a subscription plan [#tilopay-recurring-plan-wizard-start]

- `tilopay_recurring_plan_wizard_start`
- Access: Write

Starts the guided step-by-step to create (mode=create) or edit (mode=edit with plan_id) a subscription plan. Returns the first pending question: deliver it to the merchant as is and pass their answer to tilopay_recurring_plan_wizard_answer. Use it instead of tilopay_recurring_create_plan when some data is missing.

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `mode` | string (create | edit) | yes | create for a new plan, edit to modify an existing one |
| `plan_id` | string | — | Plan ID (required in mode=edit) |
| `title` | string | — | Title, if the merchant already gave it |
| `frequency` | string (diario | semanal | quincenal | mensual | bimestral | trimestral | cuatrimestral | semestral | anual) | — | Frequency, if the merchant already gave it |
| `amount` | number | — | Amount per cycle, if the merchant already gave it |
| `currency` | string | — | ISO currency if the merchant indicated it with a symbol or name ($ or dollars = USD, ₡ or colones = CRC) |
| `description` | string | — | Description, if already given |

**Returns**

`{ draft }`

draft = the plan draft in progress, with what has already been answered and the next pending step. It creates nothing in Tilopay until confirmed.

### Answer a step of the subscription plan [#tilopay-recurring-plan-wizard-answer]

- `tilopay_recurring_plan_wizard_answer`
- Access: Write

Saves the merchant's answer to the current step of the subscription plan and returns the next question or the summary to confirm. Deliver the returned text as is, without adding questions of your own.

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `answer` | string | yes | What the merchant answered, as is |

**Returns**

`{ draft }`

draft = the updated draft with the step's answer and the next pending step.

### Confirm the subscription plan [#tilopay-recurring-plan-wizard-confirm]

- `tilopay_recurring_plan_wizard_confirm`
- Access: Write
- API operation: `POST /api/v1/createPlanRepeat` — https://tilopay.com/en/developers/api/recurrentes/planes/create-plan

Creates or edits the subscription plan with the step-by-step data, after the merchant said yes to the summary. When creating, it also returns the subscription link: deliver it in full, without shortening it.

**Parameters**

No parameters.

**Returns**

`{ plan_id, subscription_url }`

Creates the plan with what was built step by step: plan_id = id of the created plan; subscription_url = subscription link to share.

### Cancel the plan step by step [#tilopay-recurring-plan-wizard-cancel]

- `tilopay_recurring_plan_wizard_cancel`
- Access: Write

Discards the subscription plan that was in progress without creating or changing anything.

**Parameters**

No parameters.

**Returns**

Discards the plan draft in progress. It creates or changes nothing in Tilopay; it only returns the confirmation in text.

### Payment link to settle a failed recurring charge [#tilopay-recurring-settle-link]

- `tilopay_recurring_settle_link`
- Access: Write
- API operation: `POST /api/v1/createLinkPayment` — https://tilopay.com/en/developers/api/links-de-pago/create-link-payment

Creates a payment link for the amount of a recurring charge that failed and associates it with the plan's subscriber. When the customer pays that link, the subscription is settled automatically: the subscriber is reactivated and its expiration date moves to the next cycle. Use it when the merchant agrees to send the link to the customer of a failed charge (the data comes from tilopay_recurring_failed_payments). Returns the link URL and, if there is a phone number, a WhatsApp link ready to send to the customer.

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `subscriber_id` | string | yes | ID of the subscriber with the failed charge |
| `amount` | number | yes | Outstanding amount of the failed charge |
| `currency` | string | — | Currency of the charge. If omitted, the merchant's country currency is used. |
| `plan_id` | string | — | Subscription plan ID |
| `plan_name` | string | — | Plan name, for the charge's concept |
| `frequency` | string (diario | semanal | quincenal | mensual | bimestral | trimestral | cuatrimestral | semestral | anual) | — | Plan frequency; if omitted it is queried from the plan or assumed monthly |
| `client_name` | string | — | Customer name |
| `client_email` | string | — | Customer email |
| `client_phone` | string | — | Customer phone in international format, for the WhatsApp link |
| `message` | string | — | Your own message for the customer; if omitted one is drafted |

**Returns**

`{ url, linkId, whatsapp_url, currency, amount, subscriber_id, frequency }`

Creates a one-time payment link for the subscriber to settle a failed recurring charge: url = payment link; whatsapp_url = WhatsApp link ready to send it; linkId = id of the created link.

### Links to bring several failed charges up to date [#tilopay-recurring-settle-batch]

- `tilopay_recurring_settle_batch`
- Access: Write

Batch sending (maximum 20) of links to bring failed recurring charges up to date. First call it WITHOUT confirming: it returns the summary (count, total, who has no phone) and a fingerprint. Show that summary AS IS and ask for an explicit yes. Only if the merchant answers yes, call it again with confirm=true and the SAME fingerprint. Use it when they ask to 'send it to everyone'; for a single customer use tilopay_recurring_settle_link.

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `confirm` | boolean | — | true only after the explicit yes to the summary |
| `fingerprint` | string | — | Fingerprint returned by the summary |
| `subscriber_ids` | array<string> | — | Limit to these subscribers; if omitted, all pending ones (max. 20) |

**Returns**

`{ ok, preview, fingerprint, count } | { ok, created, count }`

Preview: { ok, preview: true, fingerprint, count }. Execution (with confirm: true and the same fingerprint): { ok, created, count }.

### Settle a subscriber [#tilopay-recurring-mark-settled]

- `tilopay_recurring_mark_settled`
- Access: Write
- API operation: `POST /api/v1/editSuscriptorRepeat` — https://tilopay.com/en/developers/api/recurrentes/suscriptores/edit-suscriptor-plan

Marks the subscriber as up to date on their plan: it leaves them active and moves their expiration date to the next cycle. Use it when the pending charge was already paid by other means. If the payment was made with the tilopay_recurring_settle_link link, it is not needed: it updates by itself. Confirm with the merchant before running it.

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `subscriber_id` | string | yes | Subscriber ID |
| `plan_id` | string | — | Subscription plan ID |
| `frequency` | string (diario | semanal | quincenal | mensual | bimestral | trimestral | cuatrimestral | semestral | anual) | — | Plan frequency; if omitted it is queried from the plan or assumed monthly |
| `expire` | string | — | New expiration date YYYY-MM-DD; if omitted the next cycle is calculated |

**Returns**

`{ ok, expire, frequency }`

Moves the subscriber's due date forward according to the plan's frequency, to settle them after recovering a failed charge. expire = the new expiration date.