Invoice lifecycle and UPO

Invoice submission is asynchronous. A successful POST /v1/invoices can return status: processing; use GET /v1/invoices/{id} to observe stored lifecycle state.

Invoice statuses

received
The invoice has been accepted into the product lifecycle.
processing
The invoice is being processed or waiting for due-time processing.
accepted
The invoice was accepted. UPO may still be unavailable until a persisted artifact exists.
rejected
Non-retryable product or business rejection.
failed
Technical or retry-exhausted processing failure.

Polling

Use the invoice read endpoint to observe status after submission.

Do not submit the same invoice again with a new Idempotency-Key just to check whether it finished.

Retry state

retrying: true means a background retry is scheduled. next_retry_at gives the next retry time when exposed.

Only retrying and next_retry_at are exposed through the developer API.

KSeF numbers

Accepted sandbox invoices receive a synthetic KSEF-TEST-... number. It is simulated test data.

UPO availability

upo_available: true means a persisted UPO XML artifact exists and can be retrieved with GET /v1/invoices/{id}/upo.

upo_available: false means no persisted artifact is available through the public API yet.

UPO unavailable

The UPO endpoint returns upo_not_available when the invoice exists for the caller but no persisted UPO artifact can be downloaded.

For upo_not_available, retryable: true means the client may retry the read later because the artifact may still appear through normal backend lifecycle. It does not mean the GET request triggered backend retry.

Rejected and failed invoices can return the same error with retryable: false.