> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyperprop.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Billing and invoices

> Read the invoices Hyperprop issues to your organization, download PDFs, get bank transfer instructions, track usage and credits, and manage your billing details with your API key.

Your organization's Hyperprop bill is available through the API, so you can
show it in your own finance tools: what you owe, what this month is costing so
far, and the line items behind it.

All endpoints here are under `/organization/billing`. Reads work with a
[read-only key](https://docs.hyperprop.com/authentication.md#read-only-keys); 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

```bash theme={null}
curl "https://api.hyperprop.com/platform/v1/organization/billing/invoices?status=open" \
  -H "X-API-Key: hp_live_your_key_here"
```

You only see issued invoices:

| `status` | Meaning |
| - | - |
| `open` | Issued and awaiting payment |
| `paid` | Paid in full |
| `uncollectible` | Written off by Hyperprop |

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.

### PDF

`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):

```json theme={null}
{
  "success": true,
  "data": {
    "currency": "usd",
    "amountRemainingCents": 2860000,
    "reference": "HP-0042",
    "bankTransfer": {
      "type": "us_bank_transfer",
      "addresses": [
        { "type": "aba", "accountHolderName": "Hyperprop B.V.", "bankName": "Example Bank, N.A.", "accountNumber": "000123456789", "routingNumber": "110000000", "accountType": "checking" },
        { "type": "swift", "accountHolderName": "Hyperprop B.V.", "bankName": "Example Bank, N.A.", "accountNumber": "000123456789", "swiftCode": "EXAMUS33", "accountType": "checking" }
      ]
    }
  }
}
```

USD invoices list US account details (`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 (`estimate` is null when no agreement prices the month).
* `outstandingCents`, `overdueCents` and `unpaidCount` across issued invoices.
* `creditBalanceCents`: credit available for your next invoices.

For a per-trader breakdown, `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:

```csv theme={null}
Trader,Started,Trigger,Platform (USD),Market data (USD),Total (USD)
trader@example.com,2026-10-03,market data activated,22.00,0.00,22.00
```

The file is UTF-8 with a byte order mark. `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.

```bash theme={null}
curl "https://api.hyperprop.com/platform/v1/organization/billing/details" \
  -H "X-API-Key: hp_live_your_key_here"
```

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

```bash theme={null}
curl -X PUT "https://api.hyperprop.com/platform/v1/organization/billing/details" \
  -H "X-API-Key: hp_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "legalName": "Example Trading Ltd.",
    "billingEmail": "ap@example.com",
    "ccEmails": ["finance@example.com"],
    "address": { "line1": "Herengracht 100", "city": "Amsterdam", "postalCode": "1015 BS", "country": "NL" },
    "taxId": { "type": "eu_vat", "value": "NL123456789B01" }
  }'
```

`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.

> [!WARNING]
>
> Once complete details are saved, they are **locked** (`locked: true`): further
> updates return `403 BILLING_DETAILS_LOCKED`. Check the details before you send
> the final version, and contact Hyperprop at [finance@hyperprop.com](mailto:finance@hyperprop.com) to change
> locked details.

## Limits

| Endpoint | Limit per organization |
| - | - |
| Invoice PDF | 30 a minute |
| Payment instructions | 30 a minute |
| Billing details update | 20 per 10 minutes |
| Line items CSV export | 10 a minute |

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.


## Related topics

- [Get an invoice](https://docs.hyperprop.com/platform-api/billing-and-invoices/get-an-invoice.md)
- [List invoices](https://docs.hyperprop.com/platform-api/billing-and-invoices/list-invoices.md)
- [Download an invoice PDF](https://docs.hyperprop.com/platform-api/billing-and-invoices/download-an-invoice-pdf.md)
- [Get bank transfer instructions](https://docs.hyperprop.com/platform-api/billing-and-invoices/get-bank-transfer-instructions.md)
- [Build your own CRM on Hyperprop](https://docs.hyperprop.com/guides/build-a-crm.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.