Skip to content
Otoshek
OTOSHEK · DOCS
DEEP DIVE · BILLINGscheduleRead · 9 min

Stripe Billing Infrastructure

Every generated Otoshek app ships with a complete subscription billing system connected directly to your Stripe account: three plans with monthly and yearly pricing, hosted checkout, a self-service customer portal, and a webhook pipeline that keeps your database in sync with Stripe automatically. This page explains what gets provisioned, how the moving parts fit together, and how to verify that everything is working.

The first half is written for anyone launching a product; the second half goes deeper into webhooks, deployments, and versions for readers who want the engineering detail.

Generated app pricing page showing the six provisioned pricesno source
The pricing page of a generated app — three plans, monthly and yearlyPLACEHOLDER
01

What you get

A working subscription business, wired end to end, in your own cloud and your own Stripe account. These are the four pillars.

01
sell

Three plans, six prices

Starter, Standard, and Premium Products are created in your Stripe sandbox, each with a monthly and a yearly Price. The pricing page renders all six and sends the exact Price ID the customer picked.

02
shopping_cart

Hosted checkout and self-service portal

New subscribers pay through Stripe Checkout. Existing subscribers manage their plan, billing cycle, payment method, and cancellation through the Stripe Customer Portal — no custom payment forms to maintain.

03
database

Billing data mirrored into your database

dj-stripe synchronizes Products, Prices, Customers, PaymentMethods, and Subscriptions into your app's PostgreSQL, so dashboards and feature gates read fast local state instead of calling Stripe on every request.

04
shield_lock

No card data touches your app

Stripe collects and stores payment details. Your app only mirrors safe summaries — card brand, last four digits, expiration — so there is no raw card data in your database, ever.

02

Who does what

The division of responsibility is deliberate: Otoshek automates everything that is mechanical and error-prone, while you keep control of the account, the money, and the go-live decision.

precision_manufacturingOtoshek automates

  • Creates the three Products (Starter, Standard, Premium) in your Stripe sandbox.
  • Creates monthly and yearly Prices for each Product — six in total.
  • Creates the per-app Customer Portal configuration (proration, downgrade timing, and cancellation policy).
  • Passes the Price IDs, Portal configuration ID, and secret configuration into your Azure or GCP infrastructure.
  • Installs the pinned billing dependencies and runs database migrations.
  • Ships the deployment workflow that creates, repairs, and verifies the production webhook endpoint on every push.
  • Ships the synchronization step that mirrors the supported Stripe objects into your PostgreSQL database.

personYou own

  • Creating or selecting the Stripe sandbox and providing its secret key to Otoshek.
  • Keeping that key active in Stripe.
  • Testing checkout and subscription management after deployment.
  • Monitoring GitHub Actions and Stripe Workbench for failed deployments or webhook deliveries.
  • Deciding when and how to move from sandbox to live mode.
  • Coordinating later changes to Products, Prices, plan metadata, or environment variables.
03

The two automation phases

Billing automation happens in two distinct places, and understanding the split explains almost everything about how the system behaves: a one-time provisioning pass that runs inside Otoshek before your infrastructure is deployed, and a repeatable pipeline that lives in your generated repository and runs on every push to main.

Diagram of the two automation phases: one-time provisioning and per-push CI/CDno source
One-time provisioning inside Otoshek, then a repeatable pipeline in your repositoryPLACEHOLDER · DIAGRAM
Phase 1 · ONE-TIME
factory

Otoshek provisioning

ONE-TIME

Runs inside Otoshek before your cloud infrastructure is deployed, using the sandbox secret key you provided.

01

Create Products and Prices

Starter, Standard, and Premium are created in your sandbox, each with a monthly and a yearly Price — six Prices in total.

02

Create the Customer Portal configuration

A per-app portal configuration encodes the billing policy: immediate prorated upgrades, period-end downgrades, and period-end cancellation.

03

Store the IDs in the build configuration

The six Price IDs and the Portal configuration ID are recorded in the per-build configuration bundle.

04

Hand everything to your infrastructure

Terraform and the generated app receive the IDs and secret configuration through Azure or GCP, so the deployed app starts with billing fully wired.

Phase 2 · EVERY PUSH
rocket_launch

Generated repository CI/CD

EVERY PUSH

Lives in your repository's GitHub Actions workflow and runs on every push to main — the first deploy and every one after it.

01

Build and deploy

Installs dependencies, builds the frontend, collects static files, runs database migrations, and deploys to your cloud.

02

Wait for public readiness

The pipeline waits until the public service actually responds before configuring anything that depends on it.

03

Reconcile the webhook

Verifies the Stripe webhook endpoint exists, points at the right URL, and requests the right events — repairing or replacing it if needed.

04

Synchronize Stripe data

Runs the dj-stripe model sync so Products, Prices, Customers, PaymentMethods, and Subscriptions are mirrored into PostgreSQL.

04

The subscription lifecycle

What your customers actually experience: subscribing, upgrading, downgrading, canceling, and changing cards. The pattern throughout is the same — the app initiates, Stripe confirms and charges, and webhooks bring the result back into your database.

Checkout

When a customer picks a plan, the pricing page sends the exact Price ID they selected — including whether it is the monthly or yearly variant — and the backend creates a Stripe Checkout subscription session. Stripe hosts the payment page, so card details never pass through your app. If the customer already has an active subscription, checkout is blocked and they are pointed to the portal instead, which prevents accidental double subscriptions.

After payment, the redirect back into your app gives immediate feedback, but it is only a UX signal. The authoritative confirmation is the checkout.session.completed webhook, which synchronizes the new subscription into your database even if the customer closes the browser tab before the redirect finishes. The dashboard then reads that local record.

Stripe Checkout in test mode for a generated app subscriptionno source
Stripe Checkout — payment details are collected on Stripe, not in your appPLACEHOLDER

Upgrades

The dashboard and pricing page know the customer's exact current Price, so an upgrade opens Stripe's subscription_update_confirm portal flow pre-targeted at the Price the customer chose. The app itself never mutates the subscription — Stripe shows the exact amount, timing, and proration, and only applies the change after the customer confirms it on Stripe's page.

The provisioned Portal configuration uses proration_behavior: always_invoice, so an upgrade takes effect right away and the customer sees the prorated difference before being charged. After confirmation, webhooks update the local database; the dashboard briefly polls after the customer returns from Stripe so the asynchronous sync has time to land.

Stripe portal subscription update confirmation showing the prorated amountno source
The portal confirmation screen — proration is shown before the customer confirmsPLACEHOLDER

Downgrades

Downgrades use the same portal confirmation flow, but the Portal configuration schedules two kinds of changes for the end of the current billing period instead of applying them immediately: moving to a lower-value Price (decreasing_item_amount) and shortening the billing interval, such as yearly to monthly (shortening_interval).

The current plan stays active until the effective date. Stripe represents the pending change as a Subscription Schedule, and the schedule webhook events keep your database aware of it — which is how the dashboard can show both the current plan and the plan it will become at the next billing boundary. The app's labels are explanatory; Stripe remains authoritative for the final timing and charge.

Generated app dashboard showing the current plan and a scheduled downgradeno source
Dashboard with a pending downgrade — current plan plus the scheduled next planPLACEHOLDER

Cancellation

Cancellation goes through the generic Stripe Customer Portal, and the provisioned configuration uses mode: at_period_end. Confirming a cancellation does not remove access — it flips cancel_at_period_end to true on the subscription, which arrives in your database through a customer.subscription.updated event. The dashboard responds by turning its "next billing date" into "subscription ends" messaging.

One detail worth knowing when reading the data: canceled_at records when the cancellation was requested, not when access ends. The subscription stays active until the paid-through date; at the actual period end Stripe sends customer.subscription.deleted, the local status becomes canceled, and entitlement ends. Until then the customer can return to the portal to review or reverse the cancellation.

Dashboard showing subscription-ends messaging after a period-end cancellationno source
After cancellation — access continues until the paid-through datePLACEHOLDER

Payment methods

Checkout and the portal both produce payment-method events — payment_method.attached, updated, automatically_updated (card networks refreshing expiry dates), and detached. dj-stripe stores the PaymentMethod locally, and the dashboard displays the card brand, last four digits, and expiration from that local record.

The app never stores raw card details. Everything sensitive lives in Stripe; your database holds only the display-safe summary.

tuneWhat the portal lets customers do

These capabilities come from the Customer Portal configuration Otoshek provisions for the app — they are policy, not code, so the app doesn't need custom UI for any of them.

CapabilityProvisioned behavior
Update billing detailsName, email, address, and phone
Invoice historyPast invoices are viewable and downloadable
Payment methodsAdd, update, or replace the card on file
Plan changesSwitch between all six generated Prices, including monthly ↔ yearly
CancellationAt period end, with cancellation reasons collected
PausingNot enabled — subscriptions are either active, scheduled to change, or canceled
05

Webhooks and data synchronization

TECHNICAL

Webhooks are how Stripe tells your app what happened — a renewal succeeded, a card expired, a downgrade is scheduled. This section covers how the endpoint is created, how it is kept healthy, and exactly which events the app listens for.

webhookHow the endpoint is created

The app uses dj-stripe's canonical webhook route, /stripe/webhook/<uuid>/, served over HTTPS. Each deployment gets a unique UUID and its own signing secret, and the secret is stored in the local djstripe.WebhookEndpoint record — it never needs to be copied into an environment variable. The UUID makes the endpoint address unique, but authenticity comes from Stripe's signature verification, which dj-stripe performs on every delivery before persisting the Event.

buildKept healthy on every deployment

After each deployment, a reconciliation command verifies the webhook end to end. It is idempotent — a normal push finds a healthy endpoint and changes nothing.

  • Validates the Stripe key and the HTTPS backend URL before touching anything.
  • Ensures the dj-stripe API key is linked to the proper Stripe Account.
  • Reuses a healthy Otoshek-managed endpoint when one exists.
  • Repairs URL, event selection, metadata, status, or description drift in place.
  • Creates a replacement endpoint only when the existing one's API version is incompatible — and verifies the replacement before disabling the obsolete one.
  • Leaves webhook endpoints it does not manage completely alone.
  • Verifies the local and remote configuration match before reporting success, and redacts secrets from any error output.
The full event catalog — 18 eventsexpand_more

The endpoint requests exactly these 18 canonical events. This is the reference to check against Stripe Workbench when debugging deliveries.

AreaEventsWhy they matter
Checkoutcheckout.session.completed
Confirms subscription checkout and ensures the subscription is synchronized independently of the browser redirect.
Customercustomer.updated
Keeps customer billing details and default payment information current.
Subscriptioncustomer.subscription.created customer.subscription.updated customer.subscription.deleted
Tracks creation, plan changes, cancellation scheduling, status changes, and final subscription termination.
Invoicesinvoice.payment_succeeded invoice.payment_failed
Tracks successful renewals and failed recurring payments.
Payment methodspayment_method.attached payment_method.updated payment_method.automatically_updated payment_method.detached
Keeps the dashboard's card summary synchronized.
Subscription schedulessubscription_schedule.aborted subscription_schedule.canceled subscription_schedule.completed subscription_schedule.created subscription_schedule.expiring subscription_schedule.released subscription_schedule.updated
Tracks changes scheduled for a future billing-period boundary, including downgrades and billing-cycle changes.

account_treeWho handles what

dj-stripe owns signature verification, Event storage, and the built-in synchronization of Stripe objects into the database. The app adds small custom handlers only for checkout, subscription lifecycle, and invoice events — and they are deliberately conservative. The subscription created/updated/deleted handlers are observational and do not run a second, competing sync; the invoice handlers refresh the related subscription. No webhook handler ever cancels, upgrades, downgrades, or creates a subscription — customers do that through Stripe, and webhooks only record the outcome.

Stripe Workbench showing webhook deliveries with Delivered status and HTTP 200no source
Stripe Workbench — every delivery should show Delivered with an HTTP 2xx responsePLACEHOLDER
06

Reading a deployment

Every push to main runs the same pipeline, so it helps to know what a run does, what it deliberately never does, and how to interpret a green or red workflow.

repeatEvery push repeats

  • Dependency installation and frontend build
  • Static-file collection
  • Database migrations
  • Cloud deployment
  • Public readiness check
  • Webhook reconciliation and verification
  • Stripe model synchronization

blockA push never

  • Resets your Stripe sandbox
  • Resets your database
  • Recreates Products and Prices
  • Recreates the Customer Portal configuration
  • Duplicates a healthy webhook endpoint
  • Deletes unrelated Stripe endpoints
GitHub Actions run showing the Stripe webhook and sync stepno source
The deployment workflow — the Stripe setup step runs after the app is publicly reachablePLACEHOLDER
07

Verification checklist

After your first deployment — and after any change to plans or billing configuration — walk through this list. Ten minutes with a Stripe test card covers the whole lifecycle.

  • The pricing page shows all six Prices with the correct amounts and intervals.
  • A sandbox checkout completes with a Stripe test card and lands back in the app.
  • Stripe Workbench shows webhook deliveries as Delivered with HTTP 2xx responses.
  • The dashboard shows the exact Product, Price interval, renewal date, and payment-method summary.
  • An upgrade shows the prorated amount in the Stripe portal before you confirm it.
  • A downgrade or yearly-to-monthly change shows a future effective date instead of charging immediately.
  • A cancellation shows continued access until the end of the paid period.
  • GitHub Actions completes its Stripe setup step with a green check.
  • The database contains Product, Price, Customer, PaymentMethod, Subscription, and WebhookEndpoint records (visible in the Django admin).
08

Versions, parity, and ownership

TECHNICAL

The exact dependency and API-version contract the generated app is built against, and what stays true after the repository becomes yours.

package_2The pinned billing contract

The generated backend pins an exact, tested package pair and an explicit Stripe API version. The version comes from djstripe_settings.STRIPE_API_VERSION and is used by the runtime clients and the webhook endpoint alike — the integration never depends on your Stripe account's default API version, so an account-level version change cannot silently alter the app's payload model.

Billing contractPINNED
dj-stripe==2.11.0
stripe==15.3.0
STRIPE_API_VERSION=2026-06-24.dahlia

cloudAzure and GCP parity

Both generated workflows run the same post-deployment sequence — readiness check, webhook reconciliation, model synchronization — and request the same event allowlist. The secret and variable names differ between the Azure and GCP workflows, but the billing behavior is intended to be identical on both clouds.

handshakeThe repository is yours

New apps are generated from the current reference implementation. After generation, the repository is independent: later improvements to Otoshek's templates do not automatically modify previously generated repositories, and pushes to your main branch use the workflow already present in your repository. That independence is the point — your billing stack has no runtime dependency on Otoshek.