Connect Stripe

Farther Shore uses your Stripe account to settle: subscriptions, recurring fees, invoices for amount due, prepaid top-up payments, refunds, and tax. The business program is the source of truth for plan economics; the platform's rating engine and ledger are the source of truth for what a subscriber owes. Stripe never rates usage, never owns a subscriber balance, and never receives per-unit usage.

Human setup#

An organization owner connects and verifies Stripe from the signed-in dashboard. This browser flow establishes provider ownership and account requirements; it is not a CLI automation step.

Publishing currently requires a verified Stripe connection even for a free-only business. Complete setup before the first production publish.

What the platform creates#

When a release is published, Farther Shore materializes the subscription and recurring-price identities the release needs in Stripe. Usage pricing, funding buckets, and allowances have no Stripe counterpart: they are rated and allocated locally and reach Stripe only as amount due on an invoice or as a top-up payment.

Your application initiates checkout through the Farther Shore frontend SDK or API and reads subscription state from Farther Shore. Do not create a parallel Stripe product/price model for the same plan.

Initial prepaid plan purchase uses the same managed plan checkout. A later refill is a subscriber-portal operation: implement the public fs.core() handoff in the prepaid wallet cookbook, which targets the documented top-up endpoint. There is no builder CLI or MCP mutation for a subscriber's purchase.

What stays in your code#

Author these in business/:

• plan kinds, recurring prices, and trials;
• pricing catalogs (rates, tiers, modifiers, backend-quoted bounds);
• funding buckets and their display; disclosure and exhaustion policy;
• meter-route bindings and admission bounds.

Do not put Stripe credentials, connected-account ids, price ids, or webhook secrets in the business program.

How Stripe events are treated#

Every Stripe webhook is an input to a ledger posting, idempotent on the Stripe event id — never a direct balance mutation. Core is the single monetary writer for a subject.

• A top-up payment moves a prepaid bucket pending → available; the gateway reserves only against available value.
• A refund drains buckets first (prepaid → rail-refundable; promo, referral, and included value are restored only if unexpired, else written off).
• A rail-initiated refund or dispute that matches no expected local operation moves the settlement account to RECONCILIATION_REQUIRED, which the gateway treats as a monetary admission denial until scheduled reconciliation clears it.

Read Ledger & settlement for the posting templates and reconciliation checks.

Operational checks#

Before a production release:

1. Build and inspect farthershore commercial-release diff <from-release.json> <to-release.json>.
2. Push the reviewed commit and inspect its production Apply Timeline.
3. Verify the organization payments connection in the dashboard.
4. In a preview environment, test checkout, a top-up (prepaid plans), a metered request, the bill preview, and cancellation.
5. Confirm the business status and Apply Timeline after publish.

Use farthershore business publish only for first activation while the repository-managed business is still DRAFT. Later production releases are GitHub Releases for an exact reviewed commit; active businesses reject the publish command, including dry-run, with MANAGED_BY_CODE.

Stripe events are asynchronous. A checkout redirect is not proof that the subscription is active or that a top-up is available; wait for the platform's durable state.

Ownership boundary#

Stripe owns payment-method collection, invoices, tax, and payouts. Farther Shore owns rating, funding allocation, the ledger, and the mapping from the compiled release to settlement objects. Your backend owns only its domain data and the measurements it is authorized to report.

Continue with Subscriptions and usage and Plan changes.