Payment links vs checkout sessions vs invoices
Flint has three hosted ways to collect a payment. Each one pays an order, so refunds, receipts, disputes, payouts, and reporting work the same whichever you use. What differs is who opens the URL and when the money is due.
| Use | When | What you get |
|---|---|---|
| Payment link | Anyone with the URL can buy the same offer. | One URL that never changes. Each buyer who opens it gets their own checkout and order. |
| Checkout session | Your app knows what one buyer is paying for, and they pay now. | A checkout for one order that expires within 24 hours. |
| Invoice | A customer owes an amount they'll pay later, in parts, or offline. | A numbered bill with a due date, a payment page, reminders, and a PDF. |
Choose in two questions#
1. Will more than one buyer open the same URL? Use a payment link. A checkout session pays one order and ends when it's paid, and an invoice bills one customer.
2. Is the money due now? If the buyer is paying now, in your app or a flow you control, use a checkout session. If you're sending a bill that's due on a date, may arrive in parts or by check or wire, and needs a record of what's still owed, use an invoice.
| You're building | Use |
|---|---|
| A buy button on your website, or a QR code on packaging or a flyer | Payment link |
| A pricing page where each plan starts a subscription | Payment link, one per plan |
| A donation page, or an event selling tickets in tiers | Payment link |
| The checkout button in your own app or storefront | Checkout session |
| An upgrade for a signed-in customer | Checkout session |
| A charge for a quote the buyer just accepted | Checkout session |
| Net 30 billing for consulting or wholesale | Invoice |
| A bill that the customer's accounts payable team pays by ACH, check, or wire | Invoice |
| A deposit when work is booked and the balance when it's done | Invoice with a payment schedule |
Compare them#
| Payment link | Checkout session | Invoice | |
|---|---|---|---|
| What it is | A reusable offer | One checkout for one order | A bill a customer owes |
| Create it from | Line items, a donation, ticket tiers, or a plan | An order, a quick pay item, or a plan | An order, or quick pay line items |
| The URL | url, shared by every buyer | url, for this session only | public_url, once issued |
| Lasts | Until you deactivate it | Up to 24 hours | Until it's paid, voided, written off, or credited |
| Orders | A new one per buyer | One | One |
| Subscriptions | Yes | Yes | No |
| Due date | No | No | Yes, with is_overdue |
| Paying in parts | No | No | Yes, including deposits and installments |
| Offline payments | No | No | Yes |
| Emails and reminders | No | No | Yes |
| Flint fees | Processing fee | Processing fee | Processing fee, plus a 0.40% invoice collection fee on each payment Flint collects |
| No | No | Yes | |
| Stop it | Deactivate it | Close it while open | Void it while draft or open |
| Fulfill from | order.paid | order.paid | order.paid |
Fees are at published rates. A payment that starts or renews a subscription carries a 0.40% subscription collection fee instead, on any of the three. An order with automatic tax adds 0.50% on any of them. A payment you record as paid outside Flint carries no fee. See Add-on fees.
Their statuses:
| Object | status values |
|---|---|
| Payment link | active, inactive |
| Checkout session | open, paid, partially_paid, expired, closed, invalidated |
| Invoice | draft, open, partially_paid, paid, void, uncollectible, credited |
Where the payment lands#
Every surface collects through checkout sessions and settles an order:
| Surface | Collects through | Settles |
|---|---|---|
| Payment link | A new checkout session for each buyer, with type: "payment_link" and the link's payment_link_id | A new order for each buyer, with origin: "payment_link" and the link's metadata |
| Checkout session | The session you create, with type order, quick_pay, or subscription_plan | The order you pass, or one Flint creates for quick pay or a plan |
| Invoice | A checkout session for each online payment, with type: "invoice" and the invoice_id, or a manual payment you record | The invoice's order |
Because the order is the shared record, using more than one surface doesn't split your books:
- One place to reconcile.
GET /v1/orderslists orders from all three. Addorigin=payment_linkfor link sales, useGET /v1/checkout-sessions?payment_link_id=...to see what one link sold, andGET /v1/invoices?order_id=...finds the invoice for an order. - Mix them. A payment link on your pricing page, checkout sessions in your app, and invoices for larger accounts can all run at once.
- Add one later. Orders from the surface you start with sit beside the orders from the one you add, so nothing needs migrating.
Sell workshop seats three ways#
The same $120 workshop seat, sold through each surface. Amounts are integers in the currency's minor unit, so 12000 is $120.00.
One call creates the offer:
curl -X POST https://api.withflintpay.com/v1/payment-links \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: workshop-link-001" \
-d '{
"name": "Letterpress Workshop",
"line_items": [{
"type": "custom_fixed",
"key": "seat",
"name": "Workshop seat",
"unit_price_money": {"amount": 12000, "currency": "USD"}
}],
"buyer_fields": {"require_email": true}
}'
Abridged response:
{
"data": {
"payment_link_id": "pl_01K4WORKSHOP",
"url": "https://checkout.withflintpay.com/pay/pl_01K4WORKSHOP",
"status": "active",
"completed_count": 0
}
}
Share data.url on your website, in an email, or behind a QR code. Each buyer who opens it gets their own checkout, and each completed checkout creates an order with origin: "payment_link". The link keeps selling until you deactivate it or it reaches max_completions.
Choose it when seats go on sale to the public.
Create the order, then a checkout for it:
curl -X POST https://api.withflintpay.com/v1/orders \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: workshop-order-001" \
-d '{
"line_items": [{
"type": "custom",
"name": "Workshop seat",
"quantity": 1,
"unit_price_money": {"amount": 12000, "currency": "USD"},
"fulfillment": {"requirement": "none"}
}]
}'
A line item without a catalog variant_id must say whether it ships. A seat doesn't, so it sends "requirement": "none"; leaving fulfillment out returns 400 INVALID_REQUEST with param naming the line item's fulfillment.
curl -X POST https://api.withflintpay.com/v1/checkout-sessions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: workshop-checkout-001" \
-d '{
"type": "order",
"order_id": "ord_01K4WORKSHOP",
"redirects": {
"success_url": "https://example.com/thanks",
"cancel_url": "https://example.com/workshop"
}
}'
Abridged response:
{
"data": {
"checkout_session_id": "cs_01K4WORKSHOP",
"status": "open",
"order_id": "ord_01K4WORKSHOP",
"expires_at": "2026-10-14T15:54:32Z",
"url": "https://checkout.withflintpay.com/checkout/cs_01K4WORKSHOP#checkout_token=cklt_v1...",
"checkout_auth_token": "ckat_v1..."
}
}
Redirect the buyer to data.url exactly as returned; the #checkout_token fragment opens their checkout. Without an order to model, send quick_pay_item with a name and amount_money instead of order_id, and Flint creates the order in the same call.
Choose it when a buyer clicks Register in your app.
Bill the customer for three seats. quick_pay creates the order:
curl -X POST https://api.withflintpay.com/v1/invoices \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: workshop-invoice-001" \
-d '{
"type": "quick_pay",
"quick_pay": {
"customer_id": "cus_01K4NORTHWIND",
"line_items": [{
"type": "custom",
"name": "Workshop seat",
"quantity": 3,
"unit_price_money": {"amount": 12000, "currency": "USD"},
"fulfillment": {"requirement": "none"}
}]
},
"collection": {
"mode": "buyer_initiated",
"payment_policy": {"enabled_payment_options": ["card", "ach_debit"]}
},
"payment_due": {"type": "date", "due_date": "2026-11-15"},
"recipient_email": "ap@example.com",
"memo": "Net 30"
}'
The invoice starts as a draft. Issue it to number it, freeze what it bills, and email it to recipient_email:
curl -X POST https://api.withflintpay.com/v1/invoices/inv_01K4WORKSHOP/issue \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: workshop-invoice-issue-001" \
-d '{"delivery_mode": "email"}'
Abridged response:
{
"data": {
"invoice_id": "inv_01K4WORKSHOP",
"status": "open",
"due_date": "2026-11-15",
"outstanding_money": {"amount": 36000, "currency": "USD"},
"is_overdue": false,
"public_url": "https://checkout.withflintpay.com/i/inv_01K4WORKSHOP#invoice_token=ivt_..."
}
}
The customer pays from the email or from public_url by card or ACH debit. To send the invoice yourself, issue it with "delivery_mode": "caller_managed" and share public_url.
When a check arrives instead, record it:
curl -X POST https://api.withflintpay.com/v1/invoices/inv_01K4WORKSHOP/manual-payments \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: inv-workshop-check-1042" \
-d '{
"amount_money": {"amount": 12000, "currency": "USD"},
"payment_reference": "check-1042",
"note": "Check #1042"
}'
The response holds the recorded payment and the updated invoice, abridged:
{
"data": {
"invoice_manual_payment": {
"invoice_manual_payment_id": "omp_01K4WORKSHOP",
"invoice_id": "inv_01K4WORKSHOP",
"amount_money": {"amount": 12000, "currency": "USD"},
"payment_reference": "check-1042",
"status": "recorded"
},
"invoice": {
"invoice_id": "inv_01K4WORKSHOP",
"status": "partially_paid",
"paid_money": {"amount": 12000, "currency": "USD"},
"outstanding_money": {"amount": 24000, "currency": "USD"}
}
}
}
The customer can pay the remaining $240.00 from the same page. If the check bounces, reverse it with POST /v1/invoices/{invoice_id}/manual-payments/{invoice_manual_payment_id}/reverse, and the $120.00 returns to the balance.
Choose it when a company registers its team and pays through accounts payable.
Harder choices#
Subscriptions: a link or a session#
Payment links and checkout sessions both take subscription_plan_id, and the choice follows the same first question. A public pricing page wants a subscription signup link per plan. An upgrade for a signed-in customer wants a session with type: "subscription_plan", which can name them with customer_id and fill in their details with prefill. A link can't, because anyone can open it.
Invoices don't bill on a schedule. Each one is a single bill, and recurring charges belong to a subscription plan, which charges each renewal without new API calls from you.
Paying later: an invoice, not a session#
A checkout session lasts at most 24 hours, and your checkout settings can shorten it. That's a window for paying now. When payment might arrive next week, in pieces, or as a check, create an invoice: it has a due date, reminders, and an outstanding_money balance that answers "how much is still owed?"
Quick pay on sessions and invoices#
quick_pay_item on a session and quick_pay on an invoice both create the order for you, so whether you already have an order doesn't decide anything. Decide by when the money is due: now is a session, and a bill is an invoice.
A deposit now and the balance later#
An invoice can split its total into a payment schedule. This one asks for 25% when you issue it and the rest on the due date:
{
"payment_due": {"type": "date", "due_date": "2026-12-15"},
"schedule_entries": [
{
"kind": "deposit",
"amount_specification": {"type": "percentage", "percent": 25},
"due": {"type": "at_issue"}
},
{
"kind": "balance",
"amount_specification": {"type": "remaining_balance"},
"due": {"type": "invoice_due_date"}
}
]
}
The entries split the invoice total, tip included. Each installment collects the unpaid tip first, up to its amount, then items and charges, so the tip is usually collected with the deposit.
An invoice that calculates tax automatically can't be split this way; see Tax on an invoice. Stripe deposits and remaining balances compares this schedule with Stripe's payment plans and saved-card charges.
You can also take the deposit through a payment link or checkout session and bill the balance with a separate quick pay invoice. That makes two orders. You can't invoice the deposit's order: an invoice needs an unpaid order, and one with a payment returns 409 ACTION_NOT_ALLOWED with reason payment_collected.
An invoice owns its order#
From the moment you create an invoice, even as a draft, only the invoice can collect its order. A checkout session for that order returns 409 RESOURCE_IN_USE, with the invoice in details[0].blocking_resources. Collect through the invoice instead:
- The hosted page at
public_url, orPOST /v1/invoices/{invoice_id}/checkout-sessionsto start the invoice's checkout yourself. POST /v1/invoices/{invoice_id}/collectto charge a saved card, for invoices withcollection.modeset toautomatic.POST /v1/invoices/{invoice_id}/manual-paymentsto record a check, wire, or cash.
To move an unpaid checkout to an invoice, close the order's open session before you create the invoice. Voiding the invoice releases the order, but only a draft or open invoice can be voided. Marking an invoice uncollectible writes off its balance and closes the order with closed_reason: "written_off".
Fulfill from webhooks#
The buyer's redirect is for the buyer: they can close the tab before it loads, and anyone can open your success URL. Fulfill from webhooks or a read from your backend. One webhook endpoint covers all three surfaces:
Pick one trigger per sale. order.paid covers every surface without fulfilling twice:
curl -X POST https://api.withflintpay.com/v1/webhook-endpoints \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: webhook-fulfillment-001" \
-d '{
"url": "https://example.com/webhooks/flint",
"enabled_events": ["order.paid"],
"description": "Fulfillment for links, sessions, and invoices"
}'
To tell surfaces apart, read the order: origin is payment_link for link sales, GET /v1/checkout-sessions?order_id=... returns the session with its type and its payment_link_id or invoice_id, and GET /v1/invoices?order_id=... finds the invoice. Webhooks covers signature checks and retries.
Errors#
Common mistakes#
- Sending one checkout session URL to many buyers. A session pays one order. The first buyer to pay ends it, and everyone after them finds a checkout that's no longer open. A shared URL is a payment link.
- Creating a payment link per customer to collect a balance. A link doesn't know who owes what. Nothing tracks the balance, sends reminders, or records the check when it arrives. Use an invoice.
- Using invoices for recurring billing. An invoice bills once. Put recurring revenue on a subscription plan and sign customers up through a link or session.
- Collecting an invoiced order with a generic checkout session. It returns
RESOURCE_IN_USE. Use the invoice'spublic_urlorPOST /v1/invoices/{invoice_id}/checkout-sessions. - Fulfilling from the redirect. Buyers close tabs, and anyone can open a success URL. Fulfill from webhooks.
Related docs#
- Payment links: reusable checkout URLs for products, donations, events, and signups.
- Checkout sessions: one hosted or embedded checkout for one order.
- Invoicing: drafts, issuing, reminders, offline payments, late fees, and PDFs.
- Why Flint is orders-first: the order all three surfaces pay.
- Subscription billing: plans, trials, and renewals behind signup links and plan sessions.
- Webhooks: receive and verify the events that drive fulfillment.
- Payment Links API, Checkout Sessions API, Invoices API: every field on every endpoint.
