B2B wholesale with invoicing
Sell to retailers at negotiated prices, bill them on net 30 terms with a deposit up front, take the rest by check, credit what comes back damaged, and close the month with a receivables aging report. One order and one invoice carry the whole sale, so your price, tax, payment, and credit records all point at the same IDs.
The example follows one sale: a ceramics studio sells 120 stoneware mugs and 48 espresso cups to Harbor Gift Co., a Texas shop that resells them. Harbor pays 30% at issue by bank debit and the balance by check, and returns six chipped mugs.
What you build#
- Your server sends POST /v1/price-lists and its prices, once to Flint
- Your server sends POST /v1/customers with the wholesale segment and Net 30, then the resale exemption to Flint
- Your server sends POST /v1/orders for the customer: list prices, no tax to Flint
- Your server sends POST /v1/invoices with a deposit, a balance, and issue to Flint
- Flint sends invoice email; the buyer pays the deposit by bank debit to Buyer
- Flint sends invoice.partially_paid webhook to Your server
- Your server sends credit note for returned goods, allocated to the balance to Flint
- Flint sends reminders, then invoice.overdue after the due date to Buyer
- Your server sends POST manual-payments for each check to Flint
- Flint sends invoice.paid and order.paid webhooks to Your server
- Your server sends POST /v1/reports for receivables aging and itemized invoices to Flint
Steps#
1. Price the catalog for wholesale#
Create each product once at its retail price. Then create a price list for the wholesale customer segment and give each variant a wholesale base price with quantity breaks. The largest break at or below a line's quantity sets the unit price for every unit on that line, and quantities on separate lines aren't combined. Choose a price has the order Flint checks.
curl -X POST https://api.withflintpay.com/v1/products \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: product-stoneware-mug" \
-H "Content-Type: application/json" \
-d '{
"variant_mode": "simple",
"name": "Stoneware mug",
"product_type": "physical",
"default_variant": {
"sku": "MUG-STONE-12",
"unit_price_money": { "amount": 1600, "currency": "USD" }
}
}'
Create the espresso cup the same way at $10.00, then the list:
curl -X POST https://api.withflintpay.com/v1/price-lists \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: price-list-wholesale-us" \
-H "Content-Type: application/json" \
-d '{
"name": "Wholesale",
"currency": "USD",
"customer_segments": ["wholesale"],
"external_reference_id": "wholesale-us"
}'
curl -X POST https://api.withflintpay.com/v1/price-lists/prl_01KF6W9ZT24MNPZX45HY43KWJR/prices \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: price-list-wholesale-us-prices-1" \
-H "Content-Type: application/json" \
-d '{
"prices": [
{
"variant_id": "var_01KF6W3S3E28JT97KB6CQ643DZ",
"unit_price_money": { "amount": 800, "currency": "USD" },
"quantity_price_breaks": [
{ "minimum_quantity": 24, "unit_price_money": { "amount": 700, "currency": "USD" } },
{ "minimum_quantity": 96, "unit_price_money": { "amount": 625, "currency": "USD" } }
]
},
{
"variant_id": "var_01KF6WVMXXQKFBF5KZNWJ47TAN",
"unit_price_money": { "amount": 500, "currency": "USD" },
"quantity_price_breaks": [
{ "minimum_quantity": 48, "unit_price_money": { "amount": 425, "currency": "USD" } }
]
}
]
}'
| Mugs on one line | Unit price | Cups on one line | Unit price |
|---|---|---|---|
| 1 to 23 | $8.00 | 1 to 47 | $5.00 |
| 24 to 95 | $7.00 | 48 or more | $4.25 |
| 96 or more | $6.25 |
The response is 201 with each price's outcome: created, existing, or updated. A batch is atomic, so one invalid price leaves the list unchanged.
2. Set up the wholesale customer#
Create a Net 30 payment term, then the customer with segment: "wholesale" and the term as their default. To give one buyer its own negotiated list, set price_list_id on the customer instead; a direct list wins over the segment's.
curl -X POST https://api.withflintpay.com/v1/invoice-payment-terms \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: term-net-30" \
-H "Content-Type: application/json" \
-d '{
"name": "Net 30",
"calculation": { "type": "net_days", "days": 30 }
}'
curl -X POST https://api.withflintpay.com/v1/customers \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: customer-harbor-gift" \
-H "Content-Type: application/json" \
-d '{
"name": "Harbor Gift Co.",
"email": "ap@example.com",
"segment": "wholesale",
"default_invoice_payment_term_id": "ipt_01KF6WTQM83XSSSS6YS3C4DWA7",
"external_reference_id": "crm-acct-2207"
}'
Add a late_fee_policy to the term to charge a fixed or percentage fee after a grace period; Late fees covers it.
Record the buyer's Texas resale certificate as a tax exemption. Flint applies it to orders, invoices, and renewals taxed in a state it covers, between its dates, and keeps the certificate number on each exempt sale. evidence_reference points at the file you keep and is never shown to the buyer.
curl -X POST https://api.withflintpay.com/v1/customers/cus_01KF6WN36096Q14DR9GPQY77ZX/tax-exemptions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: resale-cert-harbor-tx" \
-H "Content-Type: application/json" \
-d '{
"reason": "resale",
"coverage": { "type": "states", "country": "US", "states": ["TX"] },
"certificate_number": "TX-RESALE-0417",
"evidence_reference": "certs/harbor-gift-tx-resale.pdf",
"start_date": "2026-01-01",
"end_date": "2027-12-31"
}'
3. Take the order on net terms#
Create the order with customer_id. Flint prices each catalog line from the customer's list and freezes those terms on the order, so later list edits don't change it. An order without a customer gets retail prices, and checkout never reprices after the fact. The Texas delivery destination is what the exemption's coverage is compared with.
curl -X POST https://api.withflintpay.com/v1/orders \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: order-harbor-po-7731" \
-H "Content-Type: application/json" \
-d '{
"customer_id": "cus_01KF6WN36096Q14DR9GPQY77ZX",
"line_items": [
{ "type": "variant", "variant_id": "var_01KF6W3S3E28JT97KB6CQ643DZ", "quantity": 120 },
{ "type": "variant", "variant_id": "var_01KF6WVMXXQKFBF5KZNWJ47TAN", "quantity": 48 }
],
"delivery_destination": {
"address": {
"line1": "500 Congress Ave",
"city": "Austin",
"state": "TX",
"postal_code": "78701",
"country": "US"
},
"recipient": { "name": "Harbor Gift Co. receiving" }
},
"tax": { "enabled": true },
"external_reference_id": "PO-7731"
}'
{
"data": {
"order_id": "ord_01KF6WPENECFSECZP11HYGCPWP",
"customer_id": "cus_01KF6WN36096Q14DR9GPQY77ZX",
"line_items": [
{
"order_line_item_id": "li_01KF6WQ5E6EYCNDY0YP57RCYBV",
"name": "Stoneware mug",
"quantity": 120,
"unit_price_money": { "amount": 625, "currency": "USD" },
"catalog_pricing": {
"source": "price_list",
"price_list_id": "prl_01KF6W9ZT24MNPZX45HY43KWJR",
"minimum_quantity": 96
},
"tax_money": { "amount": 0, "currency": "USD" },
"total_money": { "amount": 75000, "currency": "USD" }
},
{
"order_line_item_id": "li_01KF6WN5SXS5AA819X9YP98106",
"name": "Espresso cup",
"quantity": 48,
"unit_price_money": { "amount": 425, "currency": "USD" },
"catalog_pricing": {
"source": "price_list",
"price_list_id": "prl_01KF6W9ZT24MNPZX45HY43KWJR",
"minimum_quantity": 48
},
"tax_money": { "amount": 0, "currency": "USD" },
"total_money": { "amount": 20400, "currency": "USD" }
}
],
"tax": {
"enabled": true,
"mode": "automatic",
"status": "exempt",
"exemption": {
"source": "customer",
"tax_exempt": true,
"customer_tax_exemption_id": "ctex_01KF6WYYK596NGYA1DQ91K5GQA",
"reason": "resale",
"certificate_number": "TX-RESALE-0417"
}
},
"pricing_amounts": {
"tax_money": { "amount": 0, "currency": "USD" },
"total_money": { "amount": 95400, "currency": "USD" }
}
}
}
catalog_pricing names the list and the break that applied. It's merchant-only: the buyer sees the net prices and never the list. To refresh an open, unpaid order to current list prices, send catalog_price_behavior: "reprice" with the customer_id, as Freeze and refresh terms describes.
Ship the goods from your own system while the invoice is open: Flint's fulfillment records open once the order is paid.
4. Invoice with a deposit and net 30#
Create the invoice from the order and issue it in the same call. payment_due: customer_default takes the customer's Net 30 term, and the schedule asks for 30% at issue and the rest on the due date. At published rates, bank debit costs less than card on a balance this size, so offer it first.
curl -X POST https://api.withflintpay.com/v1/invoices \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: invoice-harbor-po-7731" \
-H "Content-Type: application/json" \
-d '{
"type": "order",
"order_id": "ord_01KF6WPENECFSECZP11HYGCPWP",
"collection": {
"mode": "buyer_initiated",
"payment_policy": { "enabled_payment_options": ["ach_debit", "card"] }
},
"payment_due": { "type": "customer_default" },
"schedule_entries": [
{
"kind": "deposit",
"amount_specification": { "type": "percentage", "percent": 30 },
"due": { "type": "at_issue" }
},
{
"kind": "balance",
"amount_specification": { "type": "remaining_balance" },
"due": { "type": "invoice_due_date" }
}
],
"recipient_email": "ap@example.com",
"po_number": "PO-7731",
"memo": "30% deposit due now, balance net 30.",
"issue": { "delivery_mode": "email" }
}'
{
"data": {
"invoice_id": "inv_01KF6W8VCD1GDJFMGT83PXT891",
"order_id": "ord_01KF6WPENECFSECZP11HYGCPWP",
"customer_id": "cus_01KF6WN36096Q14DR9GPQY77ZX",
"status": "open",
"invoice_number": "1187",
"issued_at": "2026-12-01T15:00:00Z",
"due_date": "2026-12-31",
"payment_due": {
"type": "payment_terms",
"invoice_payment_term_id": "ipt_01KF6WTQM83XSSSS6YS3C4DWA7"
},
"schedule_entries": [
{
"invoice_schedule_entry_id": "invse_01KF6W4DK79Q9G8XE6SZAEAVSN",
"kind": "deposit",
"status": "due",
"due": { "type": "at_issue", "due_date": "2026-12-01" },
"total_money": { "amount": 28620, "currency": "USD" },
"outstanding_money": { "amount": 28620, "currency": "USD" }
},
{
"invoice_schedule_entry_id": "invse_01KF6WTCPM5Q1NXW1RNJ47E65G",
"kind": "balance",
"status": "pending",
"due": { "type": "invoice_due_date", "due_date": "2026-12-31" },
"total_money": { "amount": 66780, "currency": "USD" },
"outstanding_money": { "amount": 66780, "currency": "USD" }
}
],
"pricing_amounts": {
"tax_money": { "amount": 0, "currency": "USD" },
"total_money": { "amount": 95400, "currency": "USD" }
},
"settlement_amounts": {
"paid_money": { "amount": 0, "currency": "USD" },
"credited_money": { "amount": 0, "currency": "USD" },
"outstanding_money": { "amount": 95400, "currency": "USD" },
"currently_due_money": { "amount": 28620, "currency": "USD" }
},
"snapshot": {
"tax_exemption": {
"source": "customer",
"tax_exempt": true,
"reason": "resale",
"certificate_number": "TX-RESALE-0417"
}
}
}
}
Issuing freezes the prices, the exemption, and the reminder cadence, emails ap@example.com, and returns public_url for the hosted invoice. The PDF prints a "Tax exempt" row with the reason and certificate number. Harbor pays the deposit by bank debit from the email: you get invoice_payment_attempt.processing while the debit clears, then invoice_payment_attempt.succeeded and invoice.partially_paid. To split the balance further, add up to 12 installment entries, each with its own date.
5. Credit returns and record checks#
Six mugs arrive chipped. Correct the issued invoice with a credit note for those units and apply it to the balance. Read the line's invoice_line_item_id from snapshot.line_items.
curl -X POST https://api.withflintpay.com/v1/credit-notes \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: credit-note-1187-chipped-mugs" \
-H "Content-Type: application/json" \
-d '{
"invoice_id": "inv_01KF6W8VCD1GDJFMGT83PXT891",
"reason": "returned_goods",
"memo": "Six mugs arrived chipped.",
"line_items": [
{
"invoice_line_item_id": "invli_01KF6WWB09B9Y73MY63FCH26W1",
"correction": { "type": "quantity", "quantity": 6 }
}
]
}'
curl -X POST https://api.withflintpay.com/v1/credit-notes/cn_01KF6WH2BH8VGS9ZM5H3BV4H15/issue \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: issue-credit-note-1187-1" \
-H "Content-Type: application/json" \
-d '{ "expected_version": 1, "allocation": {} }'
The note credits 6 of 120 units at the invoiced $6.25, or $37.50, with its share of the line's tax and discount, both zero here. The issue response carries the numbered note, the allocation, and the invoice, now owing $630.30. When goods come back and need receiving and restocking, use a Return instead: returns and credit notes draw on the same remaining value of each line.
When a check arrives, record it with its number in payment_reference. Record each check separately, so a bounced one can be reversed by itself.
curl -X POST https://api.withflintpay.com/v1/invoices/inv_01KF6W8VCD1GDJFMGT83PXT891/manual-payments \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: check-harbor-4521" \
-H "Content-Type: application/json" \
-d '{
"amount_money": { "amount": 40000, "currency": "USD" },
"received_at": "2027-01-08T16:00:00Z",
"payment_reference": "check-4521",
"note": "Check #4521, partial payment on PO-7731"
}'
{
"data": {
"invoice_manual_payment": {
"invoice_manual_payment_id": "omp_01KF6WSKDENC8SP3804GVA35RJ",
"invoice_id": "inv_01KF6W8VCD1GDJFMGT83PXT891",
"amount_money": { "amount": 40000, "currency": "USD" },
"payment_reference": "check-4521",
"status": "recorded"
},
"invoice": {
"invoice_id": "inv_01KF6W8VCD1GDJFMGT83PXT891",
"status": "partially_paid",
"settlement_amounts": {
"paid_money": { "amount": 68620, "currency": "USD" },
"credited_money": { "amount": 3750, "currency": "USD" },
"outstanding_money": { "amount": 23030, "currency": "USD" }
}
}
}
}
A recorded payment carries no processing fee. The final check for $230.30 clears the balance: the invoice becomes paid and sends invoice.paid, and the order sends order.paid. Recording never fails over the monthly allowance for orders paid outside Flint; past it, the response carries a warning.
6. Chase late payers and reconcile#
Set your reminder cadence once in settings. Each invoice freezes it at issue.
curl -X PATCH https://api.withflintpay.com/v1/settings \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"invoices": {
"reminder_policy": {
"rules": [{ "days_from_due": -3 }, { "days_from_due": 7 }, { "days_from_due": 14 }]
}
}
}'
For invoice 1187, Flint emails reminders on December 28, January 7, and January 14 while a balance remains, and sends invoice.overdue on January 1. When Harbor promises a check, pause with PATCH /v1/invoices/{invoice_id} and {"reminders_paused": true}, then send false once it clears. Your own chase list is GET /v1/invoices?is_overdue=true&status=open,partially_paid.
On January 15, export receivables aging:
curl -X POST https://api.withflintpay.com/v1/reports \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: aging-2027-01-15" \
-H "Content-Type: application/json" \
-d '{
"report_type": "receivables_aging_v1",
"as_of_date": "2027-01-15",
"timezone": "America/Chicago",
"currency": "USD"
}'
On report.succeeded, download download.url with your key. Invoice 1187's row (money columns shown as amounts):
invoice_number | due_date | days_past_due | total_money | paid_money | credited_money | past_due_1_30_money | outstanding_money |
|---|---|---|---|---|---|---|---|
| 1187 | 2026-12-31 | 15 | 95400 | 68620 | 3750 | 23030 | 23030 |
The five buckets sum to outstanding_money. Compare the column's total with GET /v1/customers/{customer_id}?expand=receivables for the same day, whose receivables.balances lists outstanding_money and overdue_money per currency. For the month's billing, create an invoices_itemized_v1 report over December: once the final check is in, invoice 1187's row reads paid, with paid_money 91650, credited_money 3750, and outstanding_money 0, which adds back to the 95400 billed. Reconcile receivables explains how to join both files to payouts.
Events to handle#
Subscribe your endpoint to these events. Choosing the right event explains why invoice.paid and its partners, not payment events, track receivables.
What to store#
| Value | From | Why |
|---|---|---|
price_list_id and each price_list_price_id | The price list responses | Edits and resyncs |
customer_id, and your account ID in external_reference_id | The customer | Links Flint's records to your CRM |
customer_tax_exemption_id and its end_date | The exemption | Renew the certificate before it lapses |
order_id and the buyer's PO number | The order | One key for the invoice, credit notes, and reports |
invoice_id, invoice_number, and version | The invoice | Payments, credits, and support lookups |
Each invoice_manual_payment_id | Each recorded check | Reversing a bounced check |
credit_note_id and credit_note_allocation_id | The credit note | Reversing a misapplied credit |
webhook_event_id of each processed event | Each delivery | Skips repeats |
Deadlines#
| What runs out | How long | Field | When it passes | What to do |
|---|---|---|---|---|
| Invoice payment | Through the invoice's due_date, set from its payment terms or a date you choose. It is overdue once that date ends in the invoice's timezone, the merchant's timezone as it was when the draft was written, or UTC when the merchant had none. | Invoice.due_date | Act by: Flint sends invoice.overdue while a balance remains, and is_overdue is true when you read the invoice. If the payment term carries a late fee, invoice.late_fee_due follows once the grace period ends. Before the due date, Flint sends invoice.reminder_due on your reminder cadence. | When delivery_mode is caller_managed, send the reminder yourself on invoice.reminder_due. To charge a late fee, assess it after invoice.late_fee_due. |
| Monthly allowance for orders paid outside Flint | Until resets_at on an external_paid_orders_over_allowance warning, the end of the New York calendar month in which Flint counted the order. | ResponseWarning.resets_at | Computed at read: The count and the allowance start over for the new month. Flint sends no event. A retry of the same request returns the original resets_at, even after the month has changed. | Read resets_at on the warning instead of working out the month end yourself. The allowance never prevents recording a payment. Any overage charge belongs to the month the order was counted in. |
| Report download link | 24 hours after the report succeeds. | PublicDownload.expires_at | Computed at read: The download stops working. The report keeps its succeeded status, and Flint sends no event. | Download the file soon after report.succeeded. To get it again, create a new report. |
| Answering a webhook delivery | 10 seconds per attempt. | None | Request: The attempt fails as webhook_timeout, and Flint retries on its schedule. | Return a 2xx within 10 seconds and do the real work in a background job. |
| Webhook delivery retries | Up to 9 automatic attempts over about 3 days. The ninth lands 71 to 86 hours after the first. | WebhookDelivery.next_retry_at | Request: Flint makes the next attempt. After the ninth failed attempt the delivery is failed, and you can resend it. | Deduplicate deliveries before you process them, and resend failed ones after you fix the endpoint. |
| Idempotency key | 24 hours from the original request on routes where the key is optional. On routes that require it, as long as the command's effects exist, except POST /v1/customer-sessions/refresh, which holds it for 24 hours. | None | Request: On an optional route, the same key runs as a new request. A required route returns the original result however late the retry arrives. | Keep automated retries well inside 24 hours, and never reuse an old key for a new action. |
What you must handle#
Before launch#
- Keep the secret key on your server, and give each key only the scopes it needs. Flint has no publishable key. See Keep keys on the server.
- Register a live webhook endpoint with your live key. The endpoint you tested with receives sandbox events only. See Register your production webhook endpoint.
- Verify every delivery against the raw request body before acting on it. See Verify the signature.
- Set the reminder cadence before you issue. Each invoice freezes the policy at issue, so a later change reaches only new invoices. See Reminder cadence.
- Decide who sends invoice email. With
merchant_sends, anemailissue is refused and reminders are yours to send. See The six families.
Each sale#
- Attach the customer when you create the order. Orders without a customer get retail prices, and checkout never reprices. See Supply the customer before checkout.
- Keep each resale certificate current as an exemption record with an end date. An expired record stops applying, and an issued invoice keeps its frozen tax. See When an exemption expires.
- Send an
Idempotency-Keyon every create, and reuse it when you retry. Invoice create, issue, and manual payments require one. See Send a key. - Don't edit an invoiced order. The invoice locks it; void the invoice, change the order, and invoice again. See How an invoice works.
- Record each check as its own manual payment, with its number. A reversal undoes a whole payment. See Record an offline payment.
- Correct an issued invoice with a credit note. Issued invoices can't be edited. See Choose the right correction.
After the sale#
- Reverse a bounced check by its ID. The amount returns to the balance and the invoice reopens. See Reverse a manual payment.
- Handle
invoice.reopened. When the buyer's bank returns a debit, the payment is reversed and a paid invoice reopens. See Disputes on invoice payments. - Download each report soon after
report.succeeded. The link expires 24 hours later. See Download the CSV. - Compare aging with customer receivables on the same day. Later activity changes both. See Reconcile receivables.
Test it#
Run the whole sale in your sandbox. No account yet? Sign up and you get one.
- Create the products, list, term, customer, and exemption, then the order. Check that each line shows
catalog_pricing.source: price_listand the order'stax.statusisexempt. - Create and issue the invoice, and pay the deposit from
public_urlwith a test bank account. Check thatinvoice.partially_paidreached your endpoint; Test webhook deliveries covers receiving events locally. - Issue the credit note, record two checks, and reverse one. Check for
invoice.reopened, then record it again. - Create a receivables aging report for today and compare its total with the customer's
receivables.
Going further#
Wholesale pricingInvoicingCredit notesSales taxReportsACH debit paymentsReady to bill your first wholesale account? Create a Flint account and issue a test invoice.