SaaS Billing Architecture: Stripe, Plans, Trials, and Upgrades

Billing looks simple when it is drawn on a pricing page. Three plans. A monthly and annual toggle. A free trial. One button for upgrading. Behind that page sits one of the most interconnected parts of a SaaS product.

A customer changes plans halfway through the month. Another adds five users. A card fails while an account is still active. Someone cancels during a trial and returns two weeks later. An annual customer requests an upgrade that should take effect immediately. A payment succeeds in Stripe, but the corresponding event reaches the application several seconds later.

Every situation forces the product to answer the same fundamental question:

What is this customer entitled to right now?

That is the real purpose of SaaS billing architecture.

Stripe can process payments and manage subscriptions, but the SaaS product still needs its own rules for plans, permissions, trials, upgrades, downgrades, failed payments, cancellations, and account states.

Once those rules become scattered across the codebase, even a small pricing change can become surprisingly difficult.

Your pricing page is not your billing model

A pricing page is designed for customers. A billing model is designed for reality. Suppose a SaaS company offers Starter, Professional, and Enterprise plans.

From the website, the structure appears straightforward. Behind it, the application may need to distinguish between monthly and annual subscriptions, legacy pricing, promotional discounts, trial accounts, manually negotiated contracts, different seat limits, and customers who purchased the same plan at different prices.

This creates an important architectural distinction.

A plan name should not become the business logic.

If the application repeatedly asks whether plan = professional before allowing access to functionality, pricing and product behavior gradually become tightly coupled.

A more flexible system thinks in terms of entitlements.

Instead of:

Professional plan → advanced reports

the application understands:

Account → subscription → entitlements → advanced reports enabled

That extra layer may appear unnecessary when the product has three plans.

It becomes extremely valuable when sales introduces a custom package, an existing customer keeps legacy pricing, or the company decides to move one feature from Professional to Starter without migrating thousands of accounts manually.

Stripe should know about money. Your product should know about access

One architectural mistake deserves special attention: making Stripe the only source of truth for the customer's product state.

Stripe should be authoritative about payment-related information such as subscriptions, invoices, payment status, billing periods, and transactions.

The SaaS application has a different responsibility. It needs to know what the user can actually do. Those two states are connected, but they are not identical.

Imagine an invoice payment fails at 02:14. Should the customer's account become inaccessible at 02:14? Probably not.

The business may offer a grace period. Administrators might retain access while regular users are restricted. Previously created data may remain readable while new actions are disabled. Enterprise customers may follow completely different collection rules.

Stripe knows that payment failed.

Your application decides what that failure means.

Keeping this boundary clear prevents payment-provider events from directly controlling dozens of unrelated product behaviors.

A subscription is a state machine, even if nobody calls it one

Subscription logic becomes much easier to reason about when the team stops treating subscriptions as simply "active" or "inactive."

A customer can move through many states:

Trial → Active → Past due → Grace period → Suspended → Canceled

Another path might look like:

Trial → Canceled → Expired

An annual customer could follow:

Active → Scheduled downgrade → Renewed on lower plan

Each transition has consequences.

Does access change immediately? Should an email be sent? Does the account retain its data? Should usage limits reset? Does the change happen now or at the end of the billing period?

Defining these transitions explicitly prevents individual developers from answering the same business question differently in separate parts of the application.

It also makes unusual billing situations much easier to test.

Building subscription billing into your SaaS?

Codica can design the billing logic behind your pricing model.

Contact us

Trials are product logic disguised as billing

A 14-day free trial sounds like a billing configuration. Then product questions begin.

• Does the trial require a payment method?
• Can someone start another trial with a different workspace?
• Does inviting teammates extend anything?
• What happens to created data when the trial expires?
• Can sales extend a trial manually?
• If the customer upgrades on day eight, does billing begin immediately?
• Can an expired trial still access the product in read-only mode?

Suddenly, very little of the discussion is about payment processing.

Trial design also affects conversion. Opt-in trials that do not require a payment method convert at a median rate of roughly 8%, while opt-out trials that require a card upfront can convert at around 30% or more. That makes the payment-method requirement a product and revenue decision, not simply a billing setting.

Trials affect authentication, permissions, onboarding, notifications, analytics, account lifecycle, and conversion tracking. That makes them part of the product architecture.

A useful trial model, therefore, defines more than just trial_start and trial_end. It establishes the account’s entitlements during the trial, what changes at expiration, which exceptions administrators can create, and how conversion affects the existing account state.

This becomes particularly important when SaaS companies experiment with onboarding.

Changing from a 14-day trial to a seven-day trial is easy. Introducing a product-led trial for some users and a sales-assisted trial for others is considerably harder if trial behavior has been hardcoded throughout the product.

Upgrades are easy until you ask when they happen

"Upgrade plan" sounds like one action. In practice, it contains several decisions.

A customer moves from Starter at $29 per month to Professional at $79 on day 18 of a billing cycle.

Should Professional features become available immediately? Most businesses would say yes. Now consider the money.

Should the customer pay the difference immediately? Should the amount be prorated? Should the billing date change? What happens if the additional payment fails after access has already been granted?

Seat-based subscriptions introduce another layer. If the account moves from 10 to 17 users during the month, billing may need to reflect the additional seven seats without changing the underlying plan.

Annual subscriptions create still more possibilities.

The important architectural concept is that commercial changes and entitlement changes do not always happen at the same moment.

An upgrade may provide immediate access and immediate billing. A downgrade may be requested today but become effective at renewal. A cancellation may stop future billing while allowing access until the paid period ends.

Treating all three as the same "change subscription" operation makes future pricing rules increasingly difficult to implement.

Downgrades are harder than upgrades

Upgrades generally add something. Downgrades take something away. That creates product questions payment systems cannot answer.

Suppose the Professional plan allows 50 projects and Starter allows 10. A customer with 34 existing projects schedules a downgrade.

What happens at renewal?

Deleting 24 projects would be destructive. Preventing the downgrade creates a frustrating billing experience. Keeping all 34 projects fully functional effectively ignores the Starter limit.

The product needs a deliberate policy.

One approach might preserve existing projects but prevent new ones until usage falls below the plan limit. Another might make excess projects read-only. A different SaaS product may require the customer to resolve excess usage before the downgrade can take effect.

The same issue appears with storage, team members, integrations, automation rules, reports, API usage, and practically every plan-based limit.

This is why downgrade logic belongs in architecture discussions early.

The difficult question is not "Can Stripe change the subscription?"

It is "What happens to everything the customer already created when their entitlements become smaller?"

Webhooks are messages, not commands

Stripe communicates many subscription changes through webhooks. Payment succeeded. Invoice failed. Subscription updated. Trial ending. Subscription canceled.

It is tempting to write application logic that assumes each webhook arrives exactly once, in the expected order, at the expected moment. Distributed systems are less cooperative.

Events can be delayed. Delivery can be retried. Processing can fail halfway through. Two related events can arrive close together. Your application may temporarily disagree with Stripe about the latest subscription state.

Billing architecture needs to expect these conditions rather than treat them as exceptional.

Webhook processing should therefore be idempotent: receiving the same event more than once should not repeatedly apply the same business change. Events should be recorded, failures should be observable, and important billing state should be reconcilable when the two systems disagree.

The customer should never receive two months of access because an event was processed twice, or lose access because one event was missed. That reliability layer is largely invisible. Until it fails.

Failed payments need a product policy

Payment failure is one of those situations where technical correctness and customer experience can easily conflict.

From a payment processor’s perspective, the event is straightforward: the charge did not succeed. For a SaaS product, several decisions still remain.

Should access disappear immediately? How many payment retries are allowed? Does the customer receive a grace period? Which functionality remains available during it? Can administrators update billing details without restoring the entire account first?

For a business-critical SaaS platform, immediately locking an organization out because one card expired can create a much larger problem than the failed payment itself.

Failed payments also have a direct impact on revenue. Involuntary churn can account for 20-40% of total subscription churn, while failed payments were projected to cost subscription businesses around $129 billion in 2025. Because these customers did not actively choose to cancel, much of this revenue can potentially be recovered through well-designed retries, grace periods, and account-state rules.

This is why dunning should not exist only inside Stripe settings. The application needs a corresponding account policy.

A typical sequence might include:

1. The payment fails, and the account enters a past-due state.
2. The customer receives a billing notification and an opportunity to update payment details.
3. Automatic retries continue according to the billing policy.
4. Product access changes only when the defined grace period ends.
5. Successful payment restores the appropriate account state without manual intervention.

The exact sequence varies by business model. What matters is that payment state, account state, and product access are deliberately connected rather than treated as the same thing.

Billing history becomes architecture

A young SaaS product might begin with one price. Six months later, the team changes it.

A year later, annual billing arrives. Then there is a new package, a discontinued package, a startup discount, an enterprise agreement, and several customers whose contracts should remain exactly as they were.

At that point, the platform is no longer supporting a pricing model. It is supporting pricing history.

That distinction matters because existing customers should not accidentally inherit every commercial decision made for new customers.

Suppose Professional originally cost $49 and later increases to $69. Some customers may remain grandfathered at $49. Others migrate at renewal. New customers immediately receive the $69 price.

All three groups can still be using "Professional." This is another reason product logic should not depend directly on plan names or current Stripe prices.

A robust billing architecture preserves the relationship between the customer's subscription, the commercial terms under which it was created, and the product capabilities that subscription provides.

Pricing can then evolve without forcing the entire application to evolve with it.

Planning more than 3 pricing tiers?

Codica can turn your pricing rules into billing architecture built for change.

Contact us

Your admin panel is part of the billing system

Not every subscription problem should require an engineer. Yet this happens surprisingly often.

A customer needs a three-day trial extension. Finance wants to confirm why an invoice failed. Support needs to see when a downgrade becomes effective. Sales has negotiated temporary access to an additional feature.

If the only way to handle these situations is to modify the database, open Stripe manually, or ask a developer to run a script, the billing architecture is incomplete.

Internal billing tools deserve planning alongside customer-facing functionality.

Depending on the SaaS model, authorized employees may need to:

• View subscription and payment status.
• Extend or terminate trials.
• Inspect plan changes.
• Apply approved account exceptions.
• Review failed billing events.
• Understand current entitlements.
• See scheduled cancellations or downgrades.

These controls also need boundaries. Support should not necessarily have the same billing permissions as finance, and manual changes should leave an audit trail.

Good billing architecture therefore supports two experiences at once: customers managing their subscriptions and employees managing exceptions safely.

Usage-based pricing changes the question entirely

Seat-based subscriptions are relatively intuitive. A customer has 15 seats and pays for 15 seats.

Usage-based pricing introduces a different architectural problem: the application needs to know what happened before Stripe can know what to charge.

API calls, processed documents, generated reports, storage consumption, AI tokens, transactions, or other billable events must be measured reliably.

That requires decisions about where usage is recorded, how duplicate events are prevented, what happens when reporting fails, when counters reset, and how customers can verify the numbers appearing on their invoices.

Hybrid pricing adds another layer. A SaaS company might charge:

$99 base subscription + five included users + $12 per additional user + usage above 10,000 monthly operations.

The pricing page can still make that model look simple. The underlying system now needs to coordinate subscriptions, entitlements, metering, billing periods, allowances, and overages.

This is why pricing experimentation should involve engineering early. A commercial model that takes five minutes to describe can require substantial changes to the billing system supporting it.

What we define before building SaaS billing at Codica

Billing implementation should not begin with creating products and prices inside Stripe.

At Codica, the more important work happens before those objects are configured. The team needs to understand how the company intends to charge customers and how every commercial event should affect product access.

That means mapping questions such as:

• What subscription states can an account enter?
• Which capabilities belong to each plan?
• When do upgrades and downgrades become effective?
• How should prorations work?
• What survives after a downgrade?
• What happens when payment fails?
• How do trials begin, expire, extend, and convert?
• Which pricing changes affect existing customers?
• Who can make manual billing adjustments?
• Which billing events need to be reflected inside the product?

From there, Stripe integration becomes part of a larger architecture rather than the architecture itself.

This mapping reflects the kind of interconnected product logic we’ve worked with across 100+ delivered SaaS and marketplace products over more than 11 years. It also gives clients a clear view of how commercial rules connect to product access, so the billing system does not become a black box understood only by engineers.

The resulting system can separate payment processing, subscription state, entitlements, and product behavior while keeping them synchronized. That separation becomes increasingly valuable as pricing evolves and the SaaS business introduces new plans, sales models, customer segments, or billing rules.

Test billing with the customers you don't have yet

The obvious billing tests are easy to imagine. A new customer subscribes. Payment succeeds. The correct plan activates. The scenarios worth testing most aggressively are usually less convenient.

What happens when an upgrade payment fails? What if a customer downgrades while exceeding the new plan's limits? What if the same webhook arrives twice? What if an annual customer cancels and reactivates before expiration? What if a trial converts while another subscription update is already being processed?

Billing systems accumulate edge cases because subscriptions exist over time. A useful testing strategy therefore covers transitions, not only individual states.

The goal is not simply to prove that checkout works. It is to prove that an account can move through years of billing changes without its payment status and product access gradually drifting apart.

Good billing architecture makes pricing less scary

A SaaS company should be able to experiment with its commercial model without treating every pricing change like a software migration.

New tiers appear. Trials change. Annual discounts are adjusted. Enterprise customers negotiate exceptions. Usage-based components become commercially attractive. Features move between packages.

Those changes are normal signs of a SaaS business learning how customers value the product. Billing architecture determines how expensive that learning becomes.

When pricing, payments, subscriptions, and entitlements are tightly coupled, every experiment reaches deep into the codebase. When responsibilities are clearly separated, the business has considerably more room to change commercial strategy without destabilizing product access.

Stripe can handle much of the payment infrastructure behind that system. The difficult part remains specific to the product: translating commercial rules into reliable software behavior.

At Codica, we design SaaS billing around those rules rather than around checkout alone, from trials and plan entitlements to upgrades, payment failures, and future pricing changes.

Contact us to discuss the billing architecture behind your SaaS product.