Assinaturas

Uma assinatura é uma relação de cobrança de longa duração entre um dos seus clientes e uma offer. A Tokeflow acompanha seu ciclo de vida, conduz as renovações no ciclo de cobrança da oferta, reprocessa cobranças que falharam (dunning) e registra cada mudança de estado como uma transição imutável.

A Tokeflow orquestra cada cobrança de renovação entre os provedores de pagamento que você conecta; ela não processa nem liquida os fundos por conta própria. A liquidação é realizada pelo provedor conectado. A Tokeflow normaliza o resultado e avança a assinatura de acordo.

Como as assinaturas se encaixam

Toda assinatura permanece dentro de uma única família de produtos. Mudanças de oferta são permitidas apenas entre ofertas da mesma família; mover entre famílias é modelado como um cancelamento mais uma nova assinatura.

O objeto de assinatura

Uma assinatura é um snapshot desnormalizado do plano do cliente mais o estado de cobrança ao vivo de que a engine precisa para conduzi-la.

Ciclo de vida

Uma assinatura passa por seis estados. A engine de cobrança conduz a maioria das transições; você conduz as demais por meio dos endpoints abaixo.

Datas de cobrança

Os ciclos mensal, trimestral, semestral e anual renovam no billing_anchor_day. Quando o mês de destino é mais curto que a âncora, a renovação cai no último dia desse mês — uma assinatura ancorada no dia 31 renova em 28 de fevereiro (29 em ano bissexto) e depois em 31 de março —, de modo que nenhum mês é pulado. current_period_end é sempre igual à data de renovação ancorada (next_billing_at), então a data até a qual a assinatura está paga, exibida na API, nos webhooks e no cancelamento, nunca fica aquém. Uma troca de plano mantém a âncora existente da assinatura. Ciclos baseados em dias (daily, biweekly) e planos sob demanda não são ancorados.

Dunning

Quando uma cobrança de renovação falha, a assinatura entra em dunning em vez de ser cancelada de imediato. A engine agenda reprocessamentos em dunning_next_retry_at, incrementando dunning_attempt_count a cada tentativa.

Uma renovação nunca é retentada dentro da mesma requisição, e a forma como uma recusa é tratada depende do seu motivo de recusa, da mesma maneira para todos os provedores. Um motivo que diz que o cartão nunca mais poderá ser cobrado — perdido ou roubado, conta encerrada, autorização revogada, fraude confirmada, um emissor que diz para nunca retentar — cancela a assinatura na hora. Todas as outras recusas, incluindo um cartão vencido ou dados de cartão incorretos, vão para dunning, para que o cliente possa atualizar o cartão.

• Um reprocessamento que tem sucesso retorna a assinatura para active e reseta os contadores de dunning.
• Se os reprocessamentos forem esgotados, a assinatura é cancelada.
• Enquanto estiver em dunning, o cliente pode corrigir o problema trocando para um cartão que funcione — veja Trocar o instrumento de pagamento.

Retenções de cobrança (billing hold)

Uma renovação só é cobrada quando o merchant tem um conector ativo para roteá-la, o provedor ainda aceita as credenciais desse conector e a oferta da assinatura ainda está disponível. Se qualquer um desses itens faltar no momento da renovação, o motor coloca a renovação em uma retenção de cobrança temporária, em vez de cobrar sobre uma configuração inválida: nenhuma cobrança é tentada, o cliente não entra em dunning e a assinatura não é cancelada. As renovações voltam automaticamente assim que a configuração é corrigida — um conector ativo, uma oferta válida ou novas credenciais salvas em um conector cuja chave o provedor recusou. Quando um merchant retido volta a operar, o período de cobrança é reancorado, de modo que a próxima renovação é agendada a partir desse ponto, em vez de retroagida sobre o intervalo.

Uma assinatura viva por plano

Um cliente pode manter apenas uma assinatura viva por plano por vez. Uma assinatura marcada para cancelar ao fim do período (cancel_at_period_end: true) ainda conta como viva. Iniciar uma segunda assinatura para um plano que o cliente já possui é recusado com 409 (conflict_error); a resposta aponta a reativação como o caminho para manter a assinatura existente, em vez de criar uma duplicata.

Endpoints

Todas as rotas de assinatura ficam aninhadas sob um merchant:

/api/v1/merchants/:merchant_id/subscriptions

As mutações são protegidas pelo escopo subscriptions:write; as leituras exigem subscriptions:read.

GET/api/v1/merchants/:merchant_id/subscriptions

Lista as assinaturas de um merchant, das mais recentes para as mais antigas. Suporta paginação e filtragem.

Auth: Chave de Merchant (subscriptions:read)

Query parameters

curl -G "https://api.tokeflow.com/api/v1/merchants/mrc_8a1c2d/subscriptions" \
  -H "Authorization: Bearer sk_live_mer_…" \
  -d page=1 \
  -d limit=20 \
  -d status=active

Response 200 OK

{
  "success": true,
  "data": [
    {
      "id": "sub_3f9a7c2e1b",
      "merchant_id": "mrc_8a1c2d",
      "customer_id": "cust_5b2e9f",
      "customer_name": "Ana Souza",
      "customer_email": "ana@example.com",
      "current_offer_id": "ofr_premium_monthly",
      "offer_name": "Premium — Monthly",
      "product_id": "prd_7d4a1c",
      "product_name": "Premium Plan",
      "product_family_id": "pfa_streaming",
      "billing_cycle": "monthly",
      "currency": "BRL",
      "current_amount": 4990,
      "current_period_start": "2026-06-25T00:00:00.000Z",
      "current_period_end": "2026-07-25T00:00:00.000Z",
      "next_billing_at": "2026-07-25T00:00:00.000Z",
      "billing_anchor_day": 25,
      "trial_start": null,
      "trial_end": null,
      "dunning_started_at": null,
      "dunning_attempt_count": 0,
      "dunning_next_retry_at": null,
      "cycles_completed": 3,
      "cycle_limit": null,
      "status": "active",
      "cancel_at_period_end": false,
      "cancelled_at": null,
      "cancellation_reason": null,
      "payment_instrument_id": "pi_9c3f2a",
      "preferred_connector_name": "acquirer_a",
      "preferred_installments": 1,
      "created_at": "2026-03-25T12:00:00.000Z",
      "updated_at": "2026-06-25T00:00:01.000Z"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 42,
      "total_pages": 3,
      "has_next": true,
      "has_prev": false
    }
  },
  "request_id": "req_8f3c2a1b",
  "timestamp": "2026-06-25T12:30:00.000Z"
}

GET/api/v1/merchants/:merchant_id/subscriptions/:subscription_id

Recupera uma única assinatura pelo id.

Auth: Chave de Merchant (subscriptions:read)

curl "https://api.tokeflow.com/api/v1/merchants/mrc_8a1c2d/subscriptions/sub_3f9a7c2e1b" \
  -H "Authorization: Bearer sk_live_mer_…"

Response 200 OK

{
  "success": true,
  "data": {
    "id": "sub_3f9a7c2e1b",
    "merchant_id": "mrc_8a1c2d",
    "customer_id": "cust_5b2e9f",
    "current_offer_id": "ofr_premium_monthly",
    "product_family_id": "pfa_streaming",
    "billing_cycle": "monthly",
    "currency": "BRL",
    "current_amount": 4990,
    "current_period_start": "2026-06-25T00:00:00.000Z",
    "current_period_end": "2026-07-25T00:00:00.000Z",
    "next_billing_at": "2026-07-25T00:00:00.000Z",
    "billing_anchor_day": 25,
    "trial_start": null,
    "trial_end": null,
    "dunning_started_at": null,
    "dunning_attempt_count": 0,
    "dunning_next_retry_at": null,
    "cycles_completed": 3,
    "cycle_limit": null,
    "status": "active",
    "cancel_at_period_end": false,
    "cancelled_at": null,
    "cancellation_reason": null,
    "payment_instrument_id": "pi_9c3f2a",
    "preferred_installments": 1,
    "created_at": "2026-03-25T12:00:00.000Z",
    "updated_at": "2026-06-25T00:00:01.000Z"
  },
  "request_id": "req_8f3c2a1b",
  "timestamp": "2026-06-25T12:30:00.000Z"
}

Um id ausente ou fora de escopo retorna 404 (not_found_error).

GET/api/v1/merchants/:merchant_id/subscriptions/:subscription_id/transitions

Lista o histórico de transições da assinatura — um log de auditoria somente de acréscimo de cada mudança de estado e de oferta, das mais recentes para as mais antigas. Cada transição registra o que mudou, quem disparou e o pedido que a causou (quando aplicável). Este é o sistema de registro para o histórico de mudanças de oferta.

Auth: Chave de Merchant (subscriptions:read)

Objeto de transição

curl "https://api.tokeflow.com/api/v1/merchants/mrc_8a1c2d/subscriptions/sub_3f9a7c2e1b/transitions" \
  -H "Authorization: Bearer sk_live_mer_…"

Response 200 OK

{
  "success": true,
  "data": [
    {
      "id": "sbt_2b7e1a",
      "subscription_id": "sub_3f9a7c2e1b",
      "transition_type": "upgrade",
      "from_offer_id": "ofr_basic_monthly",
      "to_offer_id": "ofr_premium_monthly",
      "from_status": "active",
      "to_status": "active",
      "triggered_by": "customer",
      "actor": null,
      "order_id": null,
      "reason": null,
      "metadata": { "change_charge_behavior": "next_renew" },
      "created_at": "2026-06-01T09:14:00.000Z"
    },
    {
      "id": "sbt_1a9c4d",
      "subscription_id": "sub_3f9a7c2e1b",
      "transition_type": "creation",
      "from_offer_id": null,
      "to_offer_id": "ofr_basic_monthly",
      "from_status": null,
      "to_status": "active",
      "triggered_by": "system",
      "actor": null,
      "order_id": "ord_5e2f8b",
      "reason": null,
      "metadata": null,
      "created_at": "2026-03-25T12:00:00.000Z"
    }
  ],
  "request_id": "req_8f3c2a1b",
  "timestamp": "2026-06-25T12:30:00.000Z"
}

POST/api/v1/merchants/:merchant_id/subscriptions/:subscription_id/cancel

Cancela uma assinatura, seja imediatamente ou ao fim do período atual.

Auth: Chave de Merchant (subscriptions:write)

Body

Quando at_period_end é true, a assinatura é sinalizada (cancel_at_period_end: true) e a virada de status de fato acontece no próximo tick de renovação — nenhuma transição é registrada ainda, porque nada mudou de estado. Quando false, o status vira para cancelled imediatamente e uma transição cancellation é registrada.

curl -X POST "https://api.tokeflow.com/api/v1/merchants/mrc_8a1c2d/subscriptions/sub_3f9a7c2e1b/cancel" \
  -H "Authorization: Bearer sk_live_mer_…" \
  -H "Content-Type: application/json" \
  -d '{ "at_period_end": true, "reason": "customer no longer needs the service" }'

Response 200 OK — o objeto de assinatura atualizado. Com at_period_end: true:

{
  "success": true,
  "data": {
    "id": "sub_3f9a7c2e1b",
    "status": "active",
    "cancel_at_period_end": true,
    "cancellation_reason": "customer no longer needs the service",
    "current_period_end": "2026-07-25T00:00:00.000Z",
    "next_billing_at": "2026-07-25T00:00:00.000Z"
  },
  "request_id": "req_8f3c2a1b",
  "timestamp": "2026-06-25T12:30:00.000Z"
}

POST/api/v1/merchants/:merchant_id/subscriptions/:subscription_id/admin-cancel

Variante privilegiada do cancelamento, registrada como iniciada pelo merchant. Requer o escopo subscriptions:admin e não faz parte da API pública.

Parâmetros de caminho

Campos da requisição

Exemplo de requisição

curl -X POST https://api.tokeflow.com/api/v1/merchants/mrc_8a3f12d9/subscriptions/sub_6d80b3a2/admin-cancel \
  -H "Authorization: Bearer sk_live_mer_…" \
  -H "Content-Type: application/json" \
  -d '{
    "at_period_end": true,
    "reason": "customer no longer needs the service"
  }'

Exemplo de resposta — 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/merchants/:merchant_id/subscriptions/:subscription_id/change-offer

Move a assinatura para uma oferta diferente (um upgrade ou downgrade) dentro da mesma família de produtos. A Tokeflow classifica a mudança como upgrade ou downgrade a partir da ordem de tiers das ofertas e registra a transição correspondente.

Auth: Chave de Merchant (subscriptions:write)

Body

Como o comportamento de cobrança é resolvido

Cada par de ofertas pode declarar um change_charge_behavior que governa como o dinheiro é tratado quando o plano muda:

O comportamento efetivo para um dado par (from_offer → to_offer) é resolvido nesta ordem:

1. Se existir uma transição de oferta ativa para o par com um comportamento explícito, esse valor prevalece.
2. Caso contrário, recorre ao padrão da família de produtos.

curl -X POST "https://api.tokeflow.com/api/v1/merchants/mrc_8a1c2d/subscriptions/sub_3f9a7c2e1b/change-offer" \
  -H "Authorization: Bearer sk_live_mer_…" \
  -H "Content-Type: application/json" \
  -d '{ "to_offer_id": "ofr_premium_monthly" }'

Response 200 OK — a assinatura com o novo current_offer_id, o current_amount atualizado e o billing_cycle re-sincronizado com o ciclo da nova oferta. O período atual mantém suas datas: next_billing_at e os campos de roteamento permanecem inalterados, e o novo ciclo passa a reger as renovações a partir da próxima data de cobrança.

{
  "success": true,
  "data": {
    "id": "sub_3f9a7c2e1b",
    "current_offer_id": "ofr_premium_monthly",
    "current_amount": 4990,
    "billing_cycle": "monthly",
    "next_billing_at": "2026-07-25T00:00:00.000Z",
    "status": "active"
  },
  "request_id": "req_8f3c2a1b",
  "timestamp": "2026-06-25T12:30:00.000Z"
}

Erros comuns:

• 400 (validation_error) — a oferta de destino é a atual, a assinatura está cancelled/expired, não existe uma transição de oferta ativa para o par, a oferta de destino não tem preço na moeda da assinatura, ou as ofertas estão em famílias diferentes (trate uma mudança entre famílias como um cancelamento mais uma nova assinatura).

POST/api/v1/merchants/:merchant_id/subscriptions/:subscription_id/change-payment-instrument

Troca a assinatura para um instrumento de pagamento diferente para renovações futuras. Este é o caminho de recuperação para sair do dunning.

Auth: Chave de Merchant (subscriptions:write)

Body

O instrumento já deve ter uma cobrança confirmada iniciada pelo cliente contra ele, para que a Tokeflow possa rotear as renovações futuras pela conexão correta. Se não tiver, a chamada retorna 422 (business_rule_error).

curl -X POST "https://api.tokeflow.com/api/v1/merchants/mrc_8a1c2d/subscriptions/sub_3f9a7c2e1b/change-payment-instrument" \
  -H "Authorization: Bearer sk_live_mer_…" \
  -H "Content-Type: application/json" \
  -d '{ "payment_instrument_id": "pi_new1234" }'

Response 200 OK

{
  "success": true,
  "data": {
    "id": "sub_3f9a7c2e1b",
    "status": "active",
    "payment_instrument_id": "pi_new1234",
    "dunning_attempt_count": 0,
    "dunning_started_at": null,
    "dunning_next_retry_at": null,
    "current_period_end": "2026-07-25T00:00:00.000Z",
    "next_billing_at": "2026-07-25T00:00:00.000Z"
  },
  "request_id": "req_8f3c2a1b",
  "timestamp": "2026-06-25T12:30:00.000Z"
}

POST/api/v1/merchants/:merchant_id/subscriptions/:subscription_id/pause

Suspende a cobrança. Enquanto pausada, nenhuma renovação dispara. Uma transição pause é registrada.

Auth: Chave de Merchant (subscriptions:write)

Body

curl -X POST "https://api.tokeflow.com/api/v1/merchants/mrc_8a1c2d/subscriptions/sub_3f9a7c2e1b/pause" \
  -H "Authorization: Bearer sk_live_mer_…" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "customer travelling for 6 weeks" }'

Response 200 OK

{
  "success": true,
  "data": {
    "id": "sub_3f9a7c2e1b",
    "status": "paused"
  },
  "request_id": "req_8f3c2a1b",
  "timestamp": "2026-06-25T12:30:00.000Z"
}

POST/api/v1/merchants/:merchant_id/subscriptions/:subscription_id/resume

Retoma uma assinatura pausada. Ela volta para active, ou para trialing se o trial ainda estiver em execução. Se a próxima data de cobrança tiver ficado no passado enquanto estava pausada, o período é avançado para começar a partir de agora — pausar para o relógio em vez de pular um ciclo, então cycles_completed não é incrementado. Uma transição resume é registrada. Sem corpo de requisição.

Auth: Chave de Merchant (subscriptions:write)

curl -X POST "https://api.tokeflow.com/api/v1/merchants/mrc_8a1c2d/subscriptions/sub_3f9a7c2e1b/resume" \
  -H "Authorization: Bearer sk_live_mer_…"

Response 200 OK

{
  "success": true,
  "data": {
    "id": "sub_3f9a7c2e1b",
    "status": "active",
    "current_period_start": "2026-06-25T00:00:00.000Z",
    "current_period_end": "2026-07-25T00:00:00.000Z",
    "next_billing_at": "2026-07-25T00:00:00.000Z"
  },
  "request_id": "req_8f3c2a1b",
  "timestamp": "2026-06-25T12:30:00.000Z"
}

POST/api/v1/merchants/:merchant_id/subscriptions/:subscription_id/reactivate

Suspende um cancelamento agendado e mantém a assinatura no plano atual. A reativação define cancel_at_period_end de volta para false e registra uma transição reactivation. Ela não altera a oferta, o valor nem as datas de cobrança — apenas cancela o cancelamento pendente.

Use-a quando um cliente que havia agendado um cancelamento decide continuar, e como remédio para o 409 retornado quando um cliente tenta comprar um plano que já possui (veja Uma assinatura viva por plano).

Auth: Merchant key (subscriptions:write)

A reativação se aplica a uma assinatura viva — active, trialing ou dunning. Uma assinatura em dunning permanece em dunning e sua escada de reprocessamento não é afetada; cancelar o cancelamento é independente do problema de pagamento. Sem corpo de requisição.

curl -X POST "https://api.tokeflow.com/api/v1/merchants/mrc_8a1c2d/subscriptions/sub_3f9a7c2e1b/reactivate" \
  -H "Authorization: Bearer sk_live_mer_…"

Response 200 OK

{
  "success": true,
  "data": {
    "id": "sub_3f9a7c2e1b",
    "status": "active",
    "cancel_at_period_end": false
  },
  "request_id": "req_8f3c2a1b",
  "timestamp": "2026-06-25T12:30:00.000Z"
}

Erros

Os endpoints de assinatura usam o envelope de erro padrão. Os casos mais comuns:

Relacionados

• Ofertas — defina ciclos de cobrança, preços, trials e transições de oferta.
• Pedidos — o pedido criado a cada renovação.
• Transações — a cobrança subjacente e os instrumentos de pagamento.
• Visão geral da referência de API — envelopes, paginação, IDs e convenções de valores monetários.