# API · Create recurring plan

> Recurring plan creation: frequencies, free trial, modalities and webhooks.

- kind: api-operation
- status: stable
- api_version: v1
- last_verified: 2026-10-22
- url: https://tilopay.com/en/developers/api/recurrentes/planes/create-plan

```http
POST /api/v1/createPlanRepeat
```

## What it does [#que-hace]

Creates a subscription plan: charge frequency, currency, trial period, modalities and webhooks.

## Authentication [#autenticacion]

Requires the API bearer token in the `Authorization` header — see [authentication](/en/developers/api/autenticacion).

## Parameters [#parametros]

<Param id="create-plan-parametro-key" name="key" type="string" required>
Tilopay integration key.
</Param>

<Param id="create-plan-parametro-title" name="title" type="string" required>
Recurring plan title.
</Param>

<Param id="create-plan-parametro-description" name="description" type="string">
Plan description.
</Param>

<Param id="create-plan-parametro-frecuency" name="frecuency" type="integer">
Charge frequency.

| Code | Value |
| --- | --- |
| 1 | Daily |
| 2 | Weekly |
| 3 | Monthly |
| 4 | Yearly |
| 5 | Fortnightly |
| 6 | Every two months |
| 7 | Quarterly |
| 8 | Every four months |
| 9 | Every six months |
</Param>

<Param id="create-plan-parametro-currency" name="currency" type="string" required>
Currency code in ISO 4217 format.
</Param>

<Param id="create-plan-parametro-first-amount" name="first_amount" type="integer" required>
Initial payment amount.
</Param>

<Param id="create-plan-parametro-trial" name="trial" type="integer" required>
Enables the free trial period: 0 no, 1 yes.
</Param>

<Param id="create-plan-parametro-trial-days" name="trial_days" type="integer" required>
Days of the free trial period.
</Param>

<Param id="create-plan-parametro-attempts" name="attempts" type="integer" required>
Number of retries for failed charges.
</Param>

<Param id="create-plan-parametro-modality" name="modality" type="array" required>
Array of plan modalities.
</Param>

<Param id="create-plan-parametro-thanks-url" name="thanks_url" type="string">
Optional field. The merchant's own thank-you URL; it must support the **GET** method.
</Param>

<Param id="create-plan-parametro-webhook-subscribe" name="webhook_subscribe" type="string">
Optional field. Webhook URL, over **POST**, that receives the callback in the request body when a customer successfully takes out a subscription. Example of the data sent: `{'id_plan' : 1, 'email' : 'email@email.com', 'modality' : 'ModalityName', 'amount' : 25, 'frequency' : '', 'coupon' : '5HT5W8YT', 'free_trial' : 1, 'next_payment_date' : '2023-02-25'}`
</Param>

<Param id="create-plan-parametro-webhook-payment" name="webhook_payment" type="string">
Optional field. Webhook URL, over **POST**, that receives the callback in the request body when the customer is charged successfully. Example of the data sent: `{'id_plan' : 1, 'email' : 'email@email.com', 'amount' : 25, 'auth' : '123456', 'orderNumber' : 'PRE123456'}`
</Param>

<Param id="create-plan-parametro-webhook-rejected" name="webhook_rejected" type="string">
Optional field. Webhook URL, over **POST**, that receives the callback in the request body when a payment fails. Example of the data sent: `{'id_plan' : 1, 'email' : 'email@email.com', 'amount' : 25}`
</Param>

<Param id="create-plan-parametro-webhook-unsubscribe" name="webhook_unsubscribe" type="string">
Optional field. Webhook URL, over **POST**, that receives the callback in the request body when a customer cancels the subscription to one of their plans. Example of the data sent: `{'id_plan' : 1, 'email' : 'email@email.com', 'expire' : '2023-02-25'}`
</Param>

<Param id="create-plan-parametro-webhook-reactive" name="webhook_reactive" type="string">
Optional field. Webhook URL, over **POST**, that receives the callback in the request body when a customer reactivates the subscription to one of their plans. Example of the data sent: `{'id_plan' : 1, 'email' : 'email@email.com', 'next_payment_date' : '2023-02-25'}`
</Param>

<Param id="create-plan-parametro-end-at" name="end_at" type="string">
End date of the recurring plan, `d-m-Y` format (for example 25-09-2022). When the plan has no end date, send it empty.
</Param>

<Param id="create-plan-parametro-notify" name="notify" type="integer">
Set to 1 it adds the `notify_detail` and `notify_note` text to the notification email. Set to 0 it adds neither.
</Param>

<Param id="create-plan-parametro-notify-detail-es" name="notify_detail_es" type="string">
Detail text in Spanish. Optional when `notify` is 0.
</Param>

<Param id="create-plan-parametro-notify-detail-en" name="notify_detail_en" type="string">
Detail text in English. Optional when `notify` is 0.
</Param>

<Param id="create-plan-parametro-notify-note-es" name="notify_note_es" type="string">
Notes text in Spanish. Optional when `notify` is 0.
</Param>

<Param id="create-plan-parametro-notify-note-en" name="notify_note_en" type="string">
Notes text in English. Optional when `notify` is 0.
</Param>

## Request example [#request]

The `<...>` values are placeholders: replace them with your own credentials and data.

```json
{
  "key": "<api_key>",
  "title": "Plan title",
  "description": "Plan description",
  "frecuency": 1,
  "currency": "USD",
  "first_amount": 0,
  "trial": 0,
  "trial_days": 0,
  "attempts": 1,
  "modality": [
    {
      "title": "Basic",
      "amount": 10
    },
    {
      "title": "Premium",
      "amount": 30
    }
  ],
  "thanks_url": "",
  "webhook_subscribe": "",
  "webhook_payment": "",
  "webhook_rejected": "",
  "webhook_unsubscribe": "",
  "webhook_reactive": "",
  "end_at": "25-10-2023",
  "notify": 0,
  "notify_detail_es": "",
  "notify_detail_en": "",
  "notify_note_es": "",
  "notify_note_en": ""
}
```

## Response [#respuesta]

<Param id="create-plan-respuesta-url" name="url" type="string">
Plan URL on `https://tp.cr` or `https://app.tilopay.com`.
</Param>

```json
{
  "type": "200",
  "status": 1,
  "message": "Success",
  "id": 624,
  "url": "https://app.tilopay.com/link/TmpJMHwx"
}
```

To interpret a response that is not a success, see [how to read an error response](/en/developers/api/procesos-operativos/errors).