Get Invoice

Retrieve a specific invoice from your store.

By default the response contains the invoice's fields, its line items, the bill-to details, a link to the PDF, and — for Polish invoices — the KSeF delivery status. Use the include query parameter to expand the related transaction, order, customer, and any correction documents in the same call.

Request

GET /invoices/{id}

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Invoice UUID

Query Parameters

Parameter	Type	Required	Description
include	string	No	Comma-separated list of sections to expand. Allowed values: transaction, order, customer, corrections. Unknown values are ignored.

note

A section that is not requested is returned as null — the key is always present, so the response shape stays stable. The line items, billing details, PDF link, and KSeF block are always present and are not controlled by include.

Example Request

curl -X GET "https://cart.easy.tools/api/v1/invoices/5b2c0f2e-1d4a-4c8b-9f3a-7e1a2b3c4d5e?include=transaction,order,customer" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

Success Response (200)

Returns a single invoice. The example below is a Polish invoice reported to KSeF, with the transaction, order, and customer sections requested.

{
  "id": "5b2c0f2e-1d4a-4c8b-9f3a-7e1a2b3c4d5e",
  "number": "EASY/2026/06/123",
  "type": "invoice",
  "status": "issued",
  "total": 12300,
  "net_total": 10000,
  "tax_total": 2300,
  "currency": "pln",
  "customer_email": "anna.kowalska@example.com",
  "issued_at": "2026-06-05T10:20:00+00:00",
  "remote_id": "884512",
  "download_url": "https://cart.easy.tools/api/v1/invoices/5b2c0f2e-1d4a-4c8b-9f3a-7e1a2b3c4d5e/download?expires=1749384000&signature=abc123",
  "correction_of": null,
  "corrected_amount": null,
  "ksef": {
    "gov_id": "5660000000-20260605-0A1B2C3D4E5F-12",
    "status": "ok",
    "error": null
  },
  "line_items": [
    {
      "name": "Vue.js Course — annual access",
      "amount": 12300,
      "net_amount": 10000,
      "tax_amount": 2300,
      "tax_rate": 23.0,
      "quantity": 1,
      "currency": "pln",
      "reverse_charge": false,
      "exempt": false
    }
  ],
  "billing_data": {
    "name": "Anna Kowalska",
    "email": "anna.kowalska@example.com",
    "tax_id": "PL7010001234",
    "address": "ul. Przykładowa 12/3",
    "city": "Warszawa",
    "post_code": "00-001",
    "country": "PL",
    "country_state": null
  },
  "transaction": {
    "id": "1f0a9b8c-7d6e-5f4a-3b2c-1d0e9f8a7b6c",
    "remote_id": "pi_3QabcXYZ",
    "total": 12300,
    "currency": "pln",
    "paid_at": "2026-06-05T10:19:42+00:00"
  },
  "order": {
    "id": "e4d3c2b1-a0f9-4e8d-7c6b-5a4f3e2d1c0b",
    "product_name": "Vue.js Course",
    "status": "completed"
  },
  "customer": {
    "id": "0c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
    "email": "anna.kowalska@example.com",
    "name": "Anna Kowalska"
  },
  "corrections": null
}

An invoice not reported to KSeF has ksef set to null. A lean read (no include) returns the always-present sections with transaction, order, customer, and corrections set to null:

{
  "id": "b3d3fbf4-1de9-4f0c-9a43-7143a0a9d592",
  "number": "EASY/2026/06/42",
  "type": "invoice",
  "status": "issued",
  "total": 4212,
  "net_total": 3900,
  "tax_total": 312,
  "currency": "pln",
  "customer_email": "buyer@example.com",
  "issued_at": "2026-06-01T09:00:00+00:00",
  "remote_id": "509353518",
  "download_url": "https://cart.easy.tools/api/v1/invoices/b3d3fbf4-1de9-4f0c-9a43-7143a0a9d592/download?expires=1749384000&signature=abc123",
  "correction_of": null,
  "corrected_amount": null,
  "ksef": null,
  "line_items": [
    {
      "name": "Server add-on",
      "amount": 4212,
      "net_amount": 3900,
      "tax_amount": 312,
      "tax_rate": 8.0,
      "quantity": 1,
      "currency": "pln",
      "reverse_charge": false,
      "exempt": false
    }
  ],
  "billing_data": {
    "name": "Jan Nowak",
    "email": "buyer@example.com",
    "tax_id": "PL5251234560",
    "address": "123 Main Street",
    "city": "Springfield",
    "post_code": "90210",
    "country": "US",
    "country_state": null
  },
  "transaction": null,
  "order": null,
  "customer": null,
  "corrections": null
}

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)
net_total	integer	Yes	Net total in minor units. Null when the invoice has no line items.
tax_total	integer	Yes	Tax total in minor units. Null when the invoice has no line items.
currency	string	No	Lowercase ISO currency code (e.g. "pln")
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
download_url	string	No	A temporary signed link to download the invoice PDF. It needs no Authorization header and expires about an hour after the read.
correction_of	string	Yes	For a correction, the id (UUID) of the invoice it corrects. Null otherwise.
corrected_amount	integer	Yes	For a correction, the corrected gross amount in minor units. Null otherwise.
ksef	object	Yes	KSeF delivery status. null for non-Polish invoices.
line_items	array	No	The invoice's line items
billing_data	object	No	The bill-to details
transaction	object	Yes	The payment the invoice was issued for. null unless transaction is included.
order	object	Yes	The order the payment belongs to. null unless order is included.
customer	object	Yes	The customer the invoice was issued to. null unless customer is included.
corrections	array	Yes	Correction documents issued against this invoice. null unless corrections is included.

line_items[]

Field	Type	Nullable	Description
name	string	Yes	Line item name
amount	integer	No	Gross amount in minor units
net_amount	integer	Yes	Net amount in minor units
tax_amount	integer	Yes	Tax amount in minor units
tax_rate	number	No	Tax rate as a percentage (e.g. 23.0)
quantity	integer	No	Quantity
currency	string	No	Lowercase ISO currency code
reverse_charge	boolean	No	Whether the line uses the reverse-charge mechanism
exempt	boolean	No	Whether the line is tax-exempt

billing_data

Field	Type	Nullable	Description
name	string	Yes	Bill-to name
email	string	Yes	Bill-to email
tax_id	string	Yes	Bill-to tax identifier
address	string	Yes	Street address
city	string	Yes	City
post_code	string	Yes	Postal code
country	string	Yes	ISO-2 country code (e.g. "PL")
country_state	string	Yes	State/province code, when set

ksef

Present only for invoices reported to the KSeF system; null for all others.

Field	Type	Nullable	Description
gov_id	string	Yes	The reference number assigned by the government tax system
status	string	Yes	Delivery status. See KSeF status for the full list.
error	string	Yes	The delivery error message, when the document was not accepted by the government system

transaction

Field	Type	Nullable	Description
id	string	No	Transaction identifier (UUID)
remote_id	string	Yes	The provider's own transaction id
total	integer	No	Captured amount in minor units
currency	string	No	Lowercase ISO currency code
paid_at	string	Yes	When the payment was settled (ISO 8601 format)

order

Field	Type	Nullable	Description
id	string	No	Order identifier (UUID)
product_name	string	No	Primary product name, cached at purchase time
status	string	Yes	Order status: created, awaiting_payment, processing, completed, canceled, or refunded. Null for legacy orders without a status.

customer

Resolved from the order's account. When the account no longer exists, id is null and the email/name fall back to the bill-to details.

Field	Type	Nullable	Description
id	string	Yes	Customer identifier (UUID). Null when there is no linked account.
email	string	Yes	Customer email
name	string	Yes	Customer full name

corrections[]

Correction documents that point back at this invoice. Empty array when there are none.

Field	Type	Nullable	Description
id	string	No	Correction identifier (UUID)
number	string	Yes	Correction number
issued_at	string	Yes	When the correction was issued (ISO 8601 format)
corrected_amount	integer	Yes	The corrected gross amount in minor units

Error Responses

Bad Request (400)

{
  "message": "Invalid invoice ID"
}

Invoice Not Found (404)

{
  "message": "Invoice with ID <UUID> not found"
}

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