Invoice
Some merchants pay Peer's fee off-chain, by invoice. If you are one of them, this endpoint
returns what you owe for a finished time range, so you can pay without waiting for a manual
invoice. Every other merchant gets 404.
Get an invoice
GET /api/v1/merchants/me/invoice?from=2026-11-09T00:00:00Z&to=2026-11-16T00:00:00Z
X-API-Key: <your key>
Uses your API key, and the IP allowlist applies as on the other API key routes.
Query parameters
| Parameter | Type | Description |
|---|---|---|
from | string | Start of the range, included. An ISO 8601 timestamp with Z or a numeric offset and at most millisecond precision, such as 2026-11-09T00:00:00Z or 2026-11-09T00:00:00.000Z. Required |
to | string | End of the range, excluded. Same format. Required |
tomust be afterfrom, and the range can be at most 366 days.tomust be at least 5 minutes in the past. Orders completing right at "now" may not be recorded yet, so a range is billable only once it has settled. After that, no more orders land in it.- A date without a time, a time without
Zor an offset, or fractional seconds finer than milliseconds (more than 3 digits) is rejected, and so is any other query parameter. - If
fromis before the date your invoice billing started, the invoice starts at that date.windowin the response shows the range actually used. If the whole range is before that date,amountDueUsdcis0.00andwindow.fromequalswindow.to.
Response
type MerchantInvoice = {
merchantId: string;
window: { from: string; to: string };
amountDueUsdc: string;
};
| Field | Description |
|---|---|
merchantId | Your merchant id |
window | The range used: from included, to excluded, ISO 8601 in UTC. from is later than you asked for when your invoice billing started after it |
amountDueUsdc | What you owe in USDC, with 2 decimals, worked out as below |
How the amount is worked out:
- An order counts when it is
FULFILLEDand itscompletedAtis in the range.CREATED,PARTIALLY_FULFILLEDandCANCELLEDorders are not counted; an order paid in parts counts in the range where it completes. - An order counts at its gross
requestedUsdcAmount, not the net USDC that settled. An order that completed within its completion threshold still counts at its full requested amount. - The fee is your invoiced rate, such as 4.5%, applied to the gross requested USDC of the counted orders, and rounded half-up to the cent once, on the total. Your current rate applies to the whole range.
- Because the fee is rounded once on the total, not per order, it can differ by a cent from a sum of per-order fees you work out yourself.
For the individual orders, page through GET /api/v1/merchants/me/orders
with status=FULFILLED; it has no date filter, so keep those whose completedAt is in window.
{
"success": true,
"message": "Invoice computed",
"responseObject": {
"merchantId": "cmf5k2x9d0000abcd1234wxyz",
"window": { "from": "2026-11-09T00:00:00.000Z", "to": "2026-11-16T00:00:00.000Z" },
"amountDueUsdc": "13.50"
},
"statusCode": 200
}
Example
A weekly invoice that ends each Monday 00:00 UTC. Start every range where your last paid range ended, not at a fixed weekday, so no order is billed twice or missed (see Paying automatically).
Your first range starts where your last invoice from Peer ended. If that invoice ended at 2026-11-02 01:00 UTC, then on Monday 2026-11-09, any time after 00:05 UTC, ask for:
curl "https://api.pay.peer.xyz/api/v1/merchants/me/invoice?from=2026-11-02T01:00:00Z&to=2026-11-09T00:00:00Z" \
-H "X-API-Key: $ZKPAY_API_KEY"
The next Monday, start at that range's window.to:
curl "https://api.pay.peer.xyz/api/v1/merchants/me/invoice?from=2026-11-09T00:00:00.000Z&to=2026-11-16T00:00:00Z" \
-H "X-API-Key: $ZKPAY_API_KEY"
The same from code. lastPaidTo is the window.to of the last range you paid, kept in your own
records and seeded with the end of your last invoice from Peer. URLSearchParams encodes the
values for you:
// The end of the last range you paid, from your own records.
const lastPaidTo = await loadLastPaidTo(); // e.g. '2026-11-02T01:00:00Z' before the first run
// Monday 00:00 UTC of the current week.
const thisMonday = new Date();
thisMonday.setUTCHours(0, 0, 0, 0);
thisMonday.setUTCDate(thisMonday.getUTCDate() - ((thisMonday.getUTCDay() + 6) % 7));
if (thisMonday.getTime() <= Date.parse(lastPaidTo)) {
throw new Error('Nothing new to invoice yet');
}
const url = new URL('https://api.pay.peer.xyz/api/v1/merchants/me/invoice');
url.searchParams.set('from', lastPaidTo);
url.searchParams.set('to', thisMonday.toISOString());
const response = await fetch(url, { headers: { 'X-API-Key': process.env.ZKPAY_API_KEY! } });
const body = (await response.json()) as {
success: boolean;
message: string;
responseObject: MerchantInvoice | null;
statusCode: number;
};
if (!body.success || body.responseObject === null) {
throw new Error(`${body.statusCode}: ${body.message}`);
}
const { amountDueUsdc, window } = body.responseObject; // "13.50"
// After paying amountDueUsdc, save window.to as the next lastPaidTo.
With the CLI:
peer-pay-cli fees invoice --from 2026-11-02T01:00:00Z --to 2026-11-09T00:00:00Z
Errors
| Status | Message | Cause |
|---|---|---|
400 | Invalid request | from or to is missing, not a timestamp with Z or an offset, or finer than milliseconds, to is not after from, the range is over 366 days, or the query has another parameter. Field errors are in responseObject.fieldErrors; an extra parameter is reported in responseObject.formErrors |
400 | to must be at least 5 minutes in the past | The range has not settled yet. Retry once to is 5 minutes old |
404 | Merchant is not billed by invoice | Your merchant is not billed by invoice. Sandbox keys always get this; see notes |
The common errors also apply: 401 for a missing or invalid key, 403
from the IP allowlist, and 429 past the rate limit.
Paying automatically
- Chain your ranges: start each one at the
window.toof the last range you paid, and start the first one where your last invoice from Peer ended. Ranges pinned to a fixed weekday overlap or leave gaps whenever a previous range ended at a different time. An overlap bills the orders in it twice, and a dedupe key onwindowcan't catch that because the two ranges have different ends. - Pay
amountDueUsdcin USDC on Base to the address you agreed with Peer. Peer gives advance notice before that address changes. - Once a range has settled, its
amountDueUsdcdoesn't change unless Peer changes your fee terms, which happens only with advance notice. Usewindow.fromandwindow.toas the payment's dedupe key so each window is paid once, and retrying is safe. Only savewindow.toas your next start after the payment succeeds.
Notes
-
Ask after a range has settled:
tomust be at least 5 minutes before your request. For a weekly invoice ending Monday 00:00 UTC, call after 00:05 UTC. -
Sandbox keys belong to a separate sandbox merchant, which is not billed by invoice, so they get
404. Test against the CLI local simulator instead, with a range that covers your local orders:peer-pay-cli --local local settings --data '{"invoicedFeeBps":450}'
peer-pay-cli --local fees invoice --from 2026-11-09T00:00:00Z --to 2026-11-16T00:00:00ZThe local invoice has no billing start date.
-
In a raw query string, send a
+offset as%2B, as infrom=2026-11-09T09:00:00%2B09:00, or useZ. An unencoded+decodes to a space and the request fails withInvalid request.