Commerce API · public alpha
The API commerce runs on.
Orders, checkout, subscriptions, refunds by line item, and payouts on the order, so there is nothing to reconcile. One record your developers and your agents both read. Nothing to self-host, no hosting fees.
3.79% + 30¢ on cards · no monthly fee · free sandbox · no credit card
01AI agents
Give agents the order details they need to act.
An amount and a currency do not tell an agent what was sold. Flint orders include line items, tax, balance, and refund state. Money-moving calls include machine-readable hints that describe side effects and human confirmation requirements.
agent_hints · POST /v1/refunds
- Side effect
- Financial
- Human confirmation
- Required
- Idempotent
- Yes, per Idempotency-Key
- Terminal states
- succeeded · failed
What an agent reads on the order
- order.line_items
- order.pricing_amounts.tax_money
- order.settlement_amounts.outstanding_money
- order.refund_status
Agents can read each method’s hints before calling it. The docs MCP server provides endpoint schemas. The CLI MCP server calls the API with your credentials and requires confirmation for destructive operations and sensitive operations in live mode.
Refund the croissant, not the whole order.
a charge-only API cannot: requires commerce data
POST /v1/refunds · line_items[]Add a bag of beans before it ships.
a charge-only API cannot: requires commerce data
POST /v1/orders/{id}/line-itemsIs the dark roast back in stock?
a charge-only API cannot: requires commerce data
GET /v1/inventory-levelsCharge my card $19.43.
a charge-only API can: supported
POST /v1/payment-intentsHas my order shipped yet?
a charge-only API cannot: requires commerce data
GET /v1/orders/{id}What sold best this week?
a charge-only API cannot: requires commerce data
GET /v1/ordersfive of these requests need more than a payment amount: order and inventory data
02Day one
The back office and the checkout are already built.
Flint includes a dashboard for payments, orders, returns, and payouts, a developer console, and hosted checkout with express wallets, cards, bank debit, and Affirm. You build and host your storefront. Flint's apps use the same public API you integrate.
03After the sale
Refund the croissant, not the order.
Refund a line item with one call. Flint recalculates its tax share and updates the order balance. The return workflow records which items came back and whether they can be restocked. Returns, disputes, and subscription renewals stay linked to their orders.
POST /v1/orders2 line items · tax computed201POST /v1/checkout-sessionshosted checkout · pays $19.43201POST /v1/refundsCroissant ×1 · −$5.36201A return, end to end
Renewals bill as orders too, so a subscription refunds like any other sale. Try the billing simulator on the subscriptions page →
04The model
The order is the system of record.
With a charge-only API, you build the cart, calculate totals and tax, and map refunds to items. You also keep your order data in sync with the processor. Flint calculates totals, tax, discounts, and refunds on the order, with one audit trail.
Coming from a payments processor
Flint connects payments, tax, promotions, subscriptions, and refunds to the order. Your application can read the order to get its payment and refund status. Payments API →
Coming from a commerce platform
If your commerce platform requires a separate processor, you integrate it and keep payment and order data in sync. Flint includes commerce and payment processing in one hosted API. Commerce API →
ord_1kmn0aExampleGET /v1/orders/{order_id}
- status · closed
- payment_status · paid
- refund_status · partially_refunded
- total · $19.43
- refunded · $5.36
Checkout, payments, and refunds update the same order. Read it to see what was bought, paid, and refunded.
payment_intentPOST /v1/orders/{order_id}/payment-intents
Collects payment for the order using its outstanding balance.
checkout_sessionPOST /v1/checkout-sessions
Provides hosted checkout for the order.
refundPOST /v1/refunds
Refunds selected line items, including their tax share.
subscriptionPOST /v1/subscriptions
Each renewal is an order, so it reports like any other sale.
disputeGET /v1/disputes
Links the dispute to its payment and order.
payoutGET /v1/payouts
Records payouts in the same transaction ledger as payments.
What you build around a charge-only API.
The cart and order service
POST /v1/ordersTax math, per line item and per refund
order.pricing_amounts.tax_moneyThe nightly job diffing your DB against the processor
GET /v1/balance-transactionsSupport tooling mapping charges back to items
POST /v1/refunds · line_items[]Retries, ordering, idempotency and replay between services
Idempotency-Key · webhook_event_idInventory holds and returned-stock receipts
POST /v1/inventory-reservations · POST /v1/inventory-receiptsreviewed 2026-09-04 against the published API · corrections: support@withflintpay.com
API and developer tools
Settlement runs on Stripe’s rails. The commerce layer is Flint’s.
API samples are validated against the published OpenAPI spec at build time
05Developers
Create an order and collect payment in four steps.
Create an order and a checkout session, send the buyer to checkout, then read the order's payment status from your backend. Use HTTP and JSON, the typed Node SDK, or the CLI. The CLI forwards sandbox webhooks to localhost, and coding agents can read the API's OpenAPI spec.
# 1. compute the totals yourself
subtotal=1795 tax=148 total=1943 # every service must agree
# 2. charge the total
curl -X POST https://api.processor.example/v1/charges \
-u "sk_test_...:" \
-d amount=1943 -d currency=usd # no line items
# 3. build and maintain the supporting services
# the order service, the tax math, the nightly reconcile job,
# refund tooling that maps charges back to items,
# and inventory holds for what came backThe charge records an amount and a currency. You build and maintain the order, tax, reconciliation, refund, and inventory code.
# 1. the order: line items in, totals computed
curl -X POST https://api.withflintpay.com/v1/orders \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{ "line_items": [ ... ] }'
# 2. a hosted page over that order
curl -X POST https://api.withflintpay.com/v1/checkout-sessions \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"order_id": "ord_1kmn0aExample",
"redirects": {
"success_redirect_url": "https://example.com/thanks",
"cancel_redirect_url": "https://example.com/cart"
}
}'
# 3. send the buyer to data.url, exactly as returned
# 4. confirm it from your own backend
curl https://api.withflintpay.com/v1/orders/ord_1kmn0aExample \
-H "Authorization: Bearer YOUR_API_KEY"Your backend reads the order's current payment status in step 4.
Node SDK
CLI
Live sandbox events, to localhost
Connect your coding agent
Add the docs server to Claude Code or Cursor and the tool pulls exact endpoint schemas while it writes the calls. No key is needed to read. The server that acts on your account runs on your machine with your credential, so the key never passes through the agent’s arguments or a third party.
A first prompt
Connect the Flint docs MCP server, then build me a small store that sells three products through a hosted checkout. Create orders on the server with the sandbox key in my environment, pay one with a test card, and show me the paid order at the end.
Public alpha
Alpha accounts get the changes first.
Real merchants take real payments on Flint today. Request and response shapes can still change before beta, with notice, and new features reach alpha accounts before general rollout.
shipped 2026-09-04 · Shared money inputs and inventory tracking names
06Pricing
One all-in processing price.
Your approved Flint agreement sets one all-in processing price, and provider costs are not added later as a separate merchant charge. Flint onboards US businesses today and prices in USD. Buyers’ cards work from anywhere in the world. Full details are on the pricing page.
Developer
$0/mo, forever3.79% + 30¢
cards and wallets · one flat rate, any volume
- ACH 0.70%, min $1, max $700 per payment
- Subscriptions & invoicing 0% platform fee
- Every public API endpoint, including the B2B suite
- Unlimited test mode, unlimited seats
- No processing-volume ceiling, no automatic upgrades
- 20 externally or manually paid orders per month
- One business · community + email support
For developers, side projects, and businesses validating Flint.
free sandbox · no card · keys in minutes
Growth
lower rate3.59% + 30¢
$399/mo, or $299/mo billed annually
- ACH 0.60%, min $1, max $700 per payment
- Subscriptions & invoicing 0% platform fee
- Everything in Developer, at a lower card and ACH rate
- Unlimited externally or manually paid orders
- Priority support, launch review, higher rate limits
- 12-month rate protection with annual billing
- Pays for itself at ~$200k/mo, or ~$150k/mo billed annually
For growing shops and SaaS, ~$100k–$500k/mo. Month-to-month available.
$399/mo · $299 annually · switch anytime
Scale
volume3.39% + 30¢
from $1,499/mo · one-year agreement
- ACH 0.50%, min $1, max $700 per payment
- Subscriptions & invoicing 0% platform fee
- Everything in Growth, at a lower card and ACH rate
- Named technical contact and incident escalation
- 99.95% contractual SLA
- Technical onboarding and payment-rate reviews
- Contract-term rate protection
- Net terms, price lists, quotes, and purchase-order workflows
- Card savings cover the step up from Growth at ~$550k/mo
For high-volume single businesses, ~$400k/mo and up.
a human replies · usually same day
Enterprise
CustomFor multiple businesses and submerchants, platform and marketplace payouts, HIPAA or SOC 2 commitments, data residency, and SCIM. Cards, ACH, payouts, and contract terms are all custom. Tell us what you are running and we will price it.
FAQ
Questions worth asking first.
How can AI agents use Flint?
Agents can read an order's line items, balances, and refund state before acting. API methods include agent_hints describing side-effect levels, idempotency, required scopes, terminal states, and human confirmation requirements. The API uses HTTP and JSON.
Is Flint a Stripe alternative, or built on Stripe?
Flint provides orders, catalog, tax, subscriptions, line-item refunds, and payouts through one API. Settlement runs on Stripe's rails. You integrate with Flint for both commerce and payment processing.
Can I use my own Stripe account with Flint?
Flint provisions its own Stripe-based processing and does not currently support connecting an existing Stripe account. Support is in development; ask sales about its status if your integration depends on it.
Does Flint work for in-person or card-present payments?
Flint does not support card-present payments and has no announced release date for them. You can use hosted checkout for online orders, kiosks, or payments on a guest's phone. If you need a physical reader, use a provider that supports card-present payments.
Can my platform take a cut of its merchants' payments?
No. The API has no application-fee or revenue-share field, so a platform cannot take a share of its merchants’ payments. Platforms on Flint charge for their software instead. If a share of each transaction is your business model, talk to sales before you build.
How is Flint different from a commerce platform like Medusa, Saleor, or commercetools?
Flint includes commerce and payment processing in one hosted API. Payments and refunds update the order, so you can read its current balance and payment status directly. You do not need a separate processor contract or servers to run Flint. You still build and host your storefront.
Do I need to build my own order or cart service if I use a payments API?
With a charge-only API, you build the order and cart service, calculate tax, map refunds to items, and keep your order data in sync with the processor. Flint provides the order service and calculates totals, tax, discounts, and refunds on the order, with one audit trail.
Can I refund a single line item instead of the whole charge?
Yes. Flint refunds against the order, line by line: one POST /v1/refunds with the line items returns the money and recomputes the balance and tax. A Return disposition or inventory receipt separately records whether merchandise can re-enter stock. A charge-only payments API can only refund an amount, so you map charges back to items by hand.
Do I have to adopt the whole order model on day one?
No. Charge a card with one POST /v1/payment-intents call and stop there if that’s all you need. Orders, checkout, subscriptions, and payouts are the same API and the same keys when you want them. No migration, no new account.
Does Flint handle tax and totals?
Yes. You configure the tax policy. Flint calculates totals and tax per line item, recalculates them when the order changes, and includes the item's tax share in refunds.
How do balances and payouts work?
Flint reports available, pending, and reserved balances. Payouts follow the standard schedule, and payments, refunds, and payouts are recorded in one transaction ledger accessible through the API.
Is there an SDK or a CLI?
Yes. @flintpay/node is the TypeScript and JavaScript SDK, and @flintpay/cli is a command-line client where every command maps to a documented /v1 route. The CLI forwards live sandbox webhook events to localhost with flint listen, so you can build against real events without a tunnel, and it exposes the same command surface to AI agents over MCP. The API itself is plain HTTP and JSON, so neither is required.
How do I get started with Flint?
Create an account and grab sandbox keys: free, no credit card, no sales call. Flint is in public alpha and onboards US businesses today. Buyers can pay from anywhere. The quickstart takes you from first order to paid checkout in minutes.
Start with one order.
Free sandbox, no credit card. The record you create today is the same one your dashboard, your buyers, and your agents will read.
Prefer the terminal? npm install -g @flintpay/cli && flint signup creates the account and the sandbox key without leaving it. CLI docs →
POST /v1/orders · create your first order