Stripe Integration
How DevStride uses Stripe now that DevStride runs billing, what the Stripe webhook still does, and the ds stripe CLI: a read-only billing inventory and test-mode proofs of the Stripe behaviour billing relies on.
Stripe Integration#
DevStride runs its own billing: it decides who is on trial, who pays, what they pay and who is locked. Stripe keeps the cards, processes the payments and stores the payment history. The ds stripe CLI (cli/commands/stripe.ts) wraps two commands: a read-only inventory of what Stripe holds for every customer, and test-mode proofs of the Stripe behaviour DevStride's billing relies on. It is a thin operational tool, not a sync engine — each command does one specific thing, and neither runs on a schedule.
Where billing stands
- Every workspace is billed by DevStride. Stripe holds no subscriptions: the old Stripe subscription code, the plan cards and the Subscription Tier page were removed (I13245). New workspaces start on a DevStride trial and enrol for monthly card payments themselves.
- Charging: DevStride charges a card customer's saved card directly on the bill day, with no Stripe invoice. Annual, invoice and ACH customers are invoiced by staff in QuickBooks. Automatic charging (
BILLING_AUTO_CHARGE) and trial expiry (BILLING_TRIAL_EXPIRY) areonon every stage, production included; staff can also charge one customer from the staff Billing page.- Refunds: staff refund a card payment, in full or in part, from the staff Billing page; the request is sent to Stripe once, however often it is pressed. A refund made directly in the Stripe dashboard is recorded too, through the webhook below.
- The webhook now acts only on a payment's refunds:
charge.refunded,charge.refund.updatedandrefund.updated(Stripe sends the last one for every refund, so subscribe to it). Anything else Stripe sends is logged and acknowledged.Commands this page used to document are gone:
add-products(the products it created were the old plan cards),create-customersandfind-subscription-quantity.
Prerequisites
ds stripegoes through the standard AWS SSO gate before running. Each command then calls the Stripe API directly with its own key, named below; the stage's ownSTRIPE_SECRET_KEYlives in.env— written byds secrets pull, or filled in by hand before the secrets bundles exist — and is pushed up withds script set-config— see Getting Started.
Billing Inventory#
ds -b stripe billing-inventory --out <directory outside the repository>
What It Does#
Exports, read-only, everything Stripe holds for every customer beside DevStride's own view of the same customer — the census the billing migration is planned from, and the check run again before the old subscription code is deleted. Every Stripe call it makes is a list; it changes nothing, in Stripe or in DevStride.
It writes one row per billable organization to inventory.csv, plus the raw records it read as JSON Lines: organizations.jsonl, subscriptions.jsonl, customers.jsonl, unsettled-invoices.jsonl, pending-invoice-items.jsonl and catalogue.jsonl.
inventory.csv puts DevStride's stored status, seats and price beside Stripe's, compares seat counts three ways (stored, recomputed, Stripe), and carries renewal and trial dates, hand-extended trials, paused collection, the latest invoice status, scheduled changes in words, whichever payment method Stripe would actually charge, the invoice email, and a note column naming anything a person needs to look at.
It refuses a full secret key, and refuses to write inside the repository
The export needs
STRIPE_INVENTORY_KEY— an agent credential, kept in the agent secrets bundle and written byds secrets pullto~/.config/devstride/agent.env, never into.env(a key exported in your shell wins) — and that must be a restricted key (rk_…) with read access only — a fullsk_…secret key is rejected.--outmust also resolve outside this repository: the files hold customer names, invoice emails and negotiated prices, and the repo has no ignore rule for them. Do not work around either refusal.
The files are written readable by you alone, and the command will not follow a symlink or write into a directory that resolves inside the repository. In inventory.csv, any name or email beginning with =, +, - or @ carries a leading apostrophe so a spreadsheet cannot execute it as a formula.
Match the key to the stage
A test-mode key pointed at production organizations joins nothing: every row reads "Stripe customer not found in this Stripe account", which looks alarming and only means the wrong key.
When to run:
- Taking a census of real billing state before changing anything
- Re-checking that census before the old Stripe subscription code is removed
Prove Invoice Flow#
ds -b stripe prove-invoice-flow
What It Does#
Runs Stripe test-mode proofs of the behaviour DevStride's billing relies on, on the pinned Stripe SDK and API version rather than assumed, and prints PASS or FAIL for each claim. The groups cover direct card charges made through DevStride's own charging code (an off-session charge of the saved card, one payment per idempotency key, a decline read as the customer's to fix, finding a payment again by its metadata, and the receipt Billing History shows), staff refunds (a refund request made once however often it is replayed, the payment read back with its refund and the request that made it, and Stripe refusing more than is left), plus one-off invoices and subscription cancellation. The invoice groups document the design that direct card charging replaced and are kept as the record of what was measured.
It needs STRIPE_PROOF_KEY, a test-mode key, and refuses a live key outright. It is not kept in any secrets bundle, because the command writes; the STRIPE_SECRET_KEY already in your .env is a test-mode key, so STRIPE_PROOF_KEY="$STRIPE_SECRET_KEY" is enough. The customers it creates are deleted and its product and price archived at the end, even when a proof fails; a clean-up that fails makes the run fail and names what was left behind.
When to run: before relying on one of these Stripe behaviours in a change, or after a Stripe SDK or API version bump.
Next Steps#
- Maintenance & Codebase Checks —
ds scriptone-off and maintenance commands - Getting Started — Setting
STRIPE_SECRET_KEYand other.envvalues, and the webhook events to subscribe to - Subscription & Billing — what customers see