PaymentIntent is clear for charging money, but thin for everything above it.
Create the business object first, then derive payment collection from it.
What This Page Answers
What actually changes when we stop centering the workflow on PaymentIntents?
The payment intent becomes a linked operation instead of the business record. Orders hold line items, totals, hosted flow linkage, and the post-payment history your application actually needs.
Model change
You are not deleting payments. You are changing what the payment belongs to.
The payment object carries more responsibility than it was meant to.
The payment becomes one operation on the order instead of the whole system.
PaymentIntent-centered apps usually break once the sale needs more than an amount and a status.
At first, a PaymentIntent feels like enough. Then you add real line items, discounts, taxes, hosted flows, partial refunds, customer support, and recurring billing. Now the payment object needs an entire layer of interpretation wrapped around it.
The order-first move is not about ideology. It is about stopping your application from rebuilding the same commerce model on the side because the payment object cannot safely own all of that meaning.
Code shift
The migration begins at the first write
The earlier your code creates the business record, the less reconciliation work you carry through every later step.
const paymentIntent = await stripe.paymentIntents.create({amount: 6384,currency: "usd",metadata: { order_id: "internal_1042" },});// Stripe now knows charge state.// Your app still owns:// - line items// - discounts// - tax math// - refund allocation// - customer-facing order history
const order = await flint.orders.create({line_items: [{ name: "Coffee Beans", quantity: 2,unit_price_money: { amount: 1999, currency: "USD" } },{ name: "Pour-Over Mug", quantity: 1,unit_price_money: { amount: 2400, currency: "USD" } },],discounts: [{ coupon: { coupon_code: "WELCOME10" } }],});// Flint computes totals and keeps the record:// order.net_amounts → subtotal, discount, tax, paid, balance// order.activities → every state change// order.payment_intent_ids, refund_ids, checkout_session_ids
What changes
The order absorbs the work your app was doing around the PaymentIntent
This is the practical shift teams feel in checkout, refunds, and day-two operations.
| Capability | PaymentIntent-led app | Order-first app |
|---|---|---|
Starting object Where workflow begins | PaymentIntent | Order |
Totals Who owns subtotal, discounts, tax, and balance | Application code | Order net amounts |
Checkout session meaning What the hosted page is attached to | A payment attempt and metadata | A specific order workflow |
Refund semantics How support understands what changed | Refund raw money and reconstruct meaning later | Refund against a workflow that already knows the order context |
Support history What operators read | Processor state plus app-specific joins | One order with linked payment and refund state |
The migration is worth doing when the business keeps outgrowing a payment object that was only meant to move money.
This does not require exotic new payment behavior
Flint's public docs still expose the payment intent model. What changes is how that payment intent fits into the broader system: it becomes linked to an order and no longer needs to carry the whole application contract by itself.
That makes the migration lower risk because you are changing the state model above the payment, not inventing a brand-new payment primitive from scratch.
Migration steps
A simple order for the migration
Keep the change narrow enough that the team can see the operational improvement quickly.
Create the order first
Move line items and totals into the order create flow before changing hosted checkout or refund behavior.
Attach hosted checkout to the order
Use checkout sessions or payment links that stay connected to the order instead of inventing new joins around payment metadata.
Move refunds next
Once the order exists, let refunds live against that workflow so post-payment support stops being repair work.
Implementation
Go straight to the model and migration docs
These are the fastest docs to read when the team is deciding whether the order model actually removes enough application glue.
Frequently asked questions
Related Pages
Read the next pages in the order-first migration path
These pages connect the PaymentIntent model shift to checkout, refund, and broader migration decisions.