# Concepts

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.

```
                        ┌──────────────┐
                        │   Customer   │  who you bill
                        └──────┬───────┘
                               │ one customer, many contracts
                        ┌──────▼───────┐
                        │   Contract   │  the agreement: currency, term
                        └──────┬───────┘
              ┌────────────────┼────────────────┐
              │                │                │
     ┌────────▼──────┐  ┌──────▼──────┐  ┌──────▼──────┐
     │ Subscription  │  │    Usage    │  │   Credits   │
     │ recurring fee │  │ metered qty │  │ stored value│
     └────────┬──────┘  └──────┬──────┘  └──────┬──────┘
              │                │                │
              └───────┬────────┘                │ drawn down at issue
                      │ billed by a run          │
               ┌──────▼───────┐                  │
               │   Invoice    │◄─────────────────┘
               │  immutable   │
               └──────────────┘
```

**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:

```
   Customer  ──── pays ────►   Seller   ──── pays ────►   Payee
 sellerCustomerId            sellerAccountId             payeeId
 your buyer                  YOU, the key holder         who you disburse to
 Billing API                 both APIs                   Payments API
```

| Word | Who | Lives on |
| --- | --- | --- |
| **Seller** (`sellerAccountId`) | **You** — the account holder the API key belongs to. Every object in both APIs is scoped to one. | Both APIs |
| **Customer** (`sellerCustomerId`) | Who **pays you** — the party your invoices are addressed to. | This API |
| **Payee** (`payeeId`) | Who **you pay** — a counterparty receiving money through split payments and payouts. | Payments API |

`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

| Thing | On the wire |
| --- | --- |
| An amount of money | Integer **minor units**, field ends `Minor` — `4999` is €49.99 |
| A rate or percentage | Integer **basis points**, field ends `Bps` — `275` is 2.75% |
| A metered quantity | Decimal **string** — `"1250.5"` |
| A per-unit rate | Decimal **string** in MAJOR units — `"0.004"`, the one deliberate exception, because a rate is routinely finer than a minor unit |

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