Invoices overview

An invoice is how you ask a client to pay you for work you've done. This page explains how invoices
fit into the V3 API, what record an invoice is billed to, and what each side of the exchange sees.

In V1, the contractor was the "member" and the company paying was the "client", and an invoice was
addressed to a memberClientId. In V3, the party issuing the invoice is the payee, the party
paying it is the payer, and the invoice is addressed to a Payer record.

The pieces

Every invoice is owned by the Account that issued it. Invoice.accountId is your Account (the
payee). The Account you're billing appears as payerAccountId once the Payer record is linked to a
real Account, and stays null until then.

How an invoice flows

1. You create a Payer for your client (or reuse one you already have).
2. You create an invoice addressed to that Payer. It starts in Created, where you can still edit
   or delete it.
3. You send it. It moves to Opened, and Wingspan emails it to the payer.
4. The payer pays, or you collect from a payment method the payer has authorized, either with a
   pay call or automatically. The invoice moves through PaymentInTransit to Paid.
5. Wingspan pays out your proceeds, net of any fees charged to you.

The invoice lifecycle page covers every status, including overdue,
disputed, refunded, and paid outside Wingspan.

sequenceDiagram
    participant Payee as Payee (you)
    participant WS as Wingspan
    participant Payer as Payer (your client)
    Payee->>WS: POST /v3/payments/payers
    Payee->>WS: POST /v3/payments/invoices
    Payee->>WS: POST /v3/payments/invoices/{invoiceId}/send
    WS->>Payer: Invoice email
    Payer->>WS: Pays (saved method, payment link, or off platform)
    WS-->>Payee: Invoice.Paid, then Invoice.DepositConfirmed

Who sees what

An invoice and a payable are two views of one obligation. Each side sees the view that matches its
role, and each side can change only the fields it owns. Shared fields are controlled by whoever
created the obligation, and lifecycle and payment fields are set by Wingspan.

A few consequences of this model:

• The Payer record is yours. A Payer is your record of a client. Creating one doesn't create an
  Account or a Person for the client, and you can invoice an unlinked Payer. Linking is optional.
  See Payee and payer account linking.
• Expansions are caller-relative. GET /v3/payments/invoices/{invoiceId}?expand=payer
  returns the Payer record only if you can read it directly. A view you can't read is left out
  rather than returned in a reduced form.
• The payer-view token is a secret. Anyone holding payerInvoiceViewToken can read the limited
  invoice view. Don't log it or send it to analytics tools.

Invoicing policy set by the payer

A payer can publish an invoicing policy that tells payees what it accepts, for example which
currencies, a fixed due date, a menu of allowed line items, or whether attachments and PO numbers
are required. As the payer, read and update it with GET and PATCH /v3/payments/invoicing-configs.
As a payee, read a payer's policy with GET /v3/payments/invoicing-configs/payers/{payerAccountId}.
This works only when you have a relationship with that payer. Check it before you draft invoices to
a new client.

Where to go next

• Components of an invoice lists every field.
• Create an invoice walks through the calls.
• Collect payment covers how the payer pays.
• The create an invoice recipe is a complete end-to-end example.