Skip to main content

​
Esquema

CampoTipoDescrição
subscriptionIdUUIDv7Identificador único
organizationIdUUIDv7FK para Organization
planIdUUIDv7FK para Plan
planIntervalIdUUIDv7FK para PlanInterval
externalPlanRefstring?Subscription do Stripe (plano)
externalFeeRefstring?Subscription do Stripe (taxas)
currencyenumUSD, BRL, EUR
statusenumVeja abaixo
pastDueReasonenum?PLAN, FEE, PLAN_FEE
pastDueAtdatetime?Quando ficou inadimplente
pausedByUUIDv7?Quem pausou
pausedAtdatetime?Quando pausou
cancelledByUUIDv7?Quem cancelou
cancelledAtdatetime?Quando cancelou
createdByUUIDv7Criador
createdAtdatetimeCriação
updatedByUUIDv7Último atualizador
updatedAtdatetimeÚltima atualização
A subscription possui duas referências externas separadas no Stripe: externalPlanRef para a cobrança fixa do plano e externalFeeRef para as taxas de uso variável. Isso permite que cada componente tenha seu próprio ciclo de cobrança.

​
Transições de Estado

Quando a subscription entra em PAST_DUE, o campo pastDueReason indica qual componente falhou: PLAN (cobrança fixa), FEE (taxas de uso) ou PLAN_FEE (ambos). Isso é essencial para o fluxo de recuperação de inadimplência.

​
Relacionamentos

  • Belongs to Organization
  • Belongs to Plan / PlanInterval
  • Has many Invoices
  • Has many SubscriptionCoupons

​
Regras de Negócio

  • Criada com status ACTIVE
  • pastDueReason indica o componente que falhou no pagamento
  • Pausa suporta collectionBehavior: KEEP_AS_DRAFT ou MARK_UNCOLLECTIBLE
  • Suporta aplicação de cupons via SubscriptionCoupon
Ao pausar uma subscription, o collectionBehavior determina o que acontece com as faturas pendentes: KEEP_AS_DRAFT mantém como rascunho para cobrança futura, enquanto MARK_UNCOLLECTIBLE marca como incobrável. Escolha com cuidado baseado na política comercial.

​
Exemplo

{
  "subscriptionId": "019526a1-3c40-7f5d-b4e2-8a0c6e2f4b7d",
  "organizationId": "019526a0-1a20-7d3b-a1c9-5f7e9b0d3f5b",
  "planId": "019525fd-7e40-7c5a-b2d8-4e6f8a0c2e4a",
  "planIntervalId": "019525fd-8a10-7d3b-a1c9-5f7e9b0d3f5b",
  "externalPlanRef": "sub_1PqR2sT4uV6wX8yZ",
  "externalFeeRef": "sub_2QrS3tU5vW7xY9zA",
  "currency": "BRL",
  "status": "ACTIVE",
  "pastDueReason": null,
  "pastDueAt": null,
  "pausedBy": null,
  "pausedAt": null,
  "cancelledBy": null,
  "cancelledAt": null,
  "coupons": [
    {
      "couponId": "019526b2-4d50-7a6e-c5f3-9b1d7f3a5c8e",
      "code": "BEMVINDO2026",
      "type": "PERCENTAGE",
      "amount": 20,
      "appliedAt": "2026-01-15T10:30:00Z"
    }
  ],
  "createdBy": "019525fc-1234-7a1b-8c2d-3e4f5a6b7c8d",
  "createdAt": "2026-01-15T10:30:00Z",
  "updatedBy": "019525fc-1234-7a1b-8c2d-3e4f5a6b7c8d",
  "updatedAt": "2026-01-15T10:30:00Z"
}