Skip to content

Accounting and bookkeeping

Flint records money in two ledgers, and every row in both has a stable ID, a signed amount in minor units, and a link to the order, payment, refund, dispute, or invoice behind it. That's enough to keep complete books in any general ledger: post each row once, to the accounts suggested below, and tie every bank deposit back to the sales inside it.

  • The balance ledger holds every movement of your Flint balance: payments, refunds, disputes, payouts, and the processing fees taken out of each. Read it as balance transactions.
  • Merchant billing holds what you owe Flint and the account credit you hold: event fees, Flint's invoices to you, credits, and collections. Read it as merchant billing entries.

Flint doesn't include a QuickBooks, Xero, or NetSuite connector. You import the CSV reports each period, or build a sync from the API with the recipe at the end. The accounts and journal entries here are a starting point for that work; your accountant decides how your business books revenue, tax, and gift cards.

Choose your accounts#

Most businesses need these accounts for Flint activity. Rename them to fit your chart of accounts, and leave out the ones you'll never use, such as platform fee accounts if you don't run a partner app.

AccountTypeWhat posts to it
Flint balanceAsset (clearing)Every balance transaction's net_money. It should equal pending_money plus available_money plus held_money on your balance.
Flint reserveAssetreserve_hold and reserve_release rows: money Flint holds back that's still yours. It should equal reserve_money.
Payouts in transitAssetA payout between its payout row and the deposit landing in your bank. Optional: post straight to Bank if you prefer.
BankAssetPayout deposits, inbound payouts, checks and wires you record on invoices.
Disputed fundsAssetChargeback principal Flint took while a dispute is open.
Accounts receivableAssetIssued invoices, until they're paid, credited, or written off.
Credit with FlintAssetAccount credit Flint issued you and you haven't used: available_credit_money on the merchant billing balance.
Due to FlintLiabilityWhat you owe Flint: outstanding_money on the merchant billing balance.
Sales tax payableLiabilityTax you collected, less tax you refunded or credited.
Tips payableLiabilityTips you collected for staff, if you pay them out.
Gift card liabilityLiabilityUnspent gift card value.
Deferred revenueLiabilityPayments for deliveries or service periods you haven't provided yet.
SalesIncomeMerchandise and services, net of discounts if you don't track them separately.
Shipping and delivery incomeIncomeOrder charges such as delivery, service, or handling fees.
DiscountsContra-incomeDiscounts on orders, if you track them separately from sales.
Sales returns and allowancesContra-incomeRefunds and credit notes.
Chargeback lossesExpense or contra-incomeDisputes you lost.
Processing feesExpenseFlint's processing fee and add-on fees on each payment.
Platform fees paidExpenseFees a partner app charged on your payments.
Dispute feesExpenseProcessor dispute fees, and dispute event fees in merchant billing.
Flint fees and subscriptionExpenseOther event fees, Flint's invoices to you, and the custom domain add-on.
Bad debtExpenseInvoices you write off.

If you run a partner app that charges platform fees, add three accounts: Platform fee revenue (income), Platform fee receivable (asset), and Platform fee reserve (asset). If you collect payments for other sellers, add an account for marketplace splits.

Group every account's activity by currency. Flint never converts amounts, and each row carries its own currency.

Map the balance ledger#

Each balance transaction becomes one journal entry. Post its net_money to Flint balance, its fee_money to the fee account, and its amount_money to the account in the table. The entry balances because net_money is amount_money minus fee_money. Balance transaction types describes each type in full.

typeSign of amount_moneyPost amount_money againstPost fee_money to
paymentPositiveSales, shipping income, sales tax payable, and tips payable from the order. Accounts receivable for an invoice payment. Gift card liability for a gift card sale. Deferred revenue for prepaid periods.Processing fees, and Platform fees paid for the platform_fee part of fee_details
refundNegativeSales returns and allowances, and sales tax payable for the tax it refundsNone (fee_money is 0)
recoveryPositiveReverse the failed refund: Sales returns and allowancesNone
returnNegativeReverse the payment: Accounts receivable for an invoice payment, which reopens, otherwise Sales returns and allowancesNone
disputeNegativeDisputed fundsDispute fees
dispute_reversalPositiveDisputed fundsDispute fees (a negative fee is a fee returned)
payoutNegativePayouts in transit, or BankNone
payout_failure, payout_cancellation, payout_reversalPositivePayouts in transit, or Bank: the money came backNone
inbound_payoutPositiveBankNone
inbound_payout_failureNegativeBankNone
reserve_holdNegativeFlint reserve: the money moves into itNone
reserve_releasePositiveFlint reserve: the money moves out of itNone
merchant_billing_collectionNegativeDue to FlintNone
merchant_billing_collection_reversalPositiveDue to FlintNone
platform_fee_refundPositivePlatform fees paidNone
platform_fee_payout, platform_fee_payout_reversalPositive, negativePlatform fee receivableNone
payment_split and the other split typesEitherYour marketplace splits account. See Marketplaces.None
adjustmentEitherRead description. A returned processing fee goes to Processing fees.None
payout_advance, payout_advance_fundingEitherA liability for the advance. Most accounts never see these.None
otherEitherA suspense account, until you've read descriptionThe same suspense account

Filter on type, not on the sign of amount_money: several types post negative. Reconciliation covers each field.

Map merchant billing#

Each merchant billing entry changes what you owe Flint (outstanding_effect_money) or the credit you hold (available_credit_effect_money). Post the first to Due to Flint and the second to Credit with Flint, against the account in the table.

typeDebitCredit
event_fee with event_fee_type card_dispute, card_dispute_countered, or ach_disputeDispute feesDue to Flint
event_fee, any other event_fee_typeFlint fees and subscriptionDue to Flint
invoiceFlint fees and subscription, for subtotal_moneyDue to Flint
custom_domainFlint fees and subscriptionDue to Flint
custom_domain_collectionDue to FlintThe account that paid it. See the note below.
correction (positive)The fee it corrects: Processing fees when it carries payment_intent_id and corrects a processing fee, otherwise the entry named by related_merchant_billing_entry_idDue to Flint
correction (negative)Due to FlintThe fee it corrects
credit_issuedCredit with FlintFlint fees and subscription, or other income, as your accountant prefers
credit_appliedDue to FlintCredit with Flint
credit_refundedThe account the money arrived inCredit with Flint
collectionDon't post. The merchant_billing_collection balance transaction already did.
collection_reversalDon't post. The merchant_billing_collection_reversal balance transaction already did.
write_offDue to FlintThe expense account of the charge Flint stopped collecting, or other income

A custom_domain entry and its custom_domain_collection are recorded together for the same amount and carry no balance_transaction_id. Depending on your agreement, Flint takes the charge from your Flint balance or from the billing card on file, so post the collection against Flint balance or the card's account once you've matched the payment.

Your Due to Flint account should equal the sum of outstanding_money across your merchant billing balances, and Credit with Flint should equal available_credit_money.

Don't count the same money twice#

Several Flint records describe the same activity from different angles. Post each from one source:

  • Collections live in both ledgers. When Flint collects what you owe, the merchant_billing_collection balance transaction and the collection billing entry are the same money, linked by the entry's balance_transaction_id. Post the balance transaction, which moves your Flint balance, and skip the entry.
  • A dispute fee appears once. A processor dispute fee deducted from your balance is in the dispute row's fee_money, and it never also appears as a card_dispute event fee. A fee Flint paid on your behalf is an event fee in merchant billing instead. Post both sources, and each fee lands once.
  • The processing fee stays on the payment. It's in the payment row's fee_money and in payments_itemized_v1. Merchant billing holds only later correction entries to it, so post the correction as a change, not as a second fee.
  • An invoice and its order are one sale. An invoice can link to an order, and the order's totals describe the same sale. Book invoiced sales from the invoice and its payments, and don't add the order's totals to sales. Reports say the same: don't add invoice totals to order sales.
  • A payment is cash, not a second sale. When you book revenue from orders or invoices, the payment row clears that revenue or receivable into Flint balance. It isn't more revenue.
  • Gift cards move value, not cash, when spent. The cash arrives when the card is sold. A redemption moves value from gift card liability to sales and posts no balance transaction.
  • Flint's invoice entries are bills to you. The invoice type in merchant billing is Flint invoicing your Flint subscription, not your invoices to customers.
  • Pick one export per ledger. payments_itemized_v1, balance_transactions_itemized_v1, and payouts_itemized_v1 overlap. Post from balance transactions, and use the other two to check fees and deposits.

Cash or accrual#

Accrual books record revenue when you earn it; cash books record it when the money arrives. Flint gives you the timestamp for each:

ActivityAccrual: book it atCash: book it at
Order saleOrder.paid_at, or the fulfillment's completed_at if you recognize goods on deliveryThe payment row's occurred_at
InvoiceInvoice.issued_at, to Accounts receivableThe payment row's occurred_at, or a manual payment's received_at
RefundEach refund part's succeeded_at in Refund.tender_allocationsThe refund row's occurred_at
Credit noteEach allocation's allocated_at, or the linked refund's part succeeded_atThe linked refund's refund row
DisputeThe dispute row's occurred_at; the outcome at Dispute.status_changed_atThe dispute and dispute_reversal rows' occurred_at
Processing feesThe payment row's occurred_at. Fees are final at capture for cards and when an ACH debit succeeds.The same
Flint's charges to youThe billing entry's occurred_atThe merchant_billing_collection row's occurred_at
Gift cardsEach gift card transaction's posted_atThe sale's payment row
Subscription periodsSpread across the period the charge paid forThe payment row's occurred_at
PayoutsA transfer between Flint balance and Bank, at arrival_dateThe same

On either basis, a payout isn't income: it moves money you already booked from Flint balance to Bank. Most bookkeepers treat a sale's cash as received when it reaches your Flint balance, at occurred_at, rather than when the payout lands.

Every timestamp in the API is UTC. Close a period at midnight in your own time zone by sending that instant with its offset, as the report intervals do.

Worked journal entries#

The examples use USD and round example fees. Read the real fee from each payment's fee_money; don't recompute it from your rates.

A sale with tax#

Order 1042 sells $48.00 of goods with a $5.00 discount, a $6.00 delivery charge, $3.72 of sales tax, and a $5.00 tip, for a $57.72 total. The card payment posts a payment balance transaction with amount_money 5772, fee_money 197, and net_money 5575.

AccountDebitCredit
Flint balance55.75
Processing fees1.97
Discounts5.00
Sales48.00
Shipping and delivery income6.00
Sales tax payable3.72
Tips payable5.00

Take the split from the order's pricing_amounts or an orders_itemized_v1 row: subtotal_money, discount_money, charge_money, additive_tax_money, and requested_tip_money. With inclusive tax, the prices already contain it: move inclusive_tax_money out of Sales, or the charge it's in, and into Sales tax payable. For tax owed to each jurisdiction, use the tax reports.

A refund#

The buyer returns one $20.00 item from order 1042, and you refund it with its $1.73 of tax. The refund posts a refund row with amount_money -2173 and fee_money 0.

AccountDebitCredit
Sales returns and allowances20.00
Sales tax payable1.73
Flint balance21.73

The original processing fee isn't returned, so it stays in Processing fees. Read the split from the refund's line_item_allocations, charge_allocations, tax_breakdown_refunds, and refunded_tip_money. A refund to store credit, with destination new_gift_card, posts no balance transaction: credit Gift card liability instead of Flint balance. A refund you paid outside Flint has processed_by merchant and posts no balance transaction: credit Bank.

A dispute: opened, won, or lost#

A buyer disputes a $50.00 card payment. The dispute row has amount_money -5000 and, when the processor deducted its $15.00 dispute fee from your balance, fee_money 1500, for net_money -6500.

WhenAccountDebitCredit
OpenedDisputed funds50.00
Dispute fees15.00
Flint balance65.00
WonFlint balance50.00
Disputed funds50.00
LostChargeback losses50.00
Disputed funds50.00

A win posts a dispute_reversal row for the principal. If the processor also returns the fee, that row's fee_money is negative, or a separate row returns it; post that to Dispute fees. A won status alone doesn't mean the fee came back. A loss posts no balance transaction: book it when the dispute reaches lost, at status_changed_at, or when dispute.lost arrives. Inquiries move no money. An ACH bank return also posts a dispute row; on an invoice payment it reopens the invoice, so debit Accounts receivable instead of Disputed funds.

If Flint paid the processor's fee for you, the dispute row has fee_money 0 and the fee arrives as a card_dispute event fee in merchant billing: debit Dispute fees and credit Due to Flint. Disputes shows what each outcome costs.

A payout#

A $132.85 payout posts one payout row with amount_money -13285, and lands in your bank on its arrival_date.

WhenAccountDebitCredit
payout rowPayouts in transit132.85
Flint balance132.85
Deposit landsBank132.85
Payouts in transit132.85

To show what the deposit carried, list its rows with GET /v1/balance-transactions?payout_id=..., or use payouts_itemized_v1, Flint's settlement report: for each paid payout, its rows' net_money adds up to the deposit. You've already posted each of those rows, so the list is a check, not more entries. Match a deposit to its contents has the steps. If the payout fails or is reversed, post the payout_failure or payout_reversal row against Payouts in transit or Bank.

A platform fee#

A partner app charges a $1.50 platform fee on a $100.00 payment, and Flint's own fees are $3.20. On the merchant's balance, the payment row has fee_money 470, and fee_details splits it into flint 320 and platform_fee 150.

The merchant books:

AccountDebitCredit
Flint balance95.30
Processing fees3.20
Platform fees paid1.50
Sales100.00

The platform reads its fee with its own merchant's credentials, from GET /v1/platform-fees and GET /v1/platform-fee-balance-transactions. By default, Flint holds 20% of each fee in a reserve for about 120 days. When the fee succeeds, the platform books:

AccountDebitCredit
Platform fee receivable1.20
Platform fee reserve0.30
Platform fee revenue1.50

Flint pays available fees into the platform's own Flint balance daily. That posts a platform_fee_payout balance transaction on the platform's balance: debit Flint balance, credit Platform fee receivable. When the reserve is released, move it from Platform fee reserve to Platform fee receivable; when it covers a merchant's loss (loss_coverage), expense it.

If the partner app returns its fee on a refund, the merchant gets a platform_fee_refund row (debit Flint balance, credit Platform fees paid), and the platform's ledger debits a platform_fee_refund (debit Platform fee revenue, credit Platform fee receivable). Platform fees has the refund rules.

A gift card sale and redemption#

A buyer pays $50.00 by card for a $50.00 gift card. The payment row has fee_money 175.

AccountDebitCredit
Flint balance48.25
Processing fees1.75
Gift card liability50.00

Later the holder spends $43.30 of it on an order with $40.00 of goods and $3.30 of tax. No money moves, so there's no balance transaction:

AccountDebitCredit
Gift card liability43.30
Sales40.00
Sales tax payable3.30

Find gift card sales in orders_itemized_v2, where gift_card_consideration_money is what buyers paid for gift cards and merchandise_subtotal_money excludes it. Find redemptions in the order's gift_card_settlements or in GET /v1/gift-card-transactions?transaction_type=redeem&posted_after=.... A card sold below face value, such as a $25.00 card for $22.00, adds $25.00 of liability and $22.00 of consideration. How to book the difference and unspent value is your accountant's call. Check the account each period against closing_money in the gift_card_liability_v1 report. See Gift cards.

A prepaid subscription#

A gift box plan charges once for six monthly deliveries at $30.00 each, with $6.00 shipping per delivery. The signup order is delivery 1 and carries a "Box, deliveries 2 to 6" line for the other five, plus their shipping as one charge. The buyer pays $216.00 and the payment row has fee_money 656. There's no tax in this example.

WhenAccountDebitCredit
PaymentFlint balance209.44
Processing fees6.56
Sales30.00
Shipping and delivery income6.00
Deferred revenue180.00
Each later deliveryDeferred revenue36.00
Sales30.00
Shipping and delivery income6.00

Flint creates each later delivery as its own order with prepayment_order_id pointing at the paying order, subscription_delivery_number from 2 to 6, and its merchandise discounted to zero. Recognize the deferred amount when that order's fulfillment completes, and don't book the zero-value order as a sale. Prepaid deliveries has the details.

For a service paid in advance, such as a $120.00 yearly plan, credit Deferred revenue with the whole charge and move $10.00 to Sales each month of the period. The cycle's order has subscription_id and subscription_cycle but not the period's dates, so store current_period_start_at and current_period_end_at from the subscription.payment_succeeded event for that charge.

A credit note#

You issued invoice 0042 for $1,000.00 of services plus $80.00 of tax, then credit $100.00 of it, with its $8.00 of tax, before the buyer pays.

WhenAccountDebitCredit
Invoice issuedAccounts receivable1,080.00
Sales1,000.00
Sales tax payable80.00
Credit allocatedSales returns and allowances100.00
Sales tax payable8.00
Accounts receivable108.00

Each credit note line has its own tax_money. Issuing a note on its own moves nothing: book it when it's allocated or refunded. On a paid invoice, a refund of the note posts a refund row whose refund carries credit_note_id: credit Flint balance instead of Accounts receivable. A refund you record as paid outside Flint posts no balance transaction: credit Bank. Reversing an allocation reverses the entry. See Credit notes.

Invoice payments and write-offs#

EventDebitCredit
Paid online through FlintFlint balance (net_money) and Processing fees (fee_money, including the invoice collection add-on fee)Accounts receivable
Check or wire recorded as a manual paymentBank, or an undeposited funds accountAccounts receivable
Manual payment reversedAccounts receivableBank
Invoice marked uncollectibleBad debtAccounts receivable

Use receivables_aging_v1 to check Accounts receivable against your invoices as of any date; see Receivables aging.

What you owe Flint#

Flint invoices your $49.00 subscription, applies $10.00 of account credit, and collects the remaining $39.00 from your Flint balance. Merchant billing has an invoice entry, a credit_applied entry, and a collection entry, and your balance has a merchant_billing_collection row for -3900.

WhenAccountDebitCredit
invoice entryFlint fees and subscription49.00
Due to Flint49.00
credit_applied entryDue to Flint10.00
Credit with Flint10.00
merchant_billing_collection rowDue to Flint39.00
Flint balance39.00

The collection entry is the same $39.00 as the balance transaction, so it gets no entry of its own.

Build a sync that's safe to re-run#

A sync reads Flint, writes journal entries into your accounting system, and can run again at any time without creating duplicates. It needs three things: one journal entry per Flint record, keyed by that record's ID; a cursor per list so each pass reads only what may have changed; and a final check at period close.

Key every entry by a Flint ID#

Write the source ID into the journal entry's reference or memo field, and look it up before you create anything:

  • One entry per balance transaction, keyed by balance_transaction_id (btxn_).
  • One entry per merchant billing entry that you post, keyed by merchant_billing_entry_id (mbe_).
  • One entry per accrual event you book from a business object: an invoice by invoice_id, a credit note allocation by credit_note_allocation_id, a manual payment by invoice_manual_payment_id, a gift card redemption by its gift card transaction ID, a lost dispute by dispute_id.

If an entry with that key exists, update or skip it; never create a second. Flint never deletes a ledger row or changes its amounts. Money that comes back posts a new row, such as a recovery or payout_failure, so it gets a new entry.

Read each list with a cursor#

RecordsHow to read changesNotes
Balance transactionsoccurred_after and occurred_before on GET /v1/balance-transactionsRows can be recorded after they occurred while Flint reconciles your processor's history, so re-read a trailing window, such as the last 24 hours, on every pass. Only status and payout_id change on an existing row.
Merchant billing entriescreated_after on GET /v1/merchant-billing-entriesOverlap passes by a few minutes. See Sync new entries.
Orders, payment intents, refunds, disputes, invoices, subscriptionsupdated_after with an overlap of a few minutesKeep the copy with the higher version where the object has one, or the later updated_at.
Payoutscreated_after, then re-read each payout that isn't final by IDThe list has no updated_after filter, and a succeeded payout can still be reversed.
Credit notescreated_after, plus credit_note.* and credit_note_allocation.* eventsThe list has no updated_after filter, and an issued note keeps changing as you allocate and refund it.
Manual paymentsGET /v1/invoices/{invoice_id}/manual-payments for each invoice your updated_after pass returnedThere's no list across invoices.
Gift card transactionsposted_after on GET /v1/gift-card-transactionsPostings never change.
Platform fee ledgeroccurred_after on GET /v1/platform-fee-balance-transactionsFor platforms only.

Read every page of a pass, passing next_page_token as page_token until it's absent, and move your cursor only after the last page. A page token only works with the query it came from. Pagination has a loop you can copy.

cURL
curl "https://api.withflintpay.com/v1/balance-transactions?currency=USD&occurred_after=2026-11-20T00:00:00Z&page_size=100" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Flint-Version: 2026-09-07"

Send Flint-Version: 2026-09-07 or later. Earlier versions report fee_money with the opposite sign; see Older API versions.

Use webhooks to start a pass#

Webhooks tell you something changed sooner than a schedule would. Treat each one as a reason to read, not as the record:

Events can arrive more than once, out of order, or late while a delivery is retried. Fetch the object with GET and write what it says now, so a replayed event or one that arrives early changes nothing. Keep the scheduled pass running too: it picks up anything a missed delivery would have carried. Webhooks covers delivery and retries.

Close the period#

Before you lock a month in your accounting system:

  1. Run a final pass over the month with no cursor shortcuts.
  2. Check that meta.history is absent on the balance transaction list, which means Flint's history is complete. See Close a period.
  3. Generate balance_transactions_itemized_v1 and merchant_billing_itemized_v1 for the month. Flint generates them only once the interval is complete, and fails them with data_unavailable otherwise. Compare their row IDs and totals with what you posted.
  4. Check that Flint balance and Flint reserve match your balance, and that Due to Flint and Credit with Flint match your merchant billing balance.

Credentials#

Call these routes with the merchant's own API key. Give it read scopes only, such as money_movement.balance_transactions.read, merchant_billing.read, commerce.orders.read, and reports.write if the sync generates reports. A partner app token can read balance transactions and payouts when its grant holds their scopes, but it can't call report routes or read merchant billing. See Authentication and API key security.

Records without their own report#

Some records you'll book have no report type yet. Read them from the API instead:

  • Refunds. There's no refunds report. refund rows in balance_transactions_itemized_v1 carry the refund ID in related_resource.resource_id, and GET /v1/refunds?updated_after=... returns the allocations and tax. Refunds you recorded as paid outside Flint post no balance transaction, so read them from the refunds list.
  • Credit notes. There's no credit notes report. List them with GET /v1/credit-notes, and check each invoice's credited_money in invoices_itemized_v1.
  • Checks and wires. There's no report or cross-invoice list of manual payments. Read each invoice's manual payments, or follow invoice_manual_payment.created and invoice_manual_payment.reversed. paid_money in invoices_itemized_v1 includes them.
  • Invoice on a payment. payments_itemized_v1 has no invoice_id column. The payment intent has invoice_id, so read it with GET /v1/payment-intents/{payment_intent_id}, or list an invoice's payments with GET /v1/payment-intents?invoice_id=.... When the invoice has an order, order_id also joins the payment to invoices_itemized_v1.
  • Subscription on an order. orders_itemized_v1 and orders_itemized_v2 have no subscription_id column. The order has subscription_id, and GET /v1/orders?subscription_id=... lists a subscription's orders. For invoiced subscriptions, invoices_itemized_v1 has subscription_id.

Next steps#

ReconciliationMatch each deposit to the payments, refunds, and fees inside it, and close a period.ReportsEvery report type, its columns, and how to generate and download it.Merchant billingWhat you owe Flint, the credit you hold, and how Flint collects it.PayoutsPayout schedules, failures, reversals, and what each payout carried.

Ready to connect your books? Create a Flint account and run the sync against your sandbox first.

Was this helpful?