Invoices API

REST API endpoints for reading invoices.

Invoices are issued by the platform as orders are paid – this resource is read-only. To configure whether invoices are issued, or to set the footer note printed on them, use the invoiceSettings group on PATCH /api/v1/settings.

Scope: orders:read.

Order visibility. A request made for a person – through an OAuth app or the AI Assistant – only reaches the invoices of orders that person's role may see: the others are missing from the list and answer 404 on GET /api/v1/invoices/:id. API keys see every invoice.

List Invoices

GET /api/v1/invoices

Query Parameters

curl -H "Authorization: Bearer your_api_key" \
  https://your-store.yns.store/api/v1/invoices

Response

{
  "data": [
    {
      "id": "0191abc0-1234-7def-8000-000000000001",
      "invoiceNumber": "FV 1/08/2025",
      "invoiceIndex": 1,
      "series": null,
      "buyerType": "consumer",
      "orderId": "0191abc0-5678-7def-8000-000000000001",
      "orderLookup": "ORD-1234",
      "environment": "live",
      "storeAddress": {
        "name": "Acme Goods",
        "street": "123 Main St",
        "city": "Warsaw",
        "zip": "00-001",
        "country": "PL"
      },
      "createdAt": "2025-08-01T12:00:00.000Z",
      "updatedAt": "2025-08-01T12:00:00.000Z"
    }
  ],
  "meta": {
    "total": 42,
    "offset": 0,
    "limit": 20
  }
}

series is the numbering series the number was counted in: "b2b" (company buyer) or "b2c" (consumer) while the store numbers consumer invoices separately (invoiceSettings.b2c on Settings), and null for the store's single shared series.

buyerType says who bought: "company" when the buyer's billing address (or the shipping address if there is none) has a valid NIP or EU VAT ID, "consumer" otherwise. It's set whether or not the store numbers consumer invoices separately. It can be null on invoices issued before November 2026 until they're backfilled.

Get Invoice

GET /api/v1/invoices/:id

Returns a single invoice by UUID. Returns 404 if the invoice does not exist in this store.

curl -H "Authorization: Bearer your_api_key" \
  https://your-store.yns.store/api/v1/invoices/0191abc0-1234-7def-8000-000000000001

Returns the same shape as a single item from the list response.