Understanding the Core Premise

In the world of modern applications, especially those that leverage payment processing platforms like Stripe, it’s crucial to distinguish between two types of truths: financial truth and application truth. Stripe serves as the authoritative source of financial truth, detailing what has transpired in terms of transactions. Conversely, your application’s database embodies the operational truth — that is, it reflects what your application should do based on the financial data provided by Stripe. Understanding this separation is key to building a robust billing model.

Why You Must Not Query Stripe in Normal Operation

Imagine relying on an API call to determine a user’s subscription status just as a major payment is being processed. Sounds like a recipe for disaster, right? The asynchronous nature of Stripe billing events means that querying Stripe in real-time cannot be trusted for access control decisions. When you check subscription.status via API, you may get outdated or incorrect information, leading to erroneous behavior in your application. This is akin to asking a busy barista about the status of your coffee order right before they’ve had a chance to brew it — you may end up with a less-than-desirable outcome.

The Database as a Stripe Cache

To ensure your application operates smoothly, consider your database as a cache that stores the relevant billing information. The flow can be summed up as: Stripe sends events, webhooks receive them, the database is updated, and your application logic takes action based on this state. This is a form of event-sourced billing; reading directly from Stripe bypasses your carefully curated state machine, leaving your application vulnerable to inconsistencies.

What Data Must Be Stored Locally

When building a billing system, there are several critical fields that should be stored in your database. Here’s a brief overview of the essential elements:

• stripe_customer_id: This is a unique identifier for your customer in Stripe. It helps you link the user in your application to their respective billing information.
• stripe_subscription_id: Similar to the customer ID, this ID ties the subscription to the user, making it easier to manage subscription lifecycles.
• subscription status: Knowing whether a subscription is active, canceled, or in a past due state allows your application to make informed decisions about access control.
• current_period_end: This field tells you when the current billing period ends, which is crucial for determining if a user is still entitled to services.
• cancel_at_period_end: This boolean indicates if the subscription is set to cancel at the end of the current period, allowing for better user experience management.
• latest invoice status: Keeping track of the latest invoice status helps you understand if a payment was successful or if there are issues that need addressing.
• default payment method (optional): Storing this information can streamline the checkout process for returning customers.

Each of these fields plays a pivotal role in ensuring that your application can operate independently and reliably, without needing to constantly query Stripe.

How to Keep the Database in Sync

Maintaining sync between your database and Stripe’s realities involves a webhook-driven synchronization model. When Stripe emits events, your webhook handler interprets these events and updates the database deterministically. The application should trust only the database, creating a reliable foundation for your operational truth.

At a conceptual level, idempotency is crucial here. This means that no matter how many times an event is processed, the outcome remains the same. This ensures that your application doesn’t inadvertently change the state of the database multiple times due to duplicated webhook events.

The Importance of Event Ordering

Another challenge is that Stripe may deliver events out of order. Your database model must be resilient to this unpredictability. Writing state transitions that accommodate late-arriving events ensures that your application behaves correctly, regardless of the order in which updates are received. Think of it as ensuring that your house remains standing even if a strong wind blows the doors open and shut unexpectedly.

Access Control From DB Only

It is vital that your application decides access based solely on the data stored in your database. Mixing real-time Stripe queries with DB-derived states can lead to significant risks. For instance, if your application grants access based on a Stripe API response that indicates an active subscription, you may unintentionally allow users to access features they should not have, particularly if that response is delayed or incorrect.

Common Mistakes to Avoid

When implementing a billing model, be wary of several pitfalls:

• Using Stripe’s subscription status for access control: Always rely on your database for this.
• Updating DB via redirect after Checkout: This can lead to race conditions.
• Not storing subscription rows: If you don’t have this data, you lose insight into your users’ billing history.
• Failing to handle invoice.payment_failed events: This could leave your application in a state where users retain access despite payment issues.
• Allowing “active” access during incomplete or past_due states: This can lead to confusion and frustration for your users.

A Clear Mental Model

In a nutshell, think of Stripe as the keeper of financial truth, while your database holds operational truth. Webhooks are the vital link that keeps these two worlds synchronized, ensuring your application behaves predictably and correctly.

Closing Summary

In conclusion, your database should always be viewed as the authoritative source for your application’s behavior. While Stripe provides the financial truth, it’s the stability, predictability, and clarity provided by your database that enables you to build a reliable billing model. By maintaining a clear separation between these truths and adhering to best practices, you can create a seamless user experience that stands the test of time.