Concepts

The five objects and how they relate.

Five objects, and the relationships between them are not obvious from their names. Read this once and the rest of the reference follows; skip it and the most likely mistake is inventing a call that cannot exist.

Contract is the anchor. Everything else hangs off one. A subscription, a usage meter, a credit balance and an invoice all name a contract, and the contract carries the currency they must all agree on.

Invoice is a document, not a record you edit. Once issued it has a number and is immutable. A correction is a new document — a credit note — and both stay visible in every listing. There is no PATCH and no DELETE, which means an agent cannot be told to "fix" an invoice: the only correct move is to issue a correcting one.

Three questions the object names do not answer

Can an invoice exist without a contract?

No. Every invoice names a contract, and issuing one without it is refused before anything is written.

But you do not have to create the contract first. An ad-hoc invoice — a one-off with origin: adhoc — provisions what it needs from the bill-to you type: the customer is found or created by email, and a live contract in the same currency is reused if one exists, created if not. So a one-off stays one call. Send the same recipient a second one-off and it lands on the same customer and the same contract rather than minting duplicates.

This provisioning is deliberately only for ad-hoc documents. A usage or recurring invoice with no contract is a caller mistake, and inventing a contract for it would detach that revenue from the agreement it belongs to.

Does a subscription generate invoices automatically?

No — not by itself. Two different mechanisms are easy to confuse:

• The lifecycle pass advances a subscription's state on its dates: a trial activates, a cancellation takes effect after its notice period, a fixed end expires it, and a term that has rolled over gets the term now in force. It issues no documents at all.
• The billing run raises the money. It bills each revenue model on a contract — recurring, then usage, then project work, then any one-time line — each through its own engine, each producing its own document so the invoice's origin stays truthful.

So a subscription's period turning over does not, on its own, produce an invoice. Something has to run the billing — and on a seller who has the issuance passes switched on (billing.recurring.invoice_pass, billing.usage.invoice_pass), that something is a schedule, not a person. Both default to off. Write your integration so a document appearing without you is normal, not an anomaly.

Double billing is prevented by claims, not by memory. A subscription period lands on a unique (subscription, period_start) row, usage lines and project work flip guarded status columns, and every claim's invoice carries its id. Re-running a billing run finishes only what is missing; an ambiguous commit is repaired by looking the claim up, never by issuing again. A model that fails does not roll back a sibling's document — a numbered invoice cannot be un-issued — and the run reports per model what happened.

Do credits apply before or after tax?

After. Credit is a payment method, not a discount. It draws down the invoice's grand total — the amount including tax — and never reduces the taxable base. The tax the document reports is the tax on the full price, whatever the customer's balance was.

Two consequences worth knowing before you model this:

• A credit-funded invoice is neither expected nor received cash. It is its own thing, and reporting treats it that way.
• An invoice collected by bank transfer draws no credit at all. The buyer was told to wire the grand total; shrinking the collectible underneath that instruction would make every full-face wire arrive as an overpayment. The balance stays on the ledger for the next link-collected document.

Three words that are one letter of confusion apart

The platform has three roles, and two of their field names differ by a single word while meaning entirely different things:

The direction of the money is what separates them:

sellerAccountId and sellerCustomerId look like siblings and are not: the first is your own identity, the second is your customer's. A marketplace operator is all three sentences at once — they are a Fynex seller, they have customers who pay invoices, and they have payees who receive splits and payouts.

If you think in the words vendor, merchant or supplier: the merchant running the account is the seller; a vendor or supplier you disburse money to is a payee; the buyer you bill is a customer. The settlement-trail endpoint (GET /invoices/{invoiceId}/settlement) is where the two APIs meet: a customer's payment on this side becomes a payee's payout on the other.

Where money and quantities live

Everything on a contract shares that contract's currency. There is no conversion anywhere in this API: a mismatch is refused rather than converted.