Submission Status

Checking the shipping status

GET /invoices/{environment}/status/{referenceNumber}

Checks the submission status of a session (online or batch) by reference number. Returns full session details including invoice counts and per-invoice status. Requires an active KSeF session.

Status checking path parameters

Parameter	Type	Required	Description
environment	string	✅	test, demo or prod
referenceNumber	string	✅	KSeF session/batch reference number

Status checking response 200

{
  "referenceNumber": "20260101-AU-XXXXXXXX-XXXX-XX",
  "status": {
    "code": 200,
    "description": "Batch session processed successfully"
  },
  "dateCreated": "2026-01-15 12:00:00",
  "dateUpdated": "2026-01-15 12:05:00",
  "totalInvoiceCount": 3,
  "successfulInvoiceCount": 3,
  "failedInvoiceCount": 0,
  "invoices": [
    {
      "ordinalNumber": 1,
      "invoiceNumber": "FV/2026/01/001",
      "ksefNumber": "1234567890-20260101-ABCDEF-12",
      "acquisitionDate": "2026-01-15 12:01:00",
      "status": { "code": 200, "description": "OK" }
    }
  ]
}

Field	Type	Description
referenceNumber	string	KSeF reference number
status	object	Session processing status (code + description)
dateCreated	string	Session creation date
dateUpdated	string	Session last update date
totalInvoiceCount	integer	Total number of invoices in the session
successfulInvoiceCount	integer	Number of successfully processed invoices
failedInvoiceCount	integer	Number of failed invoices
invoices	array	List of invoices with their individual status

Invoice object

Field	Type	Description
ordinalNumber	integer	Invoice position in the session
invoiceNumber	string	Invoice number (e.g. FV/2026/01/001)
ksefNumber	string	KSeF invoice number
acquisitionDate	string	Date when KSeF accepted the invoice
status	object	Per-invoice status (code + description)

Session Reference Sync

When the status is checked, ksef-proxy automatically updates session_reference_number in:

• synced_invoices — for online invoices matched by ksef_number
• offline_invoices — for batch invoices matched by ksef_reference_number

This ensures that invoices sent before session tracking was implemented can be retroactively linked to their session.

Status checking error Codes

Code	Description
401	Unauthorized
404	No active KSeF session
409	KSeF outage or simulation active — error message includes details
502	KSeF error — enriched with outage context if applicable

Download UPO

GET /invoices/{environment}/status/{referenceNumber}/{ksefNumber}/upo

Downloads the UPO (Official Receipt Confirmation) for an invoice from KSeF. Requires the session reference number in which the invoice was sent and an active KSeF session.

Why is referenceNumber required?

The KSeF v2 API requires the session reference number to retrieve UPO: /v2/sessions/{referenceNumber}/invoices/ksef/{ksefNumber}/upo

The referenceNumber is the session ID returned when the invoice was sent (from POST /invoices/{environment}/send or GET /invoices/{environment}/status/{referenceNumber}).

Download UPO path parameters

Parameter	Type	Required	Description
environment	string	✅	test, demo or prod
referenceNumber	string	✅	KSeF session reference number (from send response)
ksefNumber	string	✅	KSeF invoice number

Download UPO Query Parameters

Parameter	Type	Default	Description
docType	string	xml	xml (UPO XML) or pdf (UPO PDF)

Response 200 — XML

{
  "ksefNumber": "1234567890-20260101-ABCDEF-12",
  "referenceNumber": "20260101-AU-XXXXXXXX-XXXX-XX",
  "docType": "xml",
  "contentType": "application/xml",
  "content": "PD94bWwgdmVyc2lvbj0i...",
  "fileName": "1234567890-20260101-ABCDEF-12-upo.xml"
}

Response 200 — PDF

{
  "ksefNumber": "1234567890-20260101-ABCDEF-12",
  "referenceNumber": "20260101-AU-XXXXXXXX-XXXX-XX",
  "docType": "pdf",
  "contentType": "application/pdf",
  "content": "JVBERi0xLjQK...",
  "fileName": "1234567890-20260101-ABCDEF-12-upo.pdf"
}

Server-side PDF generation

When docType=pdf is requested, the REST API always returns a PDF document. If the KSeF API returns the UPO in XML format (which is the default KSeF behavior), the server automatically converts it to a formatted PDF using pdfmake, including header, document details, and structured layout. This means docType=pdf is always reliable regardless of the native format returned by KSeF.

Field	Type	Description
ksefNumber	string	KSeF invoice number
referenceNumber	string	Session reference number
docType	string	xml or pdf
contentType	string	application/xml or application/pdf
content	string	Base64-encoded UPO content
fileName	string	Suggested file name

Download UPO error Codes

Code	Description
400	Invalid docType parameter
401	Unauthorized
404	UPO not yet available or invoice not found
409	KSeF outage or simulation active
502	KSeF error