Recipe: Subscription billing code catalog
Map every billing event to a stable, auditable code. Use this catalog to keep your payment integrations, analytics, and support tooling in sync.
Code taxonomy
| Code | Event | Retry |
|---|---|---|
| SUB_NEW | Initial subscription created | No |
| SUB_RENEW | Recurring charge succeeded | No |
| SUB_FAIL | Payment failure (any reason) | Yes |
| SUB_CANCEL | Voluntary cancellation | No |
| SUB_UPGRADE | Plan upgrade mid-cycle | No |
| SUB_DOWNGRADE | Plan downgrade (effective next cycle) | No |
Integration notes
- •Pass the code as
billing_codein every webhook payload. - •Retryable events use exponential backoff with a 24-hour ceiling.
- •Never derive the code from the payment provider's raw status — always map through this catalog.