Flint Billing

Flint billing is what you owe Flint, and any account credit you hold against it. It covers per-event fees, Flint's subscription charges to you, corrections to fees Flint already charged, credit Flint issues you, and the collections Flint takes out of your Flint balance.

This is not Subscription Billing, which is you charging your own customers. Nothing on this page touches your customers or their money.

Identifiers in this area use the merchant_billing_ prefix: merchant_billing_balance_id, merchant_billing_entry_id, the merchant_billing_itemized_v1 report, and the merchant_billing_payment balance transaction type. Flint's invoices to you use merchant_subscription_invoice_id.

The processing fee on a payment is not billed here. It comes out of the payment as it settles and stays on the payment; see Processing Fees. A later correction to one of those fees does land here, as a correction entry.

Reading any of this needs the merchant_billing.read scope.

What You Owe Right Now#

Bash

curl "https://api.withflintpay.com/v1/merchant-billing-balances" \
  -H "Authorization: Bearer YOUR_API_KEY"

You get one balance per currency, each carrying:

outstanding_money: what you owe Flint right now.
available_credit_money: account credit you hold and have not used yet.
observed_at: the instant the snapshot was taken.
merchant_billing_balance_id: stable per currency, so GET /v1/merchant-billing-balances/{merchant_billing_balance_id} fetches the same balance again.

Both amounts are unsigned. Credit is not already subtracted from outstanding_money: it reduces what you owe at the moment Flint applies it, and that application is its own entry.

What Builds the Balance#

Every change to the balance is one entry, and every entry is one of eight types.

Type	What it is
`event_fee`	A fee for one event on your account, such as a card dispute or a failed ACH payment.
`subscription_invoice`	A Flint subscription invoice issued to you for a billing period.
`correction`	A finalized correction to a fee Flint already charged you.
`credit_issued`	Flint gave you account credit.
`credit_applied`	Account credit was put toward what you owe.
`collection`	Flint collected what you owe out of your Flint balance.
`collection_reversal`	A collection came back, so the amount is owed again.
`write_off`	Flint stopped collecting an amount you owed and cleared it.

event_fee entries name the event in event_fee_type: bank_verification, failed_ach_payment, ach_dispute, or card_dispute. No other entry type carries that field.

Signed Effects#

Each entry moves the two amounts on your balance independently. These are the merchant_billing_itemized_v1 column names:

outstanding_effect_money: how the entry moved what you owe. Positive adds to it.
available_credit_effect_money: how the entry moved your account credit. Positive adds to it.
net_billing_effect_money: outstanding_effect_money minus available_credit_effect_money.

Type	`outstanding_effect_money`	`available_credit_effect_money`
`event_fee`	Positive	Zero
`subscription_invoice`	Positive	Zero
`correction`	Positive or negative	Zero
`credit_issued`	Zero	Positive
`credit_applied`	Negative	Negative, same amount
`collection`	Negative	Zero
`collection_reversal`	Positive	Zero
`write_off`	Negative	Zero

credit_applied moves both by the same negative amount, so its net_billing_effect_money is zero: credit settles what you owe without any money moving.

Entries are added, never rewritten, and merchant_billing_entry_id is derived from what the entry records. An entry keeps the same mbe_ ID every time you generate the report, so one you already reconciled will not change under you.

How Flint Collects#

Flint collects what you owe out of your Flint balance, and each collection posts a balance transaction:

merchant_billing_payment is the collection. amount_money is negative, fee_money is zero, and net_money equals amount_money, because Flint charges nothing to collect.
merchant_billing_payment_reversal is a collection coming back. amount_money is positive, and related_balance_transaction_ids holds exactly one ID: the merchant_billing_payment it reverses. A collection carries none, so that field is how you pair a reversal with the collection it undoes.

related_object on either transaction points at the payment, dispute, or Flint subscription invoice the amount came from, when there is one. Filter for the invoice case with GET /v1/balance-transactions?related_object_type=merchant_subscription_invoice.

Both types appear in GET /v1/balance-transactions, in balance_transactions_itemized_v1, and on balance_transaction.created. See Reconciliation.

The same collection and reversal also appear as billing entries: a collection entry whose balance_transaction_id is the merchant_billing_payment, and a collection_reversal entry whose balance_transaction_id is the reversal. The reversal's related_merchant_billing_entry_id points back at the collection entry it undoes.

Flint's Subscription Invoices to You#

Bash

curl "https://api.withflintpay.com/v1/merchant-subscription-invoices?page_size=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Each invoice carries merchant_subscription_invoice_id, invoice_number, the period it covers (period_start and period_end), due_at, and its lines. A line is line_type subscription or credit, with a description, quantity, unit_amount_money, and amount_money.

Four money fields describe the invoice: subtotal_money before credit, credit_money applied to it, total_money equal to subtotal minus credit, and outstanding_money still to collect.

status is draft, open, collecting, paid, delinquent, void, or written_off. Read one invoice with GET /v1/merchant-subscription-invoices/{merchant_subscription_invoice_id}.

The Report#

merchant_billing_itemized_v1 gives one row per entry over an interval, ordered by when the entry occurred. See Reports for the columns and the generation flow.

Webhooks#

Event	Fires when
`merchant_billing_balance.updated`	What you owe Flint or hold as account credit changed.
`merchant_subscription_invoice.issued`	Flint issued you a subscription invoice.
`merchant_subscription_invoice.updated`	One of Flint's invoices to you changed status.

merchant_billing_balance.updated carries merchant_billing_balance_id, outstanding_money, available_credit_money, and observed_at. Both invoice events carry the full invoice Flint issued you, the same shape GET /v1/merchant-subscription-invoices/{merchant_subscription_invoice_id} returns. See Webhook Events.

Next Steps#

Reports: the merchant_billing_itemized_v1 columns and how to generate the file.
Reconciliation: what each balance transaction type does to your balance.
Processing Fees: the fee taken out of each payment as it settles.
Flint billing API reference: the balance and subscription invoice endpoints.
Money movement API reference: balances, balance transactions, and payouts.