Suscripciones

Una suscripción (Subscription) es un cobro recurrente que genera automáticamente una serie de deudas, una por ciclo. Tú defines qué cobrar (monto, frecuencia, deudor y duración) y TapiPay genera las cuotas y resuelve toda la complejidad interna por ti. Cuándo usarla: cobros que se repiten en el tiempo (mensualidades, cuotas de crédito, planes periódicos). Para un cargo único usa una deuda; para cobrar sin deudor conocido, una liga de pago.

Generación de cuotas por adelantado

Al crear la suscripción, TapiPay calcula las fechas de todos los ciclos y genera las deudas por adelantado (no hay un proceso que cree una cuota por mes). La generación de esas deudas ocurre de forma asíncrona: la suscripción se devuelve en estado ACTIVE apenas el cálculo y el encolado terminan correctamente.

Si la generación de las deudas falla, la suscripción se revierte automáticamente para que puedas reintentar con el mismo externalSubscriptionId sin duplicar cobros.

Crear una suscripción

curl --request POST \
  --url 'https://tapipay-facade.homo.tapila.cloud/subscriptions' \
  --header 'x-api-key: TU_API_KEY' \
  --header 'x-authorization-token: TU_TOKEN_TAPI' \
  --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": "Plan Gimnasio"
  }'

Campos principales

string

requerido

Llave natural de la suscripción. Única por organización. Si la repites, la API responde 409 RESOURCE_CONFLICT. Ver Idempotencia.

string | object

requerido

El deudor. Uno de los dos es obligatorio y son excluyentes (no envíes ambos), igual que en una deuda. En v1 cada suscripción tiene exactamente un deudor.

number

requerido

Monto por ciclo en pesos, con hasta 2 decimales (mínimo 0.01).

string

requerido

Unidad del intervalo: day, week, month o year, en minúsculas exactas. Es case-sensitive: MONTH devuelve 400.

integer

requerido

Cantidad de unidades por ciclo, entero mayor o igual a 1. Por ejemplo, intervalUnit: "month" + intervalCount: 3 es trimestral.

string

requerido

Fecha de inicio en formato YYYY-MM-DD (fecha de calendario válida).

string

requerido

Nombre del producto que se cobra. Si el nombre ya existe en tu organización, se reutiliza; si no, el producto se crea en línea. Ver Creación en línea.

integer

Cantidad de ciclos a generar, de 1 a 520. Excluyente con endDate.

string

Fecha de fin (YYYY-MM-DD), posterior a startDate. Excluyente con totalCycles.

object

Override del día de cobro: { day, month? }. Solo es válido con intervalos month o year, y month (de 1 a 12) solo con year. Ver más abajo.

boolean

predeterminado:"false"

Si es true, el deudor debe pagar las cuotas en orden cronológico.

boolean

predeterminado:"true"

Si es false, las cuotas no se pueden pagar después de su vencimiento.

boolean

predeterminado:"true"

Habilita pagos parciales en las deudas generadas.

boolean

predeterminado:"false"

Solicita la domiciliación de las cuotas. autopay: true y paymentMethods son excluyentes: enviar ambos devuelve 400.

string[]

Medios de pago habilitados para las cuotas. Excluyente con autopay: true. Ver Medios de pago.

string

Descripción de la suscripción. Debe ser string (si no, 400).

object

Datos propios de tu sistema. Debe ser un objeto plano (un escalar devuelve 400) y no puede usar claves reservadas (description, paymentMethods, productName, externalProductId, debtExpirationDate, overduePayment, allowPartialPayments, recurringDebt, debtReference); si no, 400. Se guarda en las deudas generadas.

Reglas de validación

Los booleanos (autopay, allowOverduePayment, allowPartialPayments, enforcePaymentOrder) solo aceptan true o false literal: "true", 1, etc. devuelven 400 con details[].
Los campos no declarados se ignoran.
Si la programación (intervalUnit, intervalCount, startDate, totalCycles, endDate, billingDay) es inválida, la API responde 400 y no se crea nada: ni la suscripción, ni el producto, ni el contacto en línea.

Ver Convenciones de la API para las reglas comunes a todos los endpoints.

Idempotencia

La creación de suscripciones no usa el header Idempotency-Key. La llave de idempotencia es externalSubscriptionId: repetirla devuelve 409 RESOURCE_CONFLICT y no se crea una suscripción nueva. Las deudas generadas usan externalRequestId = <externalSubscriptionId>-cycle-<n>, con n desde 0 (la deuda del primer ciclo es -cycle-0).

Frecuencias con `intervalUnit` + `intervalCount`

Frecuencia	`intervalUnit`	`intervalCount`
Semanal	`week`	`1`
Quincenal	`week`	`2`
Mensual	`month`	`1`
Trimestral	`month`	`3`
Cada 45 días	`day`	`45`
Anual	`year`	`1`

Día de cobro (`billingDay`)

Por defecto, el día de cobro se infiere del startDate (modelo aniversario): si la suscripción inicia el día 15, todos los cobros caen el 15. El override billingDay desacopla el día de cobro del startDate. En la respuesta, scheduling.billingDay siempre muestra el día de cobro efectivo: si no lo enviaste, se infiere del startDate como { day } para month y { day, month } para year. Para day y week es null.

billingDay solo es válido para intervalos month o year. El subcampo month solo aplica a intervalos year.

Fin de mes: si el día configurado supera el último día del mes (por ejemplo, 31 en febrero), el cobro se realiza el último día del mes; el mes siguiente vuelve al día original.

Ciclo 1: 2026-01-31   (enero tiene 31)
Ciclo 2: 2026-02-28   (febrero tiene 28 en 2026)
Ciclo 3: 2026-03-31   (vuelve al día original)
Ciclo 4: 2026-04-30   (abril tiene 30)

Duración indefinida

Si no envías totalCycles ni endDate, la suscripción queda ACTIVE y se genera solo la deuda del primer ciclo (para no generar cobros sin límite). Define totalCycles o endDate cuando quieras generar todas las cuotas por adelantado.

La respuesta

Los datos de programación viajan anidados en el objeto scheduling.

{
  "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": "Plan Gimnasio",
    "additionalData": { "source": "crm" },
    "contact": {
      "contactId": "con_9aL3kP2m",
      "externalClientId": "CLI-00042",
      "createdInline": false
    },
    "product": {
      "productId": "prd_42",
      "name": "Plan Gimnasio",
      "active": true,
      "createdInline": true
    },
    "createdAt": "2026-06-03T18:15:00.000Z",
    "updatedAt": "2026-06-03T18:15:00.000Z"
  },
  "requestId": "req_a1b2c3d4"
}

description, additionalData y paymentMethods solo vienen si tienen valor.
scheduling.totalCycles y scheduling.endDate siempre vienen, con null si no aplican.
paymentUrl es la URL del portal compartida por todas las cuotas. Es una URL opaca: no la parsees ni la construyas a mano. Para abrir una cuota específica usa el paymentUrl de cada deuda en GET /subscriptions/{id}/debts.
contact.contactId siempre trae el prefijo con_, también cuando el contacto se creó en línea con contactData.
createdInline de contact y product indica si se crearon en línea al crear la suscripción, y se conserva en las lecturas posteriores.

Ciclo de vida

Estado	Significado
`PROCESSING`	Estado transitorio mientras se generan las deudas al crear la suscripción.
`ACTIVE`	Activa. Las deudas de los ciclos ya fueron generadas.
`PAUSED`	Pausada manualmente. Puede reanudarse.
`CANCELLED`	Cancelada manualmente. Estado final.
`ENDED`	Completó su programación: ya pasó el `endDate` o el vencimiento del último ciclo de `totalCycles`. Estado final. Una suscripción `ACTIVE` cuya fecha de fin ya pasó se devuelve como `ENDED`.

Cada deuda generada por la suscripción tiene su propio ciclo de vida (PENDING, PAID, etc.). Pausar o cancelar la suscripción cancela sus deudas pendientes. Ver Pausar, reanudar y cancelar y Deudas.

Pago en orden (`enforcePaymentOrder`)

Con enforcePaymentOrder: true, el deudor no puede pagar una cuota si hay cuotas anteriores impagas. Intentarlo devuelve 422 BUSINESS_RULE_VIOLATION. Debe saldarlas en orden cronológico.

Listar suscripciones

GET /subscriptions devuelve tus suscripciones ordenadas por externalSubscriptionId descendente, con la paginación estándar (page, limit). Filtros:

Parámetro	Descripción
`status`	`PROCESSING`, `ACTIVE`, `PAUSED`, `CANCELLED` o `ENDED`. Es case-sensitive: un valor inválido devuelve `400` (`Invalid status filter ...`). Vacío se ignora.
`externalClientId`	Deudor, match exacto. Se combina con `status` (ambos deben cumplirse). Vacío o en blanco devuelve `400 INVALID_REQUEST`.

Sin resultados, la respuesta es 200 con data: []. meta.total y meta.hasMore cuentan solo lo filtrado.

Con el filtro status, meta.total puede ser aproximado: el filtro se vuelve a aplicar después de calcular el estado real (por ejemplo, una suscripción ACTIVE vencida sale como ENDED).

Actualizar una suscripción

PATCH /subscriptions/{id} modifica amount, description, enforcePaymentOrder, allowOverduePayment, autopay, paymentMethods y additionalData.

Solo amount se aplica también a las deudas ya generadas, conservando sus pagos parciales y su allowPartialPayments. Las deudas canceladas no se modifican. El resto de los campos solo cambia la suscripción.
additionalData es un objeto plano con las mismas reglas que en la creación.
Un body vacío o un campo no modificable devuelve 400. Los tipos y valores inválidos (amount no numérico, booleanos no literales, paymentMethods fuera del enum, autopay: true junto con paymentMethods) devuelven 400 con details[].
companyCode en el body se toma como contexto y no como campo a modificar.
Una suscripción CANCELLED o ENDED no se puede modificar: 422 BUSINESS_RULE_VIOLATION.
Si la suscripción se actualiza pero falla la actualización de alguna de sus deudas ya generadas, la API responde 207 con el envelope de error: error.code es PARTIAL_UPDATE y error.message indica cuántas deudas no se sincronizaron (sin details). La suscripción sí quedó actualizada.

Pausar, reanudar y cancelar

Acción	Efecto	Errores
`POST /subscriptions/{id}/pause`	Pausa los cobros y cancela todas las deudas pendientes generadas. Pausar una suscripción ya pausada devuelve `200` sin cambios.	`422` si el estado no permite pausar.
`POST /subscriptions/{id}/resume`	Solo desde `PAUSED`. Genera deudas nuevas con `externalRequestId = <externalSubscriptionId>-resume-<n>-cycle-<m>`, así que sus `debtId` son distintos de los originales.	`422` desde cualquier otro estado (no es idempotente).
`POST /subscriptions/{id}/cancel`	Cancela la suscripción y sus deudas pendientes. Cancelar una suscripción ya cancelada devuelve `200`.	`422 BUSINESS_RULE_VIOLATION` desde `ENDED`.

Las deudas canceladas al pausar o cancelar dejan de listarse en GET /subscriptions/{id}/debts y en GET /debts, pero se siguen leyendo con GET /debts/{id}.

Deudas de la suscripción

GET /subscriptions/{id}/debts devuelve las deudas generadas, con la paginación estándar.

El externalRequestId de cada deuda es <externalSubscriptionId>-cycle-<n> (con n desde 0), o <externalSubscriptionId>-resume-<n>-cycle-<m> para las generadas al reanudar.
No incluye deudas canceladas (igual que GET /debts) y meta.total cuenta solo las listadas.
El paymentUrl de cada deuda es una URL opaca que abre directamente esa cuota.

Endpoints

Método	Ruta	Descripción
`POST`	`/subscriptions`	Crear una suscripción.
`GET`	`/subscriptions/{id}`	Consultar una suscripción.
`GET`	`/subscriptions`	Listar suscripciones.
`PATCH`	`/subscriptions/{id}`	Actualizar campos editables (`amount`, `description`, `enforcePaymentOrder`, `allowOverduePayment`, `autopay`, `paymentMethods`, `additionalData`).
`POST`	`/subscriptions/{id}/pause`	Pausar.
`POST`	`/subscriptions/{id}/resume`	Reanudar.
`POST`	`/subscriptions/{id}/cancel`	Cancelar.
`GET`	`/subscriptions/{id}/debts`	Listar las deudas generadas.

Pruébalo en el API Reference

Explora cada endpoint con su playground interactivo.

Empieza aquí

Novedades

Conceptos

Recursos

Portal de pagos

Webhooks

Generación de cuotas por adelantado

Crear una suscripción

Campos principales

Reglas de validación

Idempotencia

Frecuencias con `intervalUnit` + `intervalCount`

Día de cobro (`billingDay`)

Duración indefinida

La respuesta

Ciclo de vida

Pago en orden (`enforcePaymentOrder`)

Listar suscripciones

Actualizar una suscripción

Pausar, reanudar y cancelar

Deudas de la suscripción

Endpoints

Pruébalo en el API Reference

​Generación de cuotas por adelantado

​Crear una suscripción

​Campos principales

​Reglas de validación

​Idempotencia

​Frecuencias con intervalUnit + intervalCount

​Día de cobro (billingDay)

​Duración indefinida

​La respuesta

​Ciclo de vida

​Pago en orden (enforcePaymentOrder)

​Listar suscripciones

​Actualizar una suscripción

​Pausar, reanudar y cancelar

​Deudas de la suscripción

​Endpoints

Pruébalo en el API Reference

Generación de cuotas por adelantado

Crear una suscripción

Campos principales

Reglas de validación

Idempotencia

Frecuencias con `intervalUnit` + `intervalCount`

Día de cobro (`billingDay`)

Duración indefinida

La respuesta

Ciclo de vida

Pago en orden (`enforcePaymentOrder`)

Listar suscripciones

Actualizar una suscripción

Pausar, reanudar y cancelar

Deudas de la suscripción

Endpoints