# Invoices

One invoice per calendar month per environment, listing the seats you were charged for. Read it with your API key, reconcile it against [match results](/docs/results.md), and pay it by bank transfer.

## What you are charged for

A *seat* is one player entering one paid match, charged [per seat](/docs/paid-play.md). Practice and free play are never charged, and neither is anything played with a test key.

## Listing them

```
GET /partner/invoices
Authorization: Bearer pgs_live_…
```

The environment comes from your key, so a live key never returns a sandbox invoice. `from` and `to` take the same `yyyymmdd` range as the usage meter and are optional for this list. Add `status` to filter — `issued`, `paid` or `void`.

```
{
  "environment": "live",
  "invoices": [
    {
      "invoiceId": "inv_01J8…",
      "status": "issued",
      "periodFromDay": "20260801",
      "periodToDay": "20260831",
      "currency": "USD",
      "totalMicros": 1250000,
      "seatCount": 50,
      "issuedAt": 1756684800,
      "dueAt": 1759276800
    }
  ],
  "nextCursor": null
}
```

Pass `nextCursor` back as `cursor` for the next page.

> **Stop on a null cursor, never on an empty page.** A page can come back with no invoices and a cursor still set — loop until `nextCursor` is `null`, or you will stop short of invoices that are there.

> **A `…Micros` field is micro-USD — millionths of a dollar.** Divide by 1,000,000 for dollars: `totalMicros: 1250000` above is $1.25. A `…UsdCents` field is plain cents. The fee on the $1 tier is 2.5¢, which no integer-cent field can hold — booking these as cents loses half of it on every seat.

## One invoice

```
GET /partner/invoices/{invoiceId}
```

The same fields plus the `number` and `paymentReference` — quote the reference on the transfer — and `subtotalMicros`, `taxMicros`, `taxTreatment`, `taxRateBps`, and `seller` and `buyer` — both parties’ registered name, address, country and VAT number as they stood when the invoice was issued. An address that changes afterwards does not rewrite an invoice you have already been sent.

## The lines

```
GET /partner/invoices/{invoiceId}/lines
```

One row per seat, paginated by the same `cursor`, under the same stop rule. Each carries `matchId`, `tierId`, `prizeUsdCents`, `feeUsdMicros` and `at`. Join on `matchId` to reconcile a line against the match it came from.

## As a spreadsheet

```
GET /partner/invoices/{invoiceId}/lines?format=csv
```

The same rows as `text/csv`, paginated the same way — the cursor for the next page comes back in the `x-next-cursor` response header, since a CSV body has nowhere to carry one. A response with no such header is the last page.

Only the first page carries the header row, so the pages concatenate into one file. Cells that would otherwise be read as a spreadsheet formula are prefixed with an apostrophe, so open the file rather than trusting a raw byte comparison against the JSON.

## Which tiers earn what

A per-day, per-tier fold of the seats we recorded a fee for — the number to watch your own pricing against without waiting for a period to close.

```
GET /partner/seat-summary?from=20260801&to=20260831
Authorization: Bearer pgs_live_…

200 {
  "environment": "live",
  "fromDay": "20260801",
  "toDay": "20260831",
  "rows": [
    { "day": "20260801", "tierId": "usd_1", "seats": 42,
      "theirStakeUsdCents": 2520, "theirStakeSeats": 42,
      "feeUsdMicros": 1050000 }
  ]
}
```

`from` and `to` take the same `yyyymmdd` range as the usage meter. Both are required here, and refuse with the same codes — see [errors and limits](/docs/errors#reading-your-seat-summary.md). One row per `day` and `tierId` present in that fold; a day and tier with none was never written.

> **`theirStakeSeats` can be lower than `seats`.** `theirStakeUsdCents` sums only the seats that recorded a price, and `theirStakeSeats` counts how many of `seats` are in that sum — read the two together, or a partial total reads as a complete one.

> **`theirStakeUsdCents` is cents; `feeUsdMicros` is micro-USD, as above.** 2520 is $25.20; 1050000 is $1.05.

> **`day` is when the match was decided, not when the seat was taken.** A match seated late on one day but decided the next lands in the next day’s bucket, not the one your own seat log would put it in — that is the seam to expect if you reconcile against seat time rather than match time. Reconcile a bill against the invoice lines above instead: an invoice is defined by the rows it claimed when it was issued, while this view is defined by whatever date range you hand it.

> **A window with too much history to fold in one call is refused, not answered short.** Ask for a narrower `from`/`to` range rather than retrying the same one.

## Paying

Bank transfer, quoting `paymentReference` — that is how a transfer is matched to an invoice. Payment is recorded against the invoice and `status` becomes `paid`; a partial payment leaves it `issued` until the balance arrives.

A `void` invoice has been cancelled and is not payable. It stays readable so a reference you hold can still be looked up.