Suscripciones del Customer Portal

Permite que un cliente vea y gestione sus propias suscripciones en el portal — ver planes, cambiar de plan, agregar una tarjeta durante el dunning y cancelar.

Estos endpoints permiten que un cliente con sesión iniciada gestione sus propias suscripciones: listarlas, abrir una, ver a qué planes puede cambiar, agregar una tarjeta mientras una renovación falla (dunning) y cancelar.

Las acciones aquí están limitadas por la configuración del portal del Merchant — un Merchant elige si los clientes pueden cambiar de plan o cancelar por su cuenta. Todo está delimitado al cliente propietario de la sesión; un cliente nunca puede ver las suscripciones de otro.

Estos endpoints impulsan el Customer Portal — la superficie de self-service que usan tus clientes finales, bajo tu marca. Se autentican mediante una cookie de sesión del portal, establecida a través del flujo de magic-link (solicitar un enlace y luego verificar el token), y no mediante una clave de API. Consulta Sesiones y configuración.

El objeto de la suscripción

Devuelto por los endpoints de listado y recuperación de esta página.

Field	Type	Description
`id`	string	—
`status`	string	Uno de `trialing`, `active`, `dunning`, `paused`, `cancelled`, `expired`.
`current_offer_id`	string	—
`billing_cycle`	string	Uno de `daily`, `biweekly`, `monthly`, `quarterly`, `half_yearly`, `yearly`, `custom`, `none`.
`currency`	string	—
`current_amount`	number	Importe actual en unidades menores.
`current_period_start`	string \| null	(ISO 8601 UTC).
`current_period_end`	string \| null	(ISO 8601 UTC).
`next_billing_at`	string \| null	(ISO 8601 UTC).
`cancel_at_period_end`	boolean	—
`cancelled_at`	string \| null	(ISO 8601 UTC).
`cycles_completed`	number	Número de ciclos de cobro completados.
`cycle_limit`	number \| null	Máximo de cobros; null = continuo.
`trial_start`	string \| null	(ISO 8601 UTC).
`trial_end`	string \| null	(ISO 8601 UTC).
`preferred_installments`	number	—
`dunning_next_retry_at`	string \| null	Próximo reintento de dunning (si está en dunning). (ISO 8601 UTC).
`offer_name`	string \| null	—
`product_name`	string \| null	—
`card_brand`	string \| null	—
`card_last4`	string \| null	—
`card_exp_month`	number \| null	—
`card_exp_year`	number \| null	—

Endpoints

GET`/api/v1/portal/subscriptions`

Autenticación: Customer Portal session (cookie establecida por el flujo de magic-link).

Lista las suscripciones del cliente.

Ejemplo de solicitud

curl https://api.tokeflow.com/api/v1/portal/subscriptions \
  -H "Cookie: tf_portal_session=…"

GET`/api/v1/portal/subscriptions/:id`

Autenticación: Customer Portal session (cookie establecida por el flujo de magic-link).

Obtiene una suscripción.

Parámetros de ruta

Field	Type	Required	Description
`id`	string	Sí	—

Ejemplo de solicitud

curl https://api.tokeflow.com/api/v1/portal/subscriptions/obj_1a2b3c4d \
  -H "Cookie: tf_portal_session=…"

Ejemplo de respuesta — 200

{
  "id": "sub_123",
  "status": "trialing",
  "current_offer_id": "off_123",
  "billing_cycle": "daily",
  "currency": "BRL",
  "current_amount": 15000,
  "current_period_start": "2026-01-15T12:30:00.000Z",
  "current_period_end": "2026-01-15T12:30:00.000Z",
  "next_billing_at": "2026-01-15T12:30:00.000Z",
  "cancel_at_period_end": true,
  "cancelled_at": "2026-01-15T12:30:00.000Z",
  "cycles_completed": 1,
  "cycle_limit": 1,
  "trial_start": "2026-01-15T12:30:00.000Z",
  "trial_end": "2026-01-15T12:30:00.000Z",
  "preferred_installments": 1,
  "dunning_next_retry_at": "2026-01-15T12:30:00.000Z",
  "offer_name": "Premium Monthly",
  "product_name": "Streaming Plans",
  "card_brand": "visa",
  "card_last4": "4242",
  "card_exp_month": 12,
  "card_exp_year": 2027
}

POST`/api/v1/portal/subscriptions/:id/add-card`

Autenticación: Customer Portal session (cookie establecida por el flujo de magic-link).

Agrega una tarjeta durante el dunning.

Parámetros de ruta

Field	Type	Required	Description
`id`	string	Sí	—

Campos de la solicitud

Field	Type	Required	Description
`card_ciphertext_id`	string	Sí	La referencia de tarjeta cifrada de un solo uso (`tok_…`) de la nueva tarjeta, proveniente del Bridge SDK.

Ejemplo de solicitud

curl -X POST https://api.tokeflow.com/api/v1/portal/subscriptions/obj_1a2b3c4d/add-card \
  -H "Cookie: tf_portal_session=…" \
  -H "Content-Type: application/json" \
  -d '{
    "card_ciphertext_id": "tok_8f3c2a1b9d4e"
  }'

Ejemplo de respuesta — 200

{
  "id": "sub_123",
  "status": "trialing",
  "current_offer_id": "off_123",
  "billing_cycle": "daily",
  "currency": "BRL",
  "current_amount": 15000,
  "current_period_start": "2026-01-15T12:30:00.000Z",
  "current_period_end": "2026-01-15T12:30:00.000Z",
  "next_billing_at": "2026-01-15T12:30:00.000Z",
  "cancel_at_period_end": true,
  "cancelled_at": "2026-01-15T12:30:00.000Z",
  "cycles_completed": 1,
  "cycle_limit": 1,
  "trial_start": "2026-01-15T12:30:00.000Z",
  "trial_end": "2026-01-15T12:30:00.000Z",
  "preferred_installments": 1,
  "dunning_next_retry_at": "2026-01-15T12:30:00.000Z",
  "offer_name": "Premium Monthly",
  "product_name": "Streaming Plans",
  "card_brand": "visa",
  "card_last4": "4242",
  "card_exp_month": 12,
  "card_exp_year": 2027
}

GET`/api/v1/portal/subscriptions/:id/available-plans`

Autenticación: Customer Portal session (cookie establecida por el flujo de magic-link).

Planes a los que esta suscripción puede cambiar.

Parámetros de ruta

Field	Type	Required	Description
`id`	string	Sí	—

Ejemplo de solicitud

curl https://api.tokeflow.com/api/v1/portal/subscriptions/obj_1a2b3c4d/available-plans \
  -H "Cookie: tf_portal_session=…"

Ejemplo de respuesta — 200

{
  "current_offer_id": "off_123",
  "current_amount": 4990,
  "currency": "BRL",
  "data": [
    {
      "offer_id": "off_456",
      "offer_name": "Premium Monthly",
      "description": "Human-readable description",
      "billing_cycle": "monthly",
      "currency": "BRL",
      "amount": 4990,
      "change_kind": "upgrade",
      "change_charge_behavior": "next_renew"
    }
  ]
}

POST`/api/v1/portal/subscriptions/:id/cancel`

Autenticación: Customer Portal session (cookie establecida por el flujo de magic-link).

Cancela una suscripción.

Parámetros de ruta

Field	Type	Required	Description
`id`	string	Sí	—

Campos de la solicitud

Field	Type	Required	Description
`at_period_end`	boolean	No	Cancela al final del período pagado (predeterminado true, el más favorable). false cancela de inmediato.
`reason`	string	No	Motivo de cancelación opcional.
`survey_response`	string	No	Respuesta opcional a la encuesta de cancelación.

Ejemplo de solicitud

curl -X POST https://api.tokeflow.com/api/v1/portal/subscriptions/obj_1a2b3c4d/cancel \
  -H "Cookie: tf_portal_session=…" \
  -H "Content-Type: application/json" \
  -d '{
    "at_period_end": true,
    "reason": "requested_by_customer",
    "survey_response": "string"
  }'

Ejemplo de respuesta — 200

{
  "id": "sub_123",
  "status": "trialing",
  "current_offer_id": "off_123",
  "billing_cycle": "daily",
  "currency": "BRL",
  "current_amount": 15000,
  "current_period_start": "2026-01-15T12:30:00.000Z",
  "current_period_end": "2026-01-15T12:30:00.000Z",
  "next_billing_at": "2026-01-15T12:30:00.000Z",
  "cancel_at_period_end": true,
  "cancelled_at": "2026-01-15T12:30:00.000Z",
  "cycles_completed": 1,
  "cycle_limit": 1,
  "trial_start": "2026-01-15T12:30:00.000Z",
  "trial_end": "2026-01-15T12:30:00.000Z",
  "preferred_installments": 1,
  "dunning_next_retry_at": "2026-01-15T12:30:00.000Z",
  "offer_name": "Premium Monthly",
  "product_name": "Streaming Plans",
  "card_brand": "visa",
  "card_last4": "4242",
  "card_exp_month": 12,
  "card_exp_year": 2027
}

POST`/api/v1/portal/subscriptions/:id/change-plan`

Autenticación: Customer Portal session (cookie establecida por el flujo de magic-link).

Cambia de plan (upgrade/downgrade).

Parámetros de ruta

Field	Type	Required	Description
`id`	string	Sí	—

Campos de la solicitud

Field	Type	Required	Description
`to_offer_id`	string	Sí	Oferta de destino a la que cambiar.

Ejemplo de solicitud

curl -X POST https://api.tokeflow.com/api/v1/portal/subscriptions/obj_1a2b3c4d/change-plan \
  -H "Cookie: tf_portal_session=…" \
  -H "Content-Type: application/json" \
  -d '{
    "to_offer_id": "off_123"
  }'

Ejemplo de respuesta — 200

{
  "id": "sub_123",
  "status": "trialing",
  "current_offer_id": "off_123",
  "billing_cycle": "daily",
  "currency": "BRL",
  "current_amount": 15000,
  "current_period_start": "2026-01-15T12:30:00.000Z",
  "current_period_end": "2026-01-15T12:30:00.000Z",
  "next_billing_at": "2026-01-15T12:30:00.000Z",
  "cancel_at_period_end": true,
  "cancelled_at": "2026-01-15T12:30:00.000Z",
  "cycles_completed": 1,
  "cycle_limit": 1,
  "trial_start": "2026-01-15T12:30:00.000Z",
  "trial_end": "2026-01-15T12:30:00.000Z",
  "preferred_installments": 1,
  "dunning_next_retry_at": "2026-01-15T12:30:00.000Z",
  "offer_name": "Premium Monthly",
  "product_name": "Streaming Plans",
  "card_brand": "visa",
  "card_last4": "4242",
  "card_exp_month": 12,
  "card_exp_year": 2027
}

POST`/api/v1/portal/subscriptions/:id/reactivate`

Autenticación: Customer Portal session (cookie establecida por el flujo de magic-link).

Reactiva un plan con cancelación pendiente o pausado.

Parámetros de ruta

Field	Type	Required	Description
`id`	string	Sí	—

Ejemplo de solicitud

curl -X POST https://api.tokeflow.com/api/v1/portal/subscriptions/obj_1a2b3c4d/reactivate \
  -H "Cookie: tf_portal_session=…"

Ejemplo de respuesta — 200

{
  "id": "sub_123",
  "status": "trialing",
  "current_offer_id": "off_123",
  "billing_cycle": "daily",
  "currency": "BRL",
  "current_amount": 15000,
  "current_period_start": "2026-01-15T12:30:00.000Z",
  "current_period_end": "2026-01-15T12:30:00.000Z",
  "next_billing_at": "2026-01-15T12:30:00.000Z",
  "cancel_at_period_end": true,
  "cancelled_at": "2026-01-15T12:30:00.000Z",
  "cycles_completed": 1,
  "cycle_limit": 1,
  "trial_start": "2026-01-15T12:30:00.000Z",
  "trial_end": "2026-01-15T12:30:00.000Z",
  "preferred_installments": 1,
  "dunning_next_retry_at": "2026-01-15T12:30:00.000Z",
  "offer_name": "Premium Monthly",
  "product_name": "Streaming Plans",
  "card_brand": "visa",
  "card_last4": "4242",
  "card_exp_month": 12,
  "card_exp_year": 2027
}

GET`/api/v1/portal/subscriptions/:id/transitions`

Autenticación: Customer Portal session (cookie establecida por el flujo de magic-link).

El historial de cambios de estado de una suscripción.

Parámetros de ruta

Field	Type	Required	Description
`id`	string	Sí	—

Ejemplo de solicitud

curl https://api.tokeflow.com/api/v1/portal/subscriptions/obj_1a2b3c4d/transitions \
  -H "Cookie: tf_portal_session=…"

Errores

Los errores usan el envelope estándar. Los casos más comunes aquí:

HTTP	Meaning
`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 inició sesión no tiene acceso a esta entidad.
`404`	El registro no existe o no es visible para esta entidad.

Suscripciones del Customer Portal

El objeto de la suscripción

Endpoints

GET`/api/v1/portal/subscriptions`

GET`/api/v1/portal/subscriptions/:id`

POST`/api/v1/portal/subscriptions/:id/add-card`

GET`/api/v1/portal/subscriptions/:id/available-plans`

POST`/api/v1/portal/subscriptions/:id/cancel`

POST`/api/v1/portal/subscriptions/:id/change-plan`

POST`/api/v1/portal/subscriptions/:id/reactivate`

GET`/api/v1/portal/subscriptions/:id/transitions`

Errores

Relacionados

En esta página

Suscripciones del Customer Portal

El objeto de la suscripción

Endpoints

GET/api/v1/portal/subscriptions

GET/api/v1/portal/subscriptions/:id

POST/api/v1/portal/subscriptions/:id/add-card

GET/api/v1/portal/subscriptions/:id/available-plans

POST/api/v1/portal/subscriptions/:id/cancel

POST/api/v1/portal/subscriptions/:id/change-plan

POST/api/v1/portal/subscriptions/:id/reactivate

GET/api/v1/portal/subscriptions/:id/transitions

Errores

Relacionados

En esta página

GET`/api/v1/portal/subscriptions`

GET`/api/v1/portal/subscriptions/:id`

POST`/api/v1/portal/subscriptions/:id/add-card`

GET`/api/v1/portal/subscriptions/:id/available-plans`

POST`/api/v1/portal/subscriptions/:id/cancel`

POST`/api/v1/portal/subscriptions/:id/change-plan`

POST`/api/v1/portal/subscriptions/:id/reactivate`

GET`/api/v1/portal/subscriptions/:id/transitions`