Invoices

Two kinds of invoice, on two routes, because they mean different things:

• Platform invoices: what United Pet Club charged the business — its plans and add-ons, and its settled platform fees.
• Client invoices: what the business invoiced its own clients in its United Pet Club books (Dashboard → Finances → Invoices).

Both are read for the business that connected your app.

Access

• A token from the authorization-code grant. A client-credentials token answers 403 0010010000406.
• The business must keep a valid payment card on file; without one, 403 0010010000407.
• Scope billing:read, declared by your app and granted by the business on the consent page — see Business resources.

Platform invoices

GET /api/billing/v1/platform-invoices?status=PAID&page=1&pageSize=20
GET /api/billing/v1/platform-invoices/{id}

status (any case): BILLED, PAID, FAILED, REFUNDED. Newest first. A list may reach at most 1,000 invoices deep (page × pageSize ≤ 1000); past that it answers 400 — filter by status to go further.

{
  "data": [
    {
      "id": "3f2a9c1b-7d10-4b0e-9c52-81e0a4b6d2f3",
      "number": "SUB-3F2A9C1B-04",
      "kind": "PLAN",
      "status": "PAID",
      "currency": "USD",
      "subtotalMinorUnits": 2000,
      "taxMinorUnits": 260,
      "totalMinorUnits": 2260,
      "refundedMinorUnits": 0,
      "totalAmount": 22.60,
      "issuedAt": "2026-09-01T00:00:00Z",
      "paidAt": "2026-09-01T00:05:00Z",
      "periodStart": "2026-09-01T00:00:00Z",
      "periodEnd": "2026-10-01T00:00:00Z",
      "periodMonth": null,
      "subscriptionId": "3f2a9c1b-0000-4000-8000-000000000001",
      "planCode": "PET_PRO",
      "cadence": "MONTHLY"
    }
  ],
  "pagination": { "page": 1, "pageSize": 20, "total": 1 }
}

Field	Meaning
kind	PLAN: one billing cycle of a plan, add-on or pack the business bought. PLATFORM_FEES: a settled monthly platform-fee charge.
number	SUB-… for a plan cycle, FEE-{yyyyMM}-… for platform fees.
status	BILLED, PAID, FAILED, REFUNDED. A platform-fee invoice is always PAID.
*MinorUnits	Amounts in minor units of currency; taxMinorUnits is GST/HST for a Canadian business, else 0. totalAmount is the total in major units.
periodStart, periodEnd	The plan cycle, or the fee month. periodMonth (yyyy-MM) is set for platform fees.
subscriptionId, planCode, cadence	Plan invoices only.

Platform fees are charged to the account that owns the business, so if that account owns several businesses, one platform-fee invoice can cover all of them.

/api/billing/v1/invoices and /api/billing/v1/invoices/{id} are aliases of the platform-invoice routes.

Client invoices

GET /api/billing/v1/client-invoices?status=OVERDUE&page=1&pageSize=20
GET /api/billing/v1/client-invoices/{id}?locale=fr-CA

status (any case): ISSUED, OVERDUE (issued and past its due date), VOID. Drafts never appear. Newest first. locale names the language of the line categories (default en-US).

{
  "id": "9b0e2c7a-41f5-4d8e-a3c6-2f7d1e5b8a90",
  "number": "42",
  "status": "ISSUED",
  "isOverdue": false,
  "currency": "CAD",
  "totalAmount": 123.45,
  "issuedAt": "2026-10-02T00:00:00Z",
  "dueAt": "2026-11-01T00:00:00Z",
  "paidAt": null,
  "voidedAt": null,
  "counterpartyId": "5d3c1a8e-6f20-4b9d-8e71-0a4c2b9f6e13",
  "clientName": "Jane Client",
  "reference": "INV-42",
  "description": "Grooming",
  "lines": [
    { "lineNo": 1, "category": "Grooming services", "memo": "Full groom", "amount": 133.45 },
    { "lineNo": 2, "category": "Discounts", "memo": "Loyalty", "amount": -10.00 }
  ]
}

Field	Meaning
number	The invoice number the business sees (“Invoice #42”).
status, isOverdue	ISSUED or VOID; isOverdue is true for an issued invoice past dueAt.
totalAmount, lines[].amount	Major units of currency. A discount line is negative.
paidAt	Always null today: the books do not record payments against an invoice yet.
counterpartyId, clientName	The client in the business’s books. counterpartyId is not a client id of the client list.
lines	On a get by id only; null in a list.

Errors

Status	platformResponseCode	Cause
400	0010010000400	page or pageSize out of range, or a platform-invoice page deeper than 1,000.
400	Subscription_SubscriptionPlatform_VL_Request_RJ, Payout_PayoutPlatform_VL_Request_RJ, Accounting_Platform_VL_Request_RJ	An unknown status.
404	Subscription_SubscriptionPlatform_GT_Resource_FL, Payout_PayoutPlatform_GT_Resource_FL, Accounting_Bookkeeping_GT_Document_FL	No such invoice for this business. Another business’s invoice answers the same.
503	Payout_PayoutLedger_GT_Profile_FL	The business’s owner could not be looked up right now, so its platform-fee invoices could not be read. Retry with backoff; never read it as “no invoices”.

Everything else follows Errors.