Entitlements

Entitlements são as capacidades que um plano concede, o que o seu SaaS deve liberar ({"seats": 5, "api": true}, etc.). A ribbo não conhece "planos" do seu lado, só capacidades.

Consultar as capacidades de um cliente

curl "https://api.ribbo.app/v1/entitlements?external_id=cliente-123" -H "Authorization: Bearer bk_..."
# ou ?email=cliente@empresa.com

Lista as assinaturas do cliente que não estão canceladas, cada uma com os entitlements do plano, e soma em merged_entitlements as que estão active, trialing ou past_due (uma suspended aparece na lista, mas não soma):

{
  "customer_id": "cus_01J…",
  "subscriptions": [
    { "id": "sub_01J…", "status": "active", "plan_id": "plan_01J…", "interval": "month",
      "current_period_end": "2026-09-01T00:00:00Z", "entitlements": { "seats": 5, "api": true } }
  ],
  "merged_entitlements": { "seats": 5, "api": true }
}

Cliente inexistente → 200 com customer_id: null (nunca 404). Sem external_id nem email → 400.

Editar o plano reflete sozinho

Os entitlements vêm sempre do catálogo atual. Ao editar o que um plano libera no painel, a ribbo envia subscription.updated (com o mapa novo) para cada assinatura viva daquele plano, e o GET /v1/entitlements já devolve o novo conjunto. O seu app não precisa de script de migração.

🔑 A regra de ouro

No webhook, o campo entitlements vem cheio mesmo quando a assinatura está suspended/past_due/canceled. Decida o acesso pelo status, nunca pela presença de entitlements, senão você re-libera acesso a um inadimplente. Ver Webhooks.

O merged_entitlements acima já segue o status (só soma active, trialing e past_due) e serve para reconciliar quando o seu app perdeu um webhook.