Trials, grace periods, and dunning: decide the policy first
Most “billing mismatches” are actually policy mismatches. The database is doing what it was told; the policy was never written down.
A reconciliation engine compares states. Before it can do that honestly, someone has to decide what each state should mean. Stripe’s status field describes billing. It does not describe your product’s access policy. The two are related, but they are not interchangeable.
Questions to answer in writing
- Does a trialing subscription grant full access, a limited trial, or no paid features?
- When a payment fails, how long does access continue? Is it based on days, invoice attempts, or a support decision?
- If a customer cancels at period end, does access continue until current_period_end? What timezone defines the boundary?
- Do annual contracts, invoices, or manual grants create entitlements outside Stripe?
- Who can grant an exception, and when does it expire?
Prefer explicit grace fields to implicit status checks
If access continues during dunning, record the grace end date in the entitlement system. Do not rely on a generic “past_due = allowed” rule that silently changes when billing settings change. An explicit date can be explained, tested, and expired.
Similarly, store the cancellation effective date. A subscription object can change after a cancellation is scheduled; the audit should compare the effective access window, not just the current status string.
Test the boundaries
Use fixed timestamps in tests. Check the minute before and after a period ends, including a daylight-saving transition if your users span timezones. Verify what happens when a retry succeeds after grace has expired, and when a canceled subscription is reactivated before the effective date.
An audit that is correct on ordinary days but wrong on boundaries will erode trust quickly.
Document the default
Write the policy in the product documentation and include the policy version in every finding. When the policy changes, new findings should say which version produced them. This is especially important when someone asks why a previously resolved case has reopened.
Primary references