Suscripciones del Merchant
Administra las suscripciones de un Merchant desde el Dashboard — inspecciona el ciclo de vida y el dunning, pausa o reanuda, cancela y cambia la oferta facturada.
Una suscripción es un acuerdo recurrente entre un cliente y un Merchant, facturado contra una oferta. Estos endpoints respaldan la pantalla de suscripciones del Dashboard: listar y abrir suscripciones, recorrer su historial de transiciones, pausar y reanudar, cancelar y trasladar una a una oferta distinta.
Cada cambio de estado se registra como una transición — el historial de solo anexado que responde qué cambió, cuándo y por qué. El dunning forma parte de ese ciclo de vida: una renovación fallida traslada la suscripción a un estado de reintento en lugar de terminarla de inmediato.
Estos endpoints alimentan la Tokeflow Dashboard UI. Están autenticados por sesión (JWT bearer) — el token proviene de iniciar sesión en el Dashboard, no de una clave de API sk_/pk_. Las solicitudes también llevan el header x-merchant-id que identifica al Merchant en contexto, y el usuario que ha iniciado sesión debe ser un miembro con acceso a él.
El objeto de suscripción
Devuelto por los endpoints de listado y recuperación de esta página.
| Field | Type | Description |
|---|---|---|
id | string | ID de la suscripción. |
merchant_id | string | ID del Merchant. |
customer_id | string | ID del cliente. |
customer_name | string | null | Nombre del cliente (resuelto). |
customer_email | string | null | Correo electrónico del cliente (resuelto). |
current_offer_id | string | ID de la oferta actual. |
offer_name | string | Nombre de la oferta (resuelto). |
product_id | string | ID del producto de la oferta actual. |
product_name | string | Nombre del producto (resuelto). |
product_family_id | string | ID de la familia de productos. |
billing_cycle | string | Uno de daily, biweekly, monthly, quarterly, half_yearly, yearly, custom, none. |
currency | string | Moneda ISO 4217. |
current_amount | number | Importe del cargo actual en unidades menores. |
current_period_start | string | (ISO 8601 UTC). |
current_period_end | string | (ISO 8601 UTC). |
next_billing_at | string | null | (ISO 8601 UTC). |
billing_anchor_day | number | null | — |
trial_start | string | null | (ISO 8601 UTC). |
trial_end | string | null | (ISO 8601 UTC). |
dunning_started_at | string | null | (ISO 8601 UTC). |
dunning_attempt_count | number | — |
dunning_next_retry_at | string | null | (ISO 8601 UTC). |
cycles_completed | number | — |
cycle_limit | number | null | — |
status | string | Uno de trialing, active, dunning, paused, cancelled, expired. |
cancel_at_period_end | boolean | — |
cancelled_at | string | null | (ISO 8601 UTC). |
cancellation_reason | string | null | — |
payment_instrument_id | string | — |
preferred_connector_id | string | null | — |
preferred_connector_name | string | Nombre del conector preferido (resuelto). |
initial_network_transaction_id | string | null | — |
preferred_installments | number | — |
created_at | string | (ISO 8601 UTC). |
updated_at | string | (ISO 8601 UTC). |
Endpoints
GET/api/v1/merchant/subscriptions
Merchant
Auth: Dashboard session (JWT bearer). Se requiere membresía del Merchant.
Lista las suscripciones del Merchant.
Parámetros de consulta
| Field | Type | Required | Description |
|---|---|---|---|
page | number | No | Número de página (indexado desde 1). Predeterminado 1, mín. 1. |
limit | number | No | Número de elementos por página. Predeterminado 20, mín. 1, máx. 100. |
customer_id | string | No | Filtra por ID del cliente |
status | string | No | Filtra por estado de la suscripción |
current_offer_id | string | No | Filtra por ID de la oferta actual |
product_family_id | string | No | Filtra por ID de la familia de productos |
Ejemplo de solicitud
curl -G https://api.tokeflow.com/api/v1/merchant/subscriptions \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-merchant-id: mrc_8a3f12d9" \
--data-urlencode "page=1" \
--data-urlencode "limit=20" \
--data-urlencode "customer_id=cust_123" \
--data-urlencode "status=active"Ejemplo de respuesta — 200
{
"data": [
{
"id": "sub_123",
"merchant_id": "mrc_123",
"customer_id": "cust_123",
"customer_name": "Acme Store",
"customer_email": "jane@example.com",
"current_offer_id": "off_123",
"offer_name": "Acme Store",
"product_id": "prd_9b1e6c05",
"product_name": "Acme Store",
"product_family_id": "pfam_123",
"billing_cycle": "monthly",
"currency": "BRL",
"current_amount": 4990,
"current_period_start": "2026-05-25T00:00:00Z",
"current_period_end": "2026-06-25T00:00:00Z",
"next_billing_at": "2026-06-25T00:00:00Z",
"billing_anchor_day": 25,
"trial_start": "2026-05-25T00:00:00Z",
"trial_end": "2026-06-08T00:00:00Z",
"dunning_started_at": "2026-01-15T12:30:00.000Z",
"dunning_attempt_count": 0,
"dunning_next_retry_at": "2026-01-15T12:30:00.000Z",
"cycles_completed": 3,
"cycle_limit": 12,
"status": "active",
"cancel_at_period_end": false
}
],
"meta": {
"page": 1,
"limit": 20,
"total": 42,
"total_pages": 3,
"has_next": true,
"has_prev": false
}
}GET/api/v1/merchant/subscriptions/:id
Merchant
Auth: Dashboard session (JWT bearer). Se requiere membresía del Merchant.
Recupera la suscripción por ID.
Parámetros de ruta
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Sí | — |
Ejemplo de solicitud
curl https://api.tokeflow.com/api/v1/merchant/subscriptions/obj_1a2b3c4d \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-merchant-id: mrc_8a3f12d9"Ejemplo de respuesta — 200
{
"id": "sub_123",
"merchant_id": "mrc_123",
"customer_id": "cust_123",
"customer_name": "Acme Store",
"customer_email": "jane@example.com",
"current_offer_id": "off_123",
"offer_name": "Acme Store",
"product_id": "prd_9b1e6c05",
"product_name": "Acme Store",
"product_family_id": "pfam_123",
"billing_cycle": "monthly",
"currency": "BRL",
"current_amount": 4990,
"current_period_start": "2026-05-25T00:00:00Z",
"current_period_end": "2026-06-25T00:00:00Z",
"next_billing_at": "2026-06-25T00:00:00Z",
"billing_anchor_day": 25,
"trial_start": "2026-05-25T00:00:00Z",
"trial_end": "2026-06-08T00:00:00Z",
"dunning_started_at": "2026-01-15T12:30:00.000Z",
"dunning_attempt_count": 0,
"dunning_next_retry_at": "2026-01-15T12:30:00.000Z",
"cycles_completed": 3,
"cycle_limit": 12,
"status": "active",
"cancel_at_period_end": false
}POST/api/v1/merchant/subscriptions/:id/cancel
Merchant
Auth: Dashboard session (JWT bearer). Se requiere membresía del Merchant.
Cancela la suscripción (atribución de admin).
Parámetros de ruta
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Sí | — |
Campos de la solicitud
| Field | Type | Required | Description |
|---|---|---|---|
at_period_end | boolean | Sí | Cuando es true, aplaza la cancelación a la próxima renovación; false cancela de inmediato. |
reason | string | No | Motivo opcional legible por humanos persistido en la suscripción. |
Ejemplo de solicitud
curl -X POST https://api.tokeflow.com/api/v1/merchant/subscriptions/obj_1a2b3c4d/cancel \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-merchant-id: mrc_8a3f12d9" \
-H "Content-Type: application/json" \
-d '{
"at_period_end": true,
"reason": "customer no longer needs the service"
}'Ejemplo de respuesta — 200
{
"id": "sub_123",
"merchant_id": "mrc_123",
"customer_id": "cust_123",
"customer_name": "Acme Store",
"customer_email": "jane@example.com",
"current_offer_id": "off_123",
"offer_name": "Acme Store",
"product_id": "prd_9b1e6c05",
"product_name": "Acme Store",
"product_family_id": "pfam_123",
"billing_cycle": "monthly",
"currency": "BRL",
"current_amount": 4990,
"current_period_start": "2026-05-25T00:00:00Z",
"current_period_end": "2026-06-25T00:00:00Z",
"next_billing_at": "2026-06-25T00:00:00Z",
"billing_anchor_day": 25,
"trial_start": "2026-05-25T00:00:00Z",
"trial_end": "2026-06-08T00:00:00Z",
"dunning_started_at": "2026-01-15T12:30:00.000Z",
"dunning_attempt_count": 0,
"dunning_next_retry_at": "2026-01-15T12:30:00.000Z",
"cycles_completed": 3,
"cycle_limit": 12,
"status": "active",
"cancel_at_period_end": false
}POST/api/v1/merchant/subscriptions/:id/change-offer
Merchant
Auth: Dashboard session (JWT bearer). Se requiere membresía del Merchant.
Cambia la oferta de la suscripción.
Parámetros de ruta
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Sí | — |
Campos de la solicitud
| Field | Type | Required | Description |
|---|---|---|---|
to_offer_id | string | Sí | ID de la oferta de destino. Debe pertenecer a la misma familia de productos que la oferta actual. |
Ejemplo de solicitud
curl -X POST https://api.tokeflow.com/api/v1/merchant/subscriptions/obj_1a2b3c4d/change-offer \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-merchant-id: mrc_8a3f12d9" \
-H "Content-Type: application/json" \
-d '{
"to_offer_id": "off_premium_monthly"
}'Ejemplo de respuesta — 200
{
"id": "sub_123",
"merchant_id": "mrc_123",
"customer_id": "cust_123",
"customer_name": "Acme Store",
"customer_email": "jane@example.com",
"current_offer_id": "off_123",
"offer_name": "Acme Store",
"product_id": "prd_9b1e6c05",
"product_name": "Acme Store",
"product_family_id": "pfam_123",
"billing_cycle": "monthly",
"currency": "BRL",
"current_amount": 4990,
"current_period_start": "2026-05-25T00:00:00Z",
"current_period_end": "2026-06-25T00:00:00Z",
"next_billing_at": "2026-06-25T00:00:00Z",
"billing_anchor_day": 25,
"trial_start": "2026-05-25T00:00:00Z",
"trial_end": "2026-06-08T00:00:00Z",
"dunning_started_at": "2026-01-15T12:30:00.000Z",
"dunning_attempt_count": 0,
"dunning_next_retry_at": "2026-01-15T12:30:00.000Z",
"cycles_completed": 3,
"cycle_limit": 12,
"status": "active",
"cancel_at_period_end": false
}POST/api/v1/merchant/subscriptions/:id/change-payment-instrument
Merchant
Auth: Dashboard session (JWT bearer). Se requiere membresía del Merchant.
Cambia el instrumento de pago de la suscripción.
Parámetros de ruta
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Sí | — |
Campos de la solicitud
| Field | Type | Required | Description |
|---|---|---|---|
payment_instrument_id | string | Sí | ID del instrumento de pago a facturar de aquí en adelante. |
Ejemplo de solicitud
curl -X POST https://api.tokeflow.com/api/v1/merchant/subscriptions/obj_1a2b3c4d/change-payment-instrument \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-merchant-id: mrc_8a3f12d9" \
-H "Content-Type: application/json" \
-d '{
"payment_instrument_id": "pi_123"
}'Ejemplo de respuesta — 200
{
"id": "sub_123",
"merchant_id": "mrc_123",
"customer_id": "cust_123",
"customer_name": "Acme Store",
"customer_email": "jane@example.com",
"current_offer_id": "off_123",
"offer_name": "Acme Store",
"product_id": "prd_9b1e6c05",
"product_name": "Acme Store",
"product_family_id": "pfam_123",
"billing_cycle": "monthly",
"currency": "BRL",
"current_amount": 4990,
"current_period_start": "2026-05-25T00:00:00Z",
"current_period_end": "2026-06-25T00:00:00Z",
"next_billing_at": "2026-06-25T00:00:00Z",
"billing_anchor_day": 25,
"trial_start": "2026-05-25T00:00:00Z",
"trial_end": "2026-06-08T00:00:00Z",
"dunning_started_at": "2026-01-15T12:30:00.000Z",
"dunning_attempt_count": 0,
"dunning_next_retry_at": "2026-01-15T12:30:00.000Z",
"cycles_completed": 3,
"cycle_limit": 12,
"status": "active",
"cancel_at_period_end": false
}POST/api/v1/merchant/subscriptions/:id/pause
Merchant
Auth: Dashboard session (JWT bearer). Se requiere membresía del Merchant.
Pausa la suscripción.
Parámetros de ruta
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Sí | — |
Campos de la solicitud
| Field | Type | Required | Description |
|---|---|---|---|
reason | string | No | Motivo opcional legible por humanos persistido en la transición. |
Ejemplo de solicitud
curl -X POST https://api.tokeflow.com/api/v1/merchant/subscriptions/obj_1a2b3c4d/pause \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-merchant-id: mrc_8a3f12d9" \
-H "Content-Type: application/json" \
-d '{
"reason": "customer travelling for 6 weeks"
}'Ejemplo de respuesta — 200
{
"id": "sub_123",
"merchant_id": "mrc_123",
"customer_id": "cust_123",
"customer_name": "Acme Store",
"customer_email": "jane@example.com",
"current_offer_id": "off_123",
"offer_name": "Acme Store",
"product_id": "prd_9b1e6c05",
"product_name": "Acme Store",
"product_family_id": "pfam_123",
"billing_cycle": "monthly",
"currency": "BRL",
"current_amount": 4990,
"current_period_start": "2026-05-25T00:00:00Z",
"current_period_end": "2026-06-25T00:00:00Z",
"next_billing_at": "2026-06-25T00:00:00Z",
"billing_anchor_day": 25,
"trial_start": "2026-05-25T00:00:00Z",
"trial_end": "2026-06-08T00:00:00Z",
"dunning_started_at": "2026-01-15T12:30:00.000Z",
"dunning_attempt_count": 0,
"dunning_next_retry_at": "2026-01-15T12:30:00.000Z",
"cycles_completed": 3,
"cycle_limit": 12,
"status": "active",
"cancel_at_period_end": false
}POST/api/v1/merchant/subscriptions/:id/resume
Merchant
Auth: Dashboard session (JWT bearer). Se requiere membresía del Merchant.
Reanuda la suscripción.
Parámetros de ruta
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Sí | — |
Ejemplo de solicitud
curl -X POST https://api.tokeflow.com/api/v1/merchant/subscriptions/obj_1a2b3c4d/resume \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-merchant-id: mrc_8a3f12d9"Ejemplo de respuesta — 200
{
"id": "sub_123",
"merchant_id": "mrc_123",
"customer_id": "cust_123",
"customer_name": "Acme Store",
"customer_email": "jane@example.com",
"current_offer_id": "off_123",
"offer_name": "Acme Store",
"product_id": "prd_9b1e6c05",
"product_name": "Acme Store",
"product_family_id": "pfam_123",
"billing_cycle": "monthly",
"currency": "BRL",
"current_amount": 4990,
"current_period_start": "2026-05-25T00:00:00Z",
"current_period_end": "2026-06-25T00:00:00Z",
"next_billing_at": "2026-06-25T00:00:00Z",
"billing_anchor_day": 25,
"trial_start": "2026-05-25T00:00:00Z",
"trial_end": "2026-06-08T00:00:00Z",
"dunning_started_at": "2026-01-15T12:30:00.000Z",
"dunning_attempt_count": 0,
"dunning_next_retry_at": "2026-01-15T12:30:00.000Z",
"cycles_completed": 3,
"cycle_limit": 12,
"status": "active",
"cancel_at_period_end": false
}POST/api/v1/merchant/subscriptions/:id/reactivate
Merchant
Auth: Dashboard session (JWT bearer). Se requiere membresía del Merchant.
Cancela una cancelación programada y mantiene la suscripción en su plan actual. La reactivación vuelve a poner cancel_at_period_end en false y registra una transición reactivation; no cambia la oferta, el importe ni las fechas de facturación. Disponible para una suscripción viva (active, trialing o dunning); una suscripción paused debe reanudarse (resume), y una terminal se rechaza (409).
Parámetros de ruta
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | — |
Ejemplo de solicitud
curl -X POST https://api.tokeflow.com/api/v1/merchant/subscriptions/obj_1a2b3c4d/reactivate \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-merchant-id: mrc_8a3f12d9"Ejemplo de respuesta — 200
{
"id": "sub_123",
"merchant_id": "mrc_123",
"customer_id": "cust_123",
"customer_name": "Acme Store",
"customer_email": "jane@example.com",
"current_offer_id": "off_123",
"offer_name": "Acme Store",
"product_id": "prd_9b1e6c05",
"product_name": "Acme Store",
"product_family_id": "pfam_123",
"billing_cycle": "monthly",
"currency": "BRL",
"current_amount": 4990,
"current_period_start": "2026-05-25T00:00:00Z",
"current_period_end": "2026-06-25T00:00:00Z",
"next_billing_at": "2026-06-25T00:00:00Z",
"billing_anchor_day": 25,
"trial_start": "2026-05-25T00:00:00Z",
"trial_end": "2026-06-08T00:00:00Z",
"dunning_started_at": "2026-01-15T12:30:00.000Z",
"dunning_attempt_count": 0,
"dunning_next_retry_at": "2026-01-15T12:30:00.000Z",
"cycles_completed": 3,
"cycle_limit": 12,
"status": "active",
"cancel_at_period_end": false
}GET/api/v1/merchant/subscriptions/:id/transitions
Merchant
Auth: Dashboard session (JWT bearer). Se requiere membresía del Merchant.
Lista el historial de transiciones de la suscripción.
Parámetros de ruta
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Sí | — |
Ejemplo de solicitud
curl https://api.tokeflow.com/api/v1/merchant/subscriptions/obj_1a2b3c4d/transitions \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-merchant-id: mrc_8a3f12d9"Ejemplo de respuesta — 200
{
"data": [
{
"id": "sbt_123",
"subscription_id": "sub_123",
"transition_type": "creation",
"from_offer_id": "off_basic_monthly",
"to_offer_id": "off_premium_monthly",
"from_status": "trialing",
"to_status": "trialing",
"triggered_by": "customer",
"order_id": "ord_123",
"reason": "requested_by_customer",
"metadata": {},
"created_at": "2026-01-15T12:30:00.000Z"
}
]
}Errores
Los errores usan el envoltorio estándar. Los casos más comunes aquí:
| HTTP | Significado |
|---|---|
400 | Parámetros inválidos o un estado que no permite esta operación. |
401 | Token de sesión del Dashboard ausente, expirado o inválido. |
403 | Autenticado, pero el usuario que ha iniciado sesión carece de acceso a esta entidad. |
404 | El registro no existe o no es visible para esta entidad. |