Skip to content
flint

Ecommerce

Everything after Buyis already built.

Your storefront is what buyers see, so build that. Flint is the rest of the store: a checkout that quotes shipping and tax, stock held while the buyer pays, tracking email, a buyer account, returns by mail, and refunds to the line item. It all runs on the order your storefront creates.

Get free API keys
Accept your first payment

503

API operations behind your storefront

counted from the OpenAPI spec

6

kinds of buyer email sent for you

customer_email_delivery

$0

monthly platform fee to start

free sandbox · no card · keys in minutes

01The store

Buyers ask five questions. None is about the card.

A payment API answers whether the card worked. Everything else a buyer wants to know lands in your inbox, unless the store answers first.

  1. 01

    How much is shipping to me?

    The checkout takes the address, quotes your shipping methods against it, and shows the total with shipping and tax before the buyer pays.

    see checkout
  2. 02

    Is it still in stock?

    Read what is available for any variant at any location. Paying holds the unit, so the number on your product page is one you can sell.

    see stock
  3. 03

    Did my order go through?

    A receipt is emailed when the order is paid, with the line items, shipping, and tax taken from the order itself.

    see delivery
  4. 04

    Where is my order?

    Marking the parcel shipped emails the tracking number, and the buyer follows it from their account without writing to you.

    see delivery
  5. 05

    Can I send this back?

    The buyer opens the order in their account and picks the item. The return policy you wrote decides it, and the refund is computed from the line item.

    see returns

On a store built around a charge, each of these is an app to buy or a system to write, and a join to keep running between them. Here all five read and write the order your storefront created with one call.

02Checkout

Shipping and tax are priced before the buyer pays.

Send the cart as line items and redirect. The checkout collects the address, quotes shipping from your rules, recomputes tax, and shows the final total, under your name.

What your storefront sends
# 1. the cart, by variant. prices and tax rules come from your catalog
curl -X POST https://api.withflintpay.com/v1/orders \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: order-cart-7f3a" \
  -d '{
    "customer_id": "cus_1kmn0aExample",
    "line_items": [
      { "variant_id": "var_1kmn0aExample", "quantity": 1 },
      { "variant_id": "var_2kmn0aExample", "quantity": 1 },
      { "variant_id": "var_3kmn0aExample", "quantity": 1 }
    ],
    "inventory_routing_source": {
      "type": "fixed_location",
      "location_id": "loc_1kmn0aExample"
    }
  }'

# 2. the checkout. redirect the buyer to checkout_access.hosted_url
curl -X POST https://api.withflintpay.com/v1/checkout-sessions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: checkout-cart-7f3a" \
  -d '{ "order_id": "ord_1kmn0aExample" }'

Variants and quantities. Prices, tax rules, and stock tracking come from your catalog, so the browser never supplies a number.

A shipping method, created once
curl -X POST https://api.withflintpay.com/v1/delivery-methods \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: create-standard-shipping" \
  -d '{
    "name": "Standard shipping",
    "type": "shipment",
    "status": "active",
    "configuration": {
      "origin": {
        "type": "fixed_location",
        "location_id": "loc_1kmn0aExample"
      },
      "pricing": {
        "type": "fixed",
        "fixed": {
          "currency_options": {
            "USD": { "amount": 600, "currency": "USD" }
          }
        }
      }
    }
  }'

Save it as a checkout default and every checkout offers it. The buyer's choice adds its charge to the order and the total updates before payment.

Price shipping your way: a flat rate, a rate table, tiers, or a live rate returned by your own endpoint.

POST /v1/delivery-methods

Zones decide where each method is offered. Pickup and local delivery are methods too.

POST /v1/delivery-zones

Sales tax is calculated on the order and recorded per line item, so a later refund returns the right share.

pricing_amounts.tax_money

Cards, Apple Pay, Google Pay, and bank debit on one page, with saved cards for a buyer who is signed in to your store.

customer_id

Automatic discounts price in before the checkout opens, and promotion codes apply at checkout.

POST /v1/promotions
  • POST /v1/checkout-sessions
  • POST /v1/delivery-methods
  • POST /v1/delivery-zones
  • POST /v1/delivery-rate-callbacks
  • pricing_amounts.tax_money

The shipping guide sets this up in three calls. Every payment method, session state, and config option is on the checkout page.

03Stock

The last one sells once.

A tracked variant claims its stock when the buyer pays, commits it when the payment succeeds, and releases it if the payment fails. If no location can serve the order, the payment fails before any money moves.

Ceramic dripper · Brooklyn warehousepayingpaidshipped
On handon_hand_quantity252524
Heldheld_quantity100
Committedcommitted_quantity010
Available to sellavailable_quantity242424
One sale from a shelf of 25, read from one inventory level. The unit stops being available the moment it is held, and leaves the shelf when the parcel is handed to the carrier.

Set where an order ships from and paying it does the rest. There is no decrement to write.

inventory_routing_source

Sell from several locations with a routing policy that ranks them and splits an order only when it has to.

POST /v1/inventory-allocation-policies

Keep a buffer per location that is never sold.

safety_stock_quantity

Receiving, counts, transfers, damage, and loss are recorded as what happened, so every quantity has a history.

POST /v1/inventory-adjustments

Two variants can share one pool, so a gift set and its single item never disagree about what is left.

inventory_item_id
  • inventory_routing_source
  • inventory_reservation_id
  • GET /v1/inventory-levels
  • POST /v1/inventory-allocation-policies
  • inventory.level.updated

The inventory guide follows one unit from the receiving dock to a paid, shipped order.

04Delivery

Ship it, and the buyer hears about it.

Record the parcel and its tracking number, then mark it shipped. The buyer is emailed, the units leave your stock, and the parcel shows up in their account.

Ship the order
curl -X POST https://api.withflintpay.com/v1/orders/ord_1kmn0aExample/fulfillments \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: ship-order-7f3a" \
  -d '{
    "type": "shipment",
    "line_items": [
      { "order_line_item_id": "li_1kmn0aExample", "quantity": 1 },
      { "order_line_item_id": "li_2kmn0aExample", "quantity": 1 },
      { "order_line_item_id": "li_3kmn0aExample", "quantity": 1 }
    ],
    "shipment": {
      "packaging": "single_package",
      "package": {
        "carrier": "usps",
        "tracking_number": "9400100000000000000000",
        "buyer_notification_behavior": "send"
      }
    }
  }'

# when the carrier picks it up
curl -X POST https://api.withflintpay.com/v1/packages/pkg_1kmn0aExample/transitions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{ "action": "mark_shipped" }'

Call it from your warehouse tool or your 3PL's webhook. A partial shipment lists only the lines that went out, and the order reads as partially fulfilled until the rest follow.

What the buyer watches the parcel do

  • packed
  • shipped
  • in_transit
  • out_for_delivery
  • delivered

Receipts, shipping updates, return updates, and three more families of buyer email are sent for you, in your colors and with your logo.

customer_email_delivery

Buyers track parcels, start returns, and manage saved cards in an account that exists on day one.

account.withflintpay.com

Pickup, local delivery, and digital goods run on the same fulfillment record as a shipped parcel.

GET /v1/fulfillments

Your site is told about every step, from packed to delivered.

order.fulfillment.status_changed

Email sent for you

  • order_receipts
  • fulfillment_updates
  • subscription_lifecycle
  • dunning
  • returns
  • invoices

The buyer account, its branding, and the API for building your own are on the customer accounts page.

05Returns

Returns run on rules, not on your inbox.

Write the policy once: the window, who pays return shipping, when the money goes back. Buyers start the return from their account, approval follows the policy, and the refund is computed from the line item.

The whole policy
curl -X POST https://api.withflintpay.com/v1/return-policies \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: policy-standard-001" \
  -d '{
    "name": "Standard returns",
    "revision": {
      "priority": 100,
      "scope": { "match_type": "all" },
      "eligibility_result": "eligible",
      "return_window": {
        "duration_seconds": 2592000,
        "starts_at_event": "delivered"
      },
      "allowed_resolution_types": ["refund", "exchange"],
      "approval_mode": "automatic",
      "resolution_mode": "manual",
      "completion_mode": "automatic",
      "receipt_disposition_mode": "automatic",
      "refund_timing": "after_receipt",
      "is_merchandise_return_required": true,
      "is_inspection_required": false,
      "receiving_location_id": "loc_1kmn0aExample",
      "return_shipping": { "payer": "buyer" }
    }
  }'

Everything is returnable for 30 days from delivery, approval is automatic, the buyer pays return shipping, and the refund goes out when the parcel arrives. A received unit goes back on sale at the location you named.

ret_1kmn0aExample1 × Ceramic dripper
  • The decisiondecision_statusapproved
  • The merchandisemerchandise_statusresolved
  • The valueresolution_statusfulfilled
ord_1kmn0aExampledeliveredreturned
Whole-bean coffee$16.00$16.00
Ceramic dripper$24.00$24.00
Filter papers$9.00$9.00
Standard shipping$6.00$6.00
Taxtax_money$4.04$4.04
Totaltotal_money$59.04$59.04
Refundedrefunded_money$0.00$25.98
Drippers on handon_hand_quantity2425
Returning the dripper refunds $25.98: its $24.00 plus its $1.98 share of the tax. The unit is back on the shelf because the return recorded where it went, and nobody did the math.

Final sale

A higher-priority policy scoped to a product or category marks it ineligible, so clearance stock stays sold.

Exchanges

Swap for another size or variant on the same return. If the new item costs more, the buyer pays the difference on a hosted checkout.

Keep it

Approve a refund with nothing to send back when return shipping would cost more than the item.

Fees and inspection

Charge a restocking fee, or hold the refund until the warehouse has inspected what arrived.

  • POST /v1/return-policies
  • POST /v1/return-previews
  • POST /v1/returns
  • completion_blockers
  • return.completed

A warehouse key can record what arrived without being able to refund anyone. The returns guide covers mail-in and in-store flows, and the policy guide covers every rule.

06Yours

Start hosted. Take over any surface when you want it.

Every hosted surface has an API twin. Replace one at a time, in any order, and the orders, customers, and history never move.

checkout

Day one. A hosted page under your name, from one redirect.

When you want it. The same session embedded in your pages. Flint still computes the total, the shipping quote, and the payment.

buyer account

Day one. A hosted account with orders, tracking, returns, subscriptions, and saved cards.

When you want it. Your own account pages on the buyer API, signed in through your login.

buyer email

Day one. Six families of email sent for you, in your colors and logo.

When you want it. One setting per family hands it to your sender. The events keep firing.

storefront

Day one. Payment links sell a product from a URL before the site exists.

When you want it. Your framework, your host, your design. There is no theme engine to work around.

The headless storefront guide covers owning the checkout and the account, and the email guide covers sending your own.

07The rest of the store

Month two is already on the order.

A sale, a subscription box, a fraud rule, a tax report. Each one is more calls against the records your store already has, and each one shows up in the same dashboard.

Catalog

Products with variants, bundles, and images. An order line names a variant, and the price, tax category, and stock rules come with it.

  • POST /v1/products
  • variants
  • POST /v1/bundles

Promotions

Automatic discounts, code campaigns, and buy-one-get-one, with rules for what stacks. Priced on the server, before tax.

  • POST /v1/promotions
  • combines_with

Subscriptions

Coffee every month from the same catalog. Every renewal is an order, so it ships, emails, and refunds like any other.

  • POST /v1/subscription-plans
  • POST /v1/subscriptions

Payment links

Sell a product from a URL in a bio, an email, or a QR code. Each buyer gets a real order with the same receipt and account.

  • POST /v1/payment-links

Fraud rules

Block, review, or allow payment attempts by amount, email, card, or risk level, and test a rule before it goes live.

  • POST /v1/risk-rules
  • POST /v1/risk-previews

Payouts and reports

Each payout ties back to the payments inside it, and orders, payments, and tax export as CSV for your accountant.

  • GET /v1/payouts
  • POST /v1/reports
app.withflintpay.com
Flint dashboard order detail: line items, totals with a line-item refund, the payment attempt and an activity timeline on one $19.43 order record
An order your storefront created, as your team sees it: line items, totals, a line-item refund, and the activity timeline, with nothing to build.

Each of these has its own page: the commerce API, subscriptions, and payment links.

08Start

Put one order through the whole store.

Sandbox keys are free and take a few minutes. Create a product, sell it, ship it, and return it against test cards, and watch one record carry all of it.

Node

npm install @flintpay/node

CLI

brew install flint-pay/tap/flint

Building the storefront with an AI agent? The sell online with AI page shows how it reads the docs and pays its own test order. Building in Next.js? The Next.js commerce page has the server action.

Then read these

  1. 01
    Accept your first payment
  2. 02
    Add shipping to a checkout
  3. 03
    Inventory
  4. 04
    Returns
  5. 05
    Build a headless storefront
  6. 06
    Full API reference
Get free API keys

FAQ

Questions worth asking first.

Is Flint an ecommerce platform or a payment processor?

It is the store behind your storefront, reached through one API. You build the pages buyers browse, in any framework and on any host. Flint runs what happens after they click Buy: the checkout, shipping and tax on the order, stock, receipts and tracking email, the buyer account, returns, refunds, and payouts. Payments are part of the same API, so there is no separate processor to connect.

Do I have to use the hosted checkout?

No. The hosted checkout is the fastest way to start: create a session for the order and redirect. When you want the checkout inside your own pages, create the session as embedded and render it yourself while Flint stays authoritative for the total, the shipping quote, and the payment. Orders, customers, and history are the same either way, so switching is not a migration.

How does shipping get priced at checkout?

You create delivery methods and the checkout quotes them against the buyer's address. A method can charge a flat rate, read a rate table, step through tiers, or ask your own endpoint for a live rate. Zones decide where each method is offered, and pickup and local delivery are methods too. The selected option adds its charge to the order, and the tax and the total update before the buyer pays.

What stops two buyers from purchasing the last unit?

Stock is claimed, not counted down. When an order with tracked items is paid, Flint holds the units, commits them when the payment succeeds, and releases them if it fails. If no location can serve the order, the payment fails before any money moves. Units leave the shelf when the shipment is handed off, so available stock is always on hand minus what is held, committed, or set aside as safety stock.

Who sends the order confirmation and shipping emails?

Flint does, in your colors and with your logo, unless you would rather send them. Buyer email comes in six families: receipts, fulfillment updates, subscription notices, failed-payment notices, returns, and invoices. Each one switches to your own sender with one setting, and the webhook events behind it keep firing so your handler has what it needs.

How do returns work?

You write a return policy once: what is returnable, for how long, who pays return shipping, whether there is a restocking fee, and when the money goes back. Buyers start a return from their account, the policy can approve it on its own, and the refund is computed from what the line settled for, including its share of tax. Recording where the returned unit ended up is what puts it back in stock. Exchanges and replacements run on the same return.

Can I sell subscriptions and one-time products from the same store?

Yes. Subscription plans use the same catalog, and every renewal is an order, so a monthly coffee subscription ships, emails, refunds, and reports exactly like a one-time purchase. Buyers manage the subscription and their saved card in the same account where they track parcels.