Assinaturas do Customer Portal

Permita que um cliente veja e gerencie as próprias assinaturas no portal — ver planos, trocar de plano, adicionar um cartão durante o dunning e cancelar.

Estes endpoints permitem que um cliente autenticado gerencie as próprias assinaturas: listá-las, abrir uma, ver para quais planos ela pode trocar, adicionar um cartão enquanto uma renovação está falhando (dunning) e cancelar.

As ações aqui são limitadas pela configuração do portal do Merchant — um Merchant escolhe se os clientes podem trocar de plano ou cancelar por conta própria. Tudo é restrito ao cliente dono da sessão; um cliente nunca pode ver as assinaturas de outro.

Estes endpoints alimentam o Customer Portal — a superfície self-service que os seus clientes finais usam, sob a sua marca. Eles são autenticados por um cookie de sessão do portal, estabelecido por meio do fluxo de magic-link (solicitar um link e depois verificar o token), e não por uma chave de API. Consulte Sessões e configuração.

O objeto da assinatura

Retornado pelos endpoints de listagem e consulta desta página.

Field	Type	Description
`id`	string	—
`status`	string	Um de `trialing`, `active`, `dunning`, `paused`, `cancelled`, `expired`.
`current_offer_id`	string	—
`billing_cycle`	string	Um de `daily`, `biweekly`, `monthly`, `quarterly`, `half_yearly`, `yearly`, `custom`, `none`.
`currency`	string	—
`current_amount`	number	Valor atual em 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 cobrança concluídos.
`cycle_limit`	number \| null	Máximo de cobranças; null = contínuo.
`trial_start`	string \| null	(ISO 8601 UTC).
`trial_end`	string \| null	(ISO 8601 UTC).
`preferred_installments`	number	—
`dunning_next_retry_at`	string \| null	Próxima tentativa de dunning (se em 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`

Autenticação: Customer Portal session (cookie definido pelo fluxo de magic-link).

Lista as assinaturas do cliente.

Exemplo de requisição

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

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

Autenticação: Customer Portal session (cookie definido pelo fluxo de magic-link).

Obtém uma assinatura.

Parâmetros de caminho

Field	Type	Required	Description
`id`	string	Sim	—

Exemplo de requisição

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

Exemplo de resposta — 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`

Autenticação: Customer Portal session (cookie definido pelo fluxo de magic-link).

Adiciona um cartão durante o dunning.

Parâmetros de caminho

Field	Type	Required	Description
`id`	string	Sim	—

Campos da requisição

Field	Type	Required	Description
`card_ciphertext_id`	string	Sim	A referência de cartão criptografada de uso único (`tok_…`) do novo cartão, proveniente do Bridge SDK.

Exemplo de requisição

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"
  }'

Exemplo de resposta — 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`

Autenticação: Customer Portal session (cookie definido pelo fluxo de magic-link).

Planos para os quais esta assinatura pode trocar.

Parâmetros de caminho

Field	Type	Required	Description
`id`	string	Sim	—

Exemplo de requisição

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

Exemplo de resposta — 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`

Autenticação: Customer Portal session (cookie definido pelo fluxo de magic-link).

Cancela uma assinatura.

Parâmetros de caminho

Field	Type	Required	Description
`id`	string	Sim	—

Campos da requisição

Field	Type	Required	Description
`at_period_end`	boolean	Não	Cancela ao final do período pago (padrão true, mais favorável). false cancela imediatamente.
`reason`	string	Não	Motivo de cancelamento opcional.
`survey_response`	string	Não	Resposta opcional da pesquisa de cancelamento.

Exemplo de requisição

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"
  }'

Exemplo de resposta — 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`

Autenticação: Customer Portal session (cookie definido pelo fluxo de magic-link).

Troca de plano (upgrade/downgrade).

Parâmetros de caminho

Field	Type	Required	Description
`id`	string	Sim	—

Campos da requisição

Field	Type	Required	Description
`to_offer_id`	string	Sim	Oferta de destino para a troca.

Exemplo de requisição

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"
  }'

Exemplo de resposta — 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`

Autenticação: Customer Portal session (cookie definido pelo fluxo de magic-link).

Reativa um plano com cancelamento pendente ou pausado.

Parâmetros de caminho

Field	Type	Required	Description
`id`	string	Sim	—

Exemplo de requisição

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

Exemplo de resposta — 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`

Autenticação: Customer Portal session (cookie definido pelo fluxo de magic-link).

Histórico de mudanças de estado de uma assinatura.

Parâmetros de caminho

Field	Type	Required	Description
`id`	string	Sim	—

Exemplo de requisição

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

Erros

Os erros usam o envelope padrão. Os casos mais comuns aqui:

HTTP	Meaning
`400`	Parâmetros inválidos ou um estado que não permite esta operação.
`401`	Token de Dashboard session ausente, expirado ou inválido.
`403`	Autenticado, mas o usuário conectado não tem acesso a esta entidade.
`404`	O registro não existe ou não é visível para esta entidade.

Assinaturas do Customer Portal

O objeto da assinatura

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`

Erros

Relacionados

Nesta página

Assinaturas do Customer Portal

O objeto da assinatura

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

Erros

Relacionados

Nesta 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`