Get Invoices

Retrieve a list of invoices issued by your store.

Invoices are returned newest first, by issue date. Narrow the list with the optional filters below — for example status=error to return Polish invoices that were not accepted by the government tax system, or customer=buyer@example.com to return one customer's invoices. All filters combine with AND.

Request

GET /invoices

Query Parameters

Parameter	Type	Required	Default	Description
page	integer	No	1	Page number for pagination
type	string	No	—	Filter by document type. One of invoice, correction.
status	string	No	—	Filter by status. One of issued, pending, error.
gov_status	string	No	—	Filter Polish invoices by KSeF delivery status (e.g. ok, send_error). See KSeF status.
issued_from	string	No	—	Only invoices issued on or after this date (inclusive), YYYY-MM-DD.
issued_to	string	No	—	Only invoices issued on or before this date (inclusive), YYYY-MM-DD.
number	string	No	—	Partial, case-insensitive match on the invoice number.
customer	string	No	—	Filter by customer — either a customer UUID or an email address.
transaction_id	string	No	—	Only invoices for this transaction (UUID).
order_id	string	No	—	Only invoices for this order (UUID).

Omitting a filter or passing it empty means "no filter on that field". Passing a non-empty but unparseable value — an unknown type / status / gov_status, a malformed date, or a customer that is neither a UUID nor an email — returns a 400 (see Bad Request).

Example Request

curl -X GET "https://cart.easy.tools/api/v1/invoices?status=issued&page=1" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

Success Response (200)

Returns a paginated list of invoices.

{
  "items": [
    {
      "id": "5b2c0f2e-1d4a-4c8b-9f3a-7e1a2b3c4d5e",
      "number": "EASY/2026/06/123",
      "type": "invoice",
      "status": "issued",
      "total": 12300,
      "currency": "pln",
      "customer_email": "anna.kowalska@example.com",
      "issued_at": "2026-06-05T10:20:00+00:00",
      "remote_id": "884512"
    },
    {
      "id": "9a1f7c33-8e0b-4a21-bb6d-2c9e5f0a1b22",
      "number": "EASY-K/2026/06/12",
      "type": "correction",
      "status": "issued",
      "total": 4100,
      "currency": "pln",
      "customer_email": "biuro@firma.example",
      "issued_at": "2026-06-04T14:05:00+00:00",
      "remote_id": "884001"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 4
  }
}

Response Fields

Field	Type	Nullable	Description
id	string	No	Unique identifier for the invoice (UUID)
number	string	Yes	Invoice number. Null until the invoice has a number assigned.
type	string	No	Document type: invoice or correction.
status	string	No	Derived status: issued, pending, or error.
total	integer	No	Gross total in minor units (e.g. cents/grosze)
currency	string	No	Lowercase ISO currency code (e.g. "pln", "eur")
customer_email	string	Yes	Billing email recorded on the invoice
issued_at	string	Yes	When the invoice was issued (ISO 8601 format). Null while pending.
remote_id	string	Yes	The invoice's id with the issuing service, useful for reconciliation

To read the line items, billing details, KSeF status, PDF link, or the related transaction, order, and customer, call Get Invoice.

Error Responses

Bad Request (400)

Returned when a filter has a non-empty but unparseable value. The message names the offending field and the value received.

{
  "message": "Invalid value for 'status': 'paid'"
}

Unauthorized (401)

{
  "message": "Unauthenticated."
}

Unavailable (422)

Returned when your store does not issue invoices through EasyTools invoicing.

{
  "message": "Invoices are only available for stores using Easybilling."
}