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
per_page	integer	No	10	Items per page (min: 1, max: 100).
sort	string	No	newest issued first	Sort order: issued_at or number. Prefix with - for descending.
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, a customer that is neither a UUID nor an email, an out-of-range per_page, or an unknown sort field — returns a 400 (see Bad Request).

Ordering: Invoices default to newest issued first, with unissued (pending) invoices last, unless sort is supplied.

Counting matches: every response includes the filtered total in pagination.total. To get only a count, request per_page=1 with your filters and read pagination.total.

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": "001fd355-2cd4-4bb1-9fca-cf30e5eb76a8",
      "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": "office@company.example",
      "issued_at": "2026-06-04T14:05:00+00:00",
      "remote_id": "884001"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 4,
    "per_page": 10,
    "total": 38
  }
}

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)
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.

Pagination Object

Field	Type	Description
current_page	integer	Current page number
total_pages	integer	Total number of pages
per_page	integer	Effective page size (echoes the per_page request parameter)
total	integer	Total number of invoices matching the applied filters, across all pages

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 Error (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."
}