tokeflow.com
DocumentaçãoReferência da APIDashboardsSDKsChangelog

Assinaturas do Merchant

Gerencie as assinaturas de um Merchant a partir do Dashboard — inspecione o ciclo de vida e o dunning, pause ou retome, cancele e altere a oferta cobrada.

Uma assinatura é um acordo recorrente entre um cliente e um Merchant, cobrado contra uma oferta. Esses endpoints são a base da tela de assinaturas do Dashboard: listar e abrir assinaturas, percorrer seu histórico de transições, pausar e retomar, cancelar e mover uma para uma oferta diferente.

Toda mudança de estado é registrada como uma transição — o histórico somente-acréscimo que responde o que mudou, quando e por quê. O dunning faz parte desse ciclo de vida: uma renovação que falha move a assinatura para um estado de reprocessamento em vez de encerrá-la de imediato.

Esses endpoints alimentam a Tokeflow Dashboard UI. Eles são autenticados por sessão (JWT bearer) — o token vem do login no Dashboard, não de uma chave de API sk_/pk_. As solicitações também levam o header x-merchant-id que identifica o Merchant em contexto, e o usuário logado deve ser um membro com acesso a ele.

O objeto de assinatura

Retornado pelos endpoints de listagem e recuperação desta página.

FieldTypeDescription
idstringID da assinatura.
merchant_idstringID do Merchant.
customer_idstringID do cliente.
customer_namestring | nullNome do cliente (resolvido).
customer_emailstring | nullE-mail do cliente (resolvido).
current_offer_idstringID da oferta atual.
offer_namestringNome da oferta (resolvido).
product_idstringID do produto da oferta atual.
product_namestringNome do produto (resolvido).
product_family_idstringID da família de produtos.
billing_cyclestringUm de daily, biweekly, monthly, quarterly, half_yearly, yearly, custom, none.
currencystringMoeda ISO 4217.
current_amountnumberValor da cobrança atual em unidades menores.
current_period_startstring(ISO 8601 UTC).
current_period_endstring(ISO 8601 UTC).
next_billing_atstring | null(ISO 8601 UTC).
billing_anchor_daynumber | null—
trial_startstring | null(ISO 8601 UTC).
trial_endstring | null(ISO 8601 UTC).
dunning_started_atstring | null(ISO 8601 UTC).
dunning_attempt_countnumber—
dunning_next_retry_atstring | null(ISO 8601 UTC).
cycles_completednumber—
cycle_limitnumber | null—
statusstringUm de trialing, active, dunning, paused, cancelled, expired.
cancel_at_period_endboolean—
cancelled_atstring | null(ISO 8601 UTC).
cancellation_reasonstring | null—
payment_instrument_idstring—
preferred_connector_idstring | null—
preferred_connector_namestringNome do conector preferido (resolvido).
initial_network_transaction_idstring | null—
preferred_installmentsnumber—
created_atstring(ISO 8601 UTC).
updated_atstring(ISO 8601 UTC).

Endpoints

GET/api/v1/merchant/subscriptions

Merchant

Auth: Dashboard session (JWT bearer). É necessário ser membro do Merchant.

Lista as assinaturas do Merchant.

Parâmetros de consulta

FieldTypeRequiredDescription
pagenumberNãoNúmero da página (indexado a partir de 1). Padrão 1, mín. 1.
limitnumberNãoNúmero de itens por página. Padrão 20, mín. 1, máx. 100.
customer_idstringNãoFiltra por ID do cliente
statusstringNãoFiltra por status da assinatura
current_offer_idstringNãoFiltra por ID da oferta atual
product_family_idstringNãoFiltra por ID da família de produtos

Exemplo de solicitação

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"

Exemplo de resposta — 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). É necessário ser membro do Merchant.

Recupera a assinatura pelo ID.

Parâmetros de caminho

FieldTypeRequiredDescription
idstringSim—

Exemplo de solicitação

curl https://api.tokeflow.com/api/v1/merchant/subscriptions/obj_1a2b3c4d \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9"

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/merchant/subscriptions/:id/cancel

Merchant

Auth: Dashboard session (JWT bearer). É necessário ser membro do Merchant.

Cancela a assinatura (atribuição de admin).

Parâmetros de caminho

FieldTypeRequiredDescription
idstringSim—

Campos da solicitação

FieldTypeRequiredDescription
at_period_endbooleanSimQuando true, adia o cancelamento para a próxima renovação; false cancela imediatamente.
reasonstringNãoMotivo opcional legível por humanos persistido na assinatura.

Exemplo de solicitação

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

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/merchant/subscriptions/:id/change-offer

Merchant

Auth: Dashboard session (JWT bearer). É necessário ser membro do Merchant.

Altera a oferta da assinatura.

Parâmetros de caminho

FieldTypeRequiredDescription
idstringSim—

Campos da solicitação

FieldTypeRequiredDescription
to_offer_idstringSimID da oferta de destino. Deve pertencer à mesma família de produtos que a oferta atual.

Exemplo de solicitação

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

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/merchant/subscriptions/:id/change-payment-instrument

Merchant

Auth: Dashboard session (JWT bearer). É necessário ser membro do Merchant.

Altera o instrumento de pagamento da assinatura.

Parâmetros de caminho

FieldTypeRequiredDescription
idstringSim—

Campos da solicitação

FieldTypeRequiredDescription
payment_instrument_idstringSimID do instrumento de pagamento a ser cobrado daqui em diante.

Exemplo de solicitação

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

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/merchant/subscriptions/:id/pause

Merchant

Auth: Dashboard session (JWT bearer). É necessário ser membro do Merchant.

Pausa a assinatura.

Parâmetros de caminho

FieldTypeRequiredDescription
idstringSim—

Campos da solicitação

FieldTypeRequiredDescription
reasonstringNãoMotivo opcional legível por humanos persistido na transição.

Exemplo de solicitação

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

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/merchant/subscriptions/:id/resume

Merchant

Auth: Dashboard session (JWT bearer). É necessário ser membro do Merchant.

Retoma a assinatura.

Parâmetros de caminho

FieldTypeRequiredDescription
idstringSim—

Exemplo de solicitação

curl -X POST https://api.tokeflow.com/api/v1/merchant/subscriptions/obj_1a2b3c4d/resume \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9"

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/merchant/subscriptions/:id/reactivate

Merchant

Auth: Dashboard session (JWT bearer). É necessário ser membro do Merchant.

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; não altera a oferta, o valor nem as datas de cobrança. Disponível para uma assinatura viva (active, trialing ou dunning); uma assinatura paused deve ser retomada (resume), e uma terminal é recusada (409).

Parâmetros de caminho

FieldTypeRequiredDescription
idstringYes—

Exemplo de requisição

curl -X POST https://api.tokeflow.com/api/v1/merchant/subscriptions/obj_1a2b3c4d/reactivate \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9"

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
}

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

Merchant

Auth: Dashboard session (JWT bearer). É necessário ser membro do Merchant.

Lista o histórico de transições da assinatura.

Parâmetros de caminho

FieldTypeRequiredDescription
idstringSim—

Exemplo de solicitação

curl https://api.tokeflow.com/api/v1/merchant/subscriptions/obj_1a2b3c4d/transitions \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9"

Exemplo de resposta — 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"
    }
  ]
}

Erros

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

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

Relacionados

Configurações do Merchant

Anterior

Webhooks do Merchant

Próxima

Nesta página

O objeto de assinaturaEndpointsGET /api/v1/merchant/subscriptionsGET /api/v1/merchant/subscriptions/:idPOST /api/v1/merchant/subscriptions/:id/cancelPOST /api/v1/merchant/subscriptions/:id/change-offerPOST /api/v1/merchant/subscriptions/:id/change-payment-instrumentPOST /api/v1/merchant/subscriptions/:id/pausePOST /api/v1/merchant/subscriptions/:id/resumePOST /api/v1/merchant/subscriptions/:id/reactivateGET /api/v1/merchant/subscriptions/:id/transitionsErrosRelacionados