/organization/billing. Reads work with a
read-only key; updating billing details needs
a full-access key. Amounts are integers in cents of the invoice currency
(usd or eur). Billing months follow the America/Chicago calendar.
How billing works
- During a month, Hyperprop counts the traders who use each market family (CME futures, crypto perpetuals) and any fixed monthly fees in your agreement.
- After a month ends, a month-end invoice bills the rest of that month, including any minimums. Hyperprop can also issue an interim invoice during a month for usage up to a cut-off; minimums are only applied on the month-end invoice.
- Invoices are paid by bank transfer. Available credit is applied automatically when an invoice is issued.
Invoices
Invoices Hyperprop is still preparing, and voided invoices, are never
returned; fetching one by ID returns
404 INVOICE_NOT_FOUND. When Hyperprop
corrects an invoice, the voided one is replaced by a new invoice with a higher
revision and replacesNumber set to the old number.
For display, use displayStatus: it adds overdue (open past dueDate) and
pending (open and partly funded by a bank transfer). amountRemainingCents
is what is still to pay.
The list is not paginated: an organization receives a few invoices a month.
To mirror invoices, store them by id and refresh those that are not paid
yet, since payment fields change as transfers arrive.
GET /billing/invoices/{invoiceId} adds the invoice lines, the trader-months
it bills (usage) and explain, plain-language notes on how minimums and
first-month proration were applied.
GET /billing/invoices/{invoiceId}/pdf returns a short-lived link in
data.url. Download the file right away rather than storing the link. Add
?redirect=true to get a 302 straight to the PDF instead. A 409 NO_PDF
means the PDF is not ready yet.
Paying by bank transfer
GET /billing/invoices/{invoiceId}/payment-instructions returns the bank
account to pay an open invoice into and the reference to quote (the invoice
number):
aba for ACH or domestic wire,
swift for international wire); EUR invoices list an iban. The details are
specific to your organization. bankTransfer is null when the invoice is not
open.
This month so far
GET /billing/usage shows the current month before it is invoiced:
unbilledUnits: trader-months per family not on any invoice yet.estimate.monthEndCents: the month-end invoice if the month ended now, minimums included (estimateis null when no agreement prices the month).outstandingCents,overdueCentsandunpaidCountacross issued invoices.creditBalanceCents: credit available for your next invoices.
GET /billing/summary?month=YYYY-MM lists every
charge of a month with paging, and GET /billing/line-items/export?month=YYYY-MM
returns the same rows as one CSV file:
Trigger is market data activated
(the trader’s first billing cycle) or monthly charge (a renewal).
Credits
GET /billing/credits returns your balanceCents and every grant and
reversal. Credit is applied to your next invoices when they are issued, and
shows as creditAppliedCents on the invoice.
Billing details
The legal name, billing email, address and tax ID on your invoices. No invoice can be issued until they are complete.complete tells you whether everything is there, and missing lists the
fields still needed. To set them, send all fields with a full-access key:
PUT replaces every field, so a field you leave out is cleared. Each value is
checked; a rejected value returns 400 INVALID_BILLING_DETAILS with a
fields list, and nothing is saved.
Limits
Over a limit, the response is
429 RATE_LIMITED with a Retry-After header.
If billing is briefly unavailable, PDF and payment-instruction requests return
502 BILLING_UNAVAILABLE; retry shortly.