Adjustment Documents4

Auth1

Batch Enrollment1

Beneficiaries3

Beneficiary Accounts3

Boleto4

Campaigns9

Checkout Session5

Consulta de consentimientos1

Customer Collection Accounts3

Customer Portal10

Customers8

Débito Automático1

Debt Reconciliation Public1

Downloads2

Efectivo2

Electronic Signature2

Embed Tokens1

Facturación14

Forum9

Funding Account1

Intents de consentimiento1

Invoices9

PAC2

Payment Flows1

Payment Intents4

Payment Methods15

Payments9

Payout1

Payout Request Ingestion1

Payout Request Items1

Pix2

Pix Automático5

PlanOk3

POS Terminals5

Preauthorizations1

puntored5

Receipts2

Refunds3

Rendition Files2

Reports9

Risk flow validator executions1

Sequences1

Sin catalogar6

Subscriptions8

Transactions13

Transferencias 🇨🇱1

Transferencias 🇲🇽10

Validación de Cuenta Clabe4

Webhook Endpoints4

Webhooks1

Subscriptions

Crear Subscription

Changed on Nov 3, 2026

Crea una Subscription o actualiza la existente si coincide el identificador.

Se usa para dar de alta el cobro de un producto a un Customer. Es idempotente por (Account, product_id): si ya existe una Subscription con ese product_id, se actualiza y la respuesta es 200; si es nueva, se crea y la respuesta es 201. Para un cobro recurrente envía is_recurring=true junto con la configuración de recurrencia (frecuencia, intervalo, monto, día de vencimiento).

Límite de tasa: 20 solicitudes por segundo. Al superarlo, la API responde 429. Ver Límites de tasa.

post/subscriptions

Request

Base URL
https://api.trytoku.com
URL
https://api.trytoku.com/subscriptions
Auth
API key in header x-api-key

Headers

x-account-keystring

Llave de API de una Account, para operar sobre esa Account en lugar de la principal.

x-api-versionstring date

Versión del API para esta petición, como cualquier fecha YYYY-MM-DD. Fija el contrato de la respuesta; si se omite, se deriva de la fecha de creación de la organización.

Example:2026-10-08

Request body

amountnumber

Monto de cada Invoice de la Subscription, en la unidad mínima de la moneda. Debe ser menor que 1.000.000.000.000.000 (10^15).

creation_lead_daysinteger

Días de anticipación con los que se crea cada Invoice antes de su vencimiento. Se respeta como máximo: la creación nunca se adelanta al vencimiento del ciclo anterior. En una recurrencia mensual, creation_lead_days = due_day - 1 crea la Invoice el día 1 del mes de vencimiento, incluso cuando el vencimiento se ajusta a un mes más corto.

currency_code'CLP' | 'CLF' | 'MXN' | 'BRL' | 'USD'

Moneda, en código ISO 4217. Cubre las monedas de los países donde Toku opera —CLP (peso chileno), MXN (peso mexicano) y BRL (real)— más USD y CLF, la Unidad de Fomento chilena. La moneda determina cuántos decimales admiten los montos: CLP no admite decimales, MXN, BRL y USD admiten dos, y CLF cuatro.

customerstring required

Identificador público del Customer (cus_...) dueño de la Subscription.

due_dayinteger

Día de vencimiento de las Invoices. Para las frecuencias mensual y anual es el día del mes (1–31); para la semanal, el día de la semana (1 = lunes).

end_datestring date

Fecha hasta la cual la Subscription genera Invoices. Si es null, no tiene término.

frequency'daily' | 'weekly' | 'monthly' | 'yearly'

Frecuencia del ciclo de cobro.

intervalinteger

Número de unidades de frequency entre cada Invoice (por ejemplo, 2 con frecuencia mensual genera una Invoice cada dos meses).

is_recurringboolean

Indica si la Subscription es recurrente, es decir, si genera Invoices de forma periódica y automática. Los campos de recurrencia (currency_code, frequency, interval, due_day, amount, creation_lead_days, end_date y max_active_invoices) solo aplican cuando es true.

max_active_invoicesinteger

Número máximo de Invoices activas (impagas) que la recurrencia mantiene en simultáneo.

metadataobject

pac_mandate_idstring

Identificador del mandato PAC asociado a la Subscription.

product_idstring required

Identificador del producto de la organización asociado a la Subscription.

receipt_product_codestring

Example request

{
  "amount": 19990,
  "customer": "cus_ejC08yLqOWoFhVx4Fx42E3IR9X50tNx2",
  "due_day": 5,
  "interval": 1,
  "is_recurring": true,
  "product_id": "plan-oro-2025"
}

Response

La Subscription ya existía y fue actualizada.

amountnumber

Monto de las deudas generadas por la suscripción, expresado en la moneda indicada por currency_code.

currency_code'CLP' | 'CLF' | 'MXN' | 'BRL' | 'USD'

customerstring required

Identificador público del cliente dueño de la suscripción.

due_dayinteger

Día de vencimiento de las deudas. Para las frecuencias mensual y anual es el día del mes (1–31); para la semanal, el día de la semana (1 = lunes).

idstring required

Identificador público de la suscripción.

id_accountstring required

Identificador público de la cuenta a la que pertenece la suscripción.

is_recurringboolean

Indica si la suscripción es recurrente, es decir, si genera deudas de forma periódica y automática.

metadataobject

Campos adicionales definidos por la organización para la suscripción.

pac_mandate_idstring

Identificador del mandato PAC asociado a la suscripción.

product_idstring required

Identificador del producto de la organización asociado a la suscripción.

receipt_product_codestring

Código de producto usado al emitir el documento tributario de la suscripción.

Example response

{
  "customer": "cus_ejC08yLqOWoFhVx4Fx42E3IR9X50tNx2",
  "id": "sub_Y_EgOXMloD5-IJn6d9S2IxkNvp9p0iiP",
  "id_account": "acc_gzD0XoUTFxbUFcItpWOCqN686noSd9HQ"
}

Changes

Nov 3, 2026a6ef070075b1 Revision changes
- breaking
  request body became required
- breaking
  for the header request parameter x-account-key, default value was added
- breaking
  added to the request property allOf list
- breaking
  added to the request property allOf list
- breaking
  removed the enum value daily of the request property
- breaking
  removed the enum value monthly of the request property
- breaking
  removed the enum value weekly of the request property
- breaking
  removed the enum value yearly of the request property
- breaking
  the request property's minLength was increased from 0 to 1
- breaking
  the request property type changed from string to no type
- breaking
  the request property type changed from string to no type
- breaking
  the request property type changed from string to object, and format from json to no format
- breaking
  the response's body type changed from no type to object for status
- breaking
  the response's property type changed from integer to number for status
- breaking
  the response's property type changed from integer to number for status
- warning
  the request property's exclusiveMaximum was set to 1000000000000000.00
- warning
  the request property's maxLength was set to 8
- warning
  the request property's max was set to 31.00
- warning
  the request property's max was set to 52.00
- warning
  the request property's min was set to 0.00
- warning
  the request property's min was set to 0.00
- warning
  the request property's min was set to 1.00
- warning
  the request property's min was set to 1.00
- warning
  the request property's min was set to 1.00
- warning
  removed the optional property from the response with the status
- warning
  removed the optional property from the response with the status
- warning
  removed the optional property / from the response with the status
- warning
  removed the optional property / from the response with the status
- warning
  removed the optional property / from the response with the status
- warning
  removed the optional property / from the response with the status
- info
  api operation id crear-subscription removed and replaced with create_or_update_subscription
- info
  api tag Subscriptions added
- info
  added the new optional header request parameter x-api-version
- info
  the request property format was generalized from float to no format
- info
  the request property format was generalized from int32 to no format
- info
  removed subschema #1 subschema #2: Exception - due_day from the response body oneOf list for the response status
- info
  added the non-success response with the status
- info
  added the non-success response with the status
- info
  removed the non-success response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  the response property became required for the status
- info
  the response property became required for the status
- info
  the response property became required for the status
- info
  the response property became required for the status
- info
  the response property became required for the status
- info
  the response property became required for the status
- info
  the response's property default value changed from true to false for the status
- info
  the response's property default value changed from true to false for the status
- info
  the response's property default value 0 was removed for the status
- info
  the response's property default value 0 was removed for the status
- info
  the response's property default value 0 was removed for the status
- info
  the response's property default value 0 was removed for the status
- info
  the response's property pattern ^(?:[^ \n](?:[^\n]*[^ \n])?)?$ was added for the status
- info
  the response's property pattern ^(?:[^ \n](?:[^\n]*[^ \n])?)?$ was added for the status
- info
  added the required property to the response with the status
- info
  added the required property to the response with the status
- info
  added the required property to the response with the status
- info
  added the required property to the response with the status
- info
  added the required property to the response with the status
- info
  added the required property to the response with the status
- info
  added the required property to the response with the status

Operation history