Stripe

Stripe

Stripe operators run payments, customers, subscriptions, invoices, and treasury workflows. Modern card flows use Payment Intents; recurring revenue ties customers to Prices through Subscriptions.

First moves

1. Account health — balance and recent balance transactions when the user asks about cash on hand or payout timing.
2. Revenue snapshot — account MRR, active subscription counts, and top customers in one pass before paginating every subscription.
3. Payment activity — list recent PaymentIntents or charges when triaging failed checkouts or refund requests.
4. Customer lookup — search customers by name or email, then open customer 360 for lifetime spend, MRR, and subscription status.
5. Subscription triage — list subscriptions and flag past_due or unpaid rows before assuming renewal succeeded.
6. Invoice review — list open or overdue invoices; open one invoice for line items and payment state.
7. Disputes and refunds — list open disputes for evidence deadlines; issue partial or full refunds against captured charges.

Data model

• PaymentIntent (pi_) — primary modern card flow: create, confirm client- or server-side, cancel if abandoned.
• Charge (ch_) — legacy one-time capture; prefer PaymentIntent for SCA-capable flows.
• Customer (cus_) — payer profile with reusable payment methods and metadata; searchable by name or email.
• PaymentMethod (pm_) — tokenized card or bank instrument attached to customers.
• Subscription (sub_) — recurring relationship anchored to a Price; cancel, meter, or change price on renewal.
• Invoice (in_) — billing document: draft → line items → finalize → send or pay; auto-generated for subscriptions.
• Product (prod_) and Price (price_) — catalog primitives; prices are immutable — create a new price for amount changes.
• Coupon and PromotionCode (promo_) — discount rules and customer-facing checkout codes.
• Checkout Session (cs_) — hosted payment page for one-time, subscription, or setup mode.
• Payment Link (plink_) — reusable shareable URL for collecting payments without code.
• Refund (re_) — full or partial reversal of captured funds.
• Balance and Payout (po_) — treasury movement to the bank; cancel only before dispatch.
• Dispute (dp_) — card-network chargebacks with evidence deadlines.
• Event (evt_) and Webhook endpoint (we_) — audit stream and delivery targets for billing sync.

Operational order

1. Start with revenue snapshot or a scoped list (payments, subscriptions, invoices) — do not guess object ids.
2. Search customers, subscriptions, products, or invoices when the user gives a name, email, or metadata hint.
3. Open customer 360 or fetch one object by id before mutating subscriptions, invoices, or payment methods.
4. For checkout issues, trace Checkout Session → PaymentIntent → Charge in that order.
5. Writes that create billable state need confirmation; prefer idempotency keys on creates so retries stay safe.

PaymentIntent flow

1. Create a PaymentIntent with amount, currency, and customer when collecting a one-time payment.
2. Confirm client-side or server-side; watch for requires_action (3D Secure) before treating payment as succeeded.
3. Capture or cancel abandoned intents; issue refunds against the underlying charge if funds already captured.

Prefer PaymentIntent over Charge for new integrations — Charges lack modern SCA handling.

Subscription lifecycle

1. Ensure Product and Price exist (or create them) before starting a subscription.
2. Attach the subscription to a Customer with a default payment method when possible.
3. Monitor status (active, past_due, canceled, unpaid) before reporting renewal health.
4. Price changes require a new Price id — update the subscription item to the new price rather than editing the old price.
5. Cancel at period end vs immediately depending on whether the user should retain access through the paid window.

Invoice lifecycle

1. Draft invoice → add invoice line items → finalize → send or pay.
2. Finalized invoices cannot return to draft; use credit notes or replacement flows to fix buyer details after payment.
3. Open renewal invoices can be credited pre-payment (credit note with reason=order_change, no explicit credit amount) or deferred with a subscription trial extension.
4. Subscription-generated invoices inherit customer tax IDs once the customer record is updated and a new invoice is finalized.

Discounts and checkout

1. Define a Coupon (amount or percent off, duration, optional product scope).
2. Expose it via a PromotionCode or allow manual promo entry on Checkout.
3. Apply coupon or promotion code at subscription create or on a Checkout Session when pre-applying a campaign.

Refunds and disputes

• Refunds — full or partial against captured charges; partial refunds leave remaining balance on the charge.
• Disputes — list open cases, note evidence due dates, and gather proof before the network deadline.
• Payouts — balance must be positive; typical bank delay is several days; cancel only before the payout leaves Stripe.

Webhook delivery debugging

When billing sync lags after checkout:

1. List webhook endpoints and confirm the production destination is enabled.
2. List recent events with failed delivery for types such as checkout.session.completed and payment_intent.succeeded.
3. Open the event by evt_… id and inspect pending webhook counts and delivery status.
4. Per-attempt HTTP status for a destination is visible in the Stripe Dashboard event-delivery UI, not in API payloads.

Search syntax

Customer, invoice, subscription, and product search accept query operators: exact :, fuzzy ~, range > <, combined with AND/OR. Example shape: name~'acme' AND created>1704067200.

Revenue dashboard (MCP App)

Open the Stripe MCP App panel before relying on inline JSON summaries. The revenue snapshot renders account MRR, subscription counts, balance, and top customers; customer 360 renders lifetime spend, MRR, and recent activity for one cus_ id in the same panel.

Gotchas

• PaymentIntent vs Charge — use PaymentIntent for new integrations; Charges are legacy.
• Price is immutable — create a new Price and move the subscription item rather than editing amount on the old price.
• Subscription status — past_due and unpaid mean dunning may still be running; do not report clean renewal.
• Invoice draft vs finalized — add line items before finalize; finalized invoices need credit-note or reissue flows to fix buyer identity.
• Amounts in cents — all monetary amounts use the smallest currency unit (2000 = $20.00 USD).
• Customer tax IDs — set tax_id_type and tax_id_value on the customer before finalizing invoices that must show VAT on the PDF.
• Pagination — list calls return has_more and cursors; advance the cursor when the user asks for more rows.