Organization API: Billing & Payouts: Staff

Part of Billing & Payouts.

GET /api/v1/orgs/{org_slug}/staff/invoices

Invoices, paying customers' first. Reading invoices is Tier 3 support and up, as the invoice's PDF and the refund queue are, so a ticket about a charge is answered without escalating; moving money is billing's.

POST /api/v1/orgs/{org_slug}/staff/invoices

Raise an invoice by hand: a setup fee, an add-on, a correction, or several of them on one invoice.

Each line comes to its quantity times its unit price, rounded half up to the currency's smallest unit (the cent, the yen), since that is what a gateway can charge; the subtotal is the sum of those lines and tax, rounded the same way, is added to it. A line tied to an order must be an order of the same customer.

With send_email the issued invoice email goes to the customer once the invoice is saved; when it went, metadata.last_sent records it ({at, to, template}, as POST staff/invoices/{invoice_id}/send writes it) and the answer carries it as last_sent, otherwise null.

application/json (required)

GET /api/v1/orgs/{org_slug}/staff/invoices/export.csv

Every invoice in the window, as a CSV.

GET /api/v1/orgs/{org_slug}/staff/invoices/stats

One count per invoice status for the tiles above the list, under the audience the request carries: all, due (unpaid and overdue), unpaid, overdue, paid, cancelled and refunded. Reading invoices is Tier 3 support and up.

The counts cover the whole brand. They are normally under a minute old, and the first request after a quiet spell can show numbers a few minutes old. The invoice list is always current.

GET /api/v1/orgs/{org_slug}/staff/invoices/{invoice_id}

PATCH /api/v1/orgs/{org_slug}/staff/invoices/{invoice_id}

application/json (required)

POST /api/v1/orgs/{org_slug}/staff/invoices/{invoice_id}/cancel

Close an invoice nobody should pay. A paid one is refunded, not cancelled.

Cancelling an unpaid or overdue invoice writes off money the customer owes, so it takes a step-up (403 reauth_required without one); a draft, which nobody was sent, does not.

Wallet credit applied to part of the invoice goes back to the wallet, the exact amount the wallet lost to it (its credit ledger rows), with a ledger row and a credit_add row naming the invoice; the answer's credit_returned says how much, in the wallet's dollars, or is null. Money a gateway took for part of it cannot stay on a cancelled invoice and the refund route takes only a paid one, so that answers 409 and nothing changes. The admin console's cancel does the same (cancel_org_invoice).

application/json

POST /api/v1/orgs/{org_slug}/staff/invoices/{invoice_id}/charge

Charge the customer's saved method for an unpaid invoice now, the way the dunning job would on its next attempt. Skipped, not forced, when the customer has turned auto-pay off or a payment is still settling.

POST /api/v1/orgs/{org_slug}/staff/invoices/{invoice_id}/mark-paid

GET /api/v1/orgs/{org_slug}/staff/invoices/{invoice_id}/pdf

The same document the customer downloads from their portal.

POST /api/v1/orgs/{org_slug}/staff/invoices/{invoice_id}/refund

Refund a paid invoice on staff's own decision (a goodwill gesture, a duplicate charge, a mistake), in full or in part, to the payment method or the wallet. Recorded as a refund request staff opened and approved, so the ledger, the invoice, the service and the audit log move exactly as they do for a request the customer made.

application/json (required)

POST /api/v1/orgs/{org_slug}/staff/invoices/{invoice_id}/send

Send the invoice email again: the issued one for an open invoice, the overdue one once it is past due. Nothing about the invoice changes but metadata.last_sent ({at, to, template}: when, to which address and which email), written when the email went and answered by GET invoices/{invoice_id} so the page can say it was sent.