← Todos os modelos

Planos, cálculo proporcional, novas tentativas de pagamentos falhados, faturas, cancelamento.

Spec — Checkout and subscriptions

Status: draft · Created: 2026-11-10

1. Context and goal

Customers choose a plan, pay by card through a payment provider, and change or cancel it themselves, with a correct invoice at every step.

2. Functional requirements (EARS)

  • FR-1: THE SYSTEM SHALL take each plan's price, currency, billing period (monthly or yearly) and limits from one catalog used by checkout, billing and invoices.
  • FR-2: WHEN a customer checks out, THE SYSTEM SHALL collect the card through the provider's hosted fields, so card numbers never reach our servers.
  • FR-3: WHEN the provider confirms the first payment, THE SYSTEM SHALL activate the subscription within 10 seconds and email a receipt.
  • FR-4: THE SYSTEM SHALL change subscription state only from provider webhooks with a valid signature, processing each event id once.
  • FR-5: WHEN a customer upgrades in the middle of a period, THE SYSTEM SHALL apply the new plan at once and charge the difference prorated to the day.
  • FR-6: WHEN a customer downgrades, THE SYSTEM SHALL schedule the new plan for the end of the current period and refund nothing.
  • FR-7: IF current usage exceeds the limits of the target plan, THEN THE SYSTEM SHALL refuse the downgrade with 409 naming each exceeded limit.
  • FR-8: IF a renewal payment fails, THEN THE SYSTEM SHALL retry it 3, 5 and 7 days later and email the customer after each failure with a link to update the card.
  • FR-9: WHILE a payment is overdue, THE SYSTEM SHALL keep the subscription active for 14 days, then make the account read-only until it is paid.
  • FR-10: WHEN a payment succeeds, THE SYSTEM SHALL issue a sequentially numbered invoice with seller and buyer details, tax per line and total, as a PDF the customer can download for 10 years.
  • FR-11: THE SYSTEM SHALL compute tax from the customer's billing country and tax id, and apply the reverse charge to valid EU VAT ids.
  • FR-12: WHEN a customer cancels, THE SYSTEM SHALL keep the plan until the end of the paid period, stop the renewal, and allow reactivation until then.

3. Out of scope

  • Usage-based billing.
  • Payment methods other than cards.
  • Coupons and discounts.