Skip to main content

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​

ParameterTypeDescription
fromstringStart 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
tostringEnd of the range, excluded. Same format. Required
  • to must be after from, and the range can be at most 366 days.
  • to must 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 Z or an offset, or fractional seconds finer than milliseconds (more than 3 digits) is rejected, and so is any other query parameter.
  • If from is before the date your invoice billing started, the invoice starts at that date. window in the response shows the range actually used. If the whole range is before that date, amountDueUsdc is 0.00 and window.from equals window.to.

Response​

type MerchantInvoice = {
merchantId: string;
window: { from: string; to: string };
amountDueUsdc: string;
};
FieldDescription
merchantIdYour merchant id
windowThe range used: from included, to excluded, ISO 8601 in UTC. from is later than you asked for when your invoice billing started after it
amountDueUsdcWhat you owe in USDC, with 2 decimals, worked out as below

How the amount is worked out:

  • An order counts when it is FULFILLED and its completedAt is in the range. CREATED, PARTIALLY_FULFILLED and CANCELLED orders 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​

StatusMessageCause
400Invalid requestfrom 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
400to must be at least 5 minutes in the pastThe range has not settled yet. Retry once to is 5 minutes old
404Merchant is not billed by invoiceYour 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.to of 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 on window can't catch that because the two ranges have different ends.
  • Pay amountDueUsdc in USDC on Base to the address you agreed with Peer. Peer gives advance notice before that address changes.
  • Once a range has settled, its amountDueUsdc doesn't change unless Peer changes your fee terms, which happens only with advance notice. Use window.from and window.to as the payment's dedupe key so each window is paid once, and retrying is safe. Only save window.to as your next start after the payment succeeds.

Notes​

  • Ask after a range has settled: to must 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:00Z

    The local invoice has no billing start date.

  • In a raw query string, send a + offset as %2B, as in from=2026-11-09T09:00:00%2B09:00, or use Z. An unencoded + decodes to a space and the request fails with Invalid request.