Docs

Buscar na documentação

Guias, endpoints e eventos

Ir ao painel

Assinaturas

A assinatura nasce no checkout da ribbo. O cliente assina pela página de checkout (o número do cartão nunca toca o seu servidor nem o da ribbo). A API de integração serve para ler e gerenciar as assinaturas, não para criá-las.

Ler o estado atual de uma assinatura

Qualquer status (inclusive canceled/suspended), útil para reconciliar um webhook perdido. Escopo read.

curl "https://api.ribbo.app/v1/subscriptions/sub_01J…" -H "Authorization: Bearer bk_..."

O shape é o mesmo do payload de webhook (Webhooks): subscription_id, status, customer, plan_id, plan_name, interval, current_period_end, cancel_at_period_end, collection_method, payment_method, next_charge_amount_cents, currency, pending_offer, entitlements, last_payment e tracking.

Listar assinaturas do tenant

curl "https://api.ribbo.app/v1/subscriptions?status=active,past_due&limit=100" -H "Authorization: Bearer bk_..."

Filtros: ?status= (CSV; valor desconhecido dá 400), ?offer_id=, ?limit= (máx 500), ?after= (cursor). Resposta {results, next}. Nas listas, last_payment e tracking são omitidos (leia a assinatura pelo id se precisar deles).

Assinaturas de um cliente

curl "https://api.ribbo.app/v1/customers/cliente-123/subscriptions" -H "Authorization: Bearer bk_..."

Estados (status)

trialing, active, past_due (inadimplente, em retentativa), suspended, canceled, pending_first_payment. O acesso do cliente é decidido pelo status: ver a regra de ouro em Webhooks.

Teste grátis (trial)

Durante o teste a assinatura fica trialing (evento subscription.trial_started). No fim do teste a ribbo cobra o cartão salvo: aprovado, a assinatura vira active e chega invoice.paid; recusado, ela vira past_due e entra na régua abaixo. Quem cancela durante o teste (cancel_at_period_end: true) não é cobrado.

Régua de cobrança

  • Cartão recusado: novas tentativas em D+1, D+3, D+5 e D+9, contados do vencimento. O acesso continua durante o atraso (past_due); depois da última tentativa a assinatura fica suspended e volta para active quando o cliente paga.
  • Pix na renovação: o QR é enviado 3 dias antes do vencimento, com lembretes 1 e 3 dias depois. Sem pagamento, o acesso é cortado no mesmo D+9; o QR segue pagável até D+15.