Send invoices

Submit invoices to tax authority system for clearance and authorization.

The tax authority operates a clearance model where each invoice must be approved before it becomes legally valid. You submit invoices to the tax authority through the Sovos platform, which transforms your data into the needed format, handles authentication, and manages the clearance workflow.

After the tax authority validates and authorizes your invoice, you obtain a tax authority reference number that must appear on the invoice delivered to your buyer.

Prerequisites

Before submitting invoices, make sure you have credentials and Sovos API credentials. For credential setup details, see Set up your credentials for Poland.
Your system must generate invoices in ExtendedCanonicalInvoice format:
- Standard Business Document (SBD) wrapper with routing metadata.
- Sovos Canonical Invoice (SCI) in Universal Business Language (UBL) 2.1 format..
- Country-specific extensions in the Legal Extension section.

Note:

Sovos transforms your ExtendedCanonicalInvoice to the format that KSeF requires. You don't need to create the native format directly.

How invoice submission works

The tax authority uses a clearance model where each invoice must be validated and authorized before it becomes legally valid. Understanding the submission workflow helps you implement proper error handling and manage buyer expectations.

Clearance model overview

Three-stage process:

Submit: Your system sends the invoice to Sovos. Sovos transforms it to the required format and sends it to the tax authority.
Validate: The tax authority validates the invoice structure, tax calculations, and business rules.
Authorize: The tax authority issues a reference number confirming the invoice is legally valid.

The KSeF reference number must appear on the invoice delivered to your buyer. Without tax authority authorization, the invoice has no legal effect for tax purposes.

What happens behind the scenes

When you submit a document, Sovos transforms and validates your SCI payload, then handles authentication and transmission to KSeF based on the operation mode you configured. For online submissions, KSeF returns either a KSeF reference number or a rejection; for offline mode, Sovos generates the QR codes immediately without contacting KSeF.

Online vs offline mode determination

The tax authority system supports two fundamental approaches to invoice issuance: online mode and offline mode. The system determines which mode applies based on date matching, not just the parameters you send. While online mode is the standard method where invoices are submitted to the tax authority in real-time, offline mode means the invoice is created outside the tax authority system with submission within specified deadlines.

For more details on online and offline modes, see Offline mode and retry behavior.

Synchronous vs asynchronous processing

Most invoice submissions complete within 1-2 minutes under normal conditions. The tax authority processes the invoice and returns the KSeF reference number in near real-time.

Synchronous processing (typical scenario):

Submit invoice → Immediate validation → Authorization within seconds to minutes.
Poll every 15 seconds for the first 90 seconds.
Most clearances complete in this window.

Asynchronous processing (extended scenarios):

The tax authority takes longer to process due to high load or complexity.
Continue polling with increasing intervals (30s, 1min, 2min, 5min...).
Extended processing may occur during:
- Peak periods (end of month, year-end)
- Tax authority maintenance windows
- High system load

Transaction states during processing:

Received (immediate): Sovos acknowledges receipt.
Transmitted (within seconds): Submitted to tax authority.
Processing (variable duration): Tax authority validating invoice.
Authorized (final success): Tax authority reference number issued.
Rejected (final failure): Fix errors and resubmit.

Submit an invoice

Send invoice data to the tax authority for validation and clearance.

Standard online submission

For real-time invoice processing, submit invoices with the invoice date matching the current submission date.

API Request

Headers:
- Authorization: Bearer token from OAuth authentication.
- Content-Type: application/xml.
- x-correlationId: optional header.
Request body: Standard Business Document (SBD) containing your Sovos Canonical Invoice (SCI) in base64 format.
Invoice date requirement for online mode: The invoice date (P_1 field in the tax authority schema) must match the current date. If the invoice date is earlier than the submission date, the tax authority automatically classifies the invoice as Offline24.

curl --location --request POST https://api-test.sovos.com/v1/documents
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {accessToken}' \
--header 'x-correlationId: {uniqueValue}' \
--data-raw '{
    "data": "PD9...d4=",
    "dataEncoding": "base64"
}'

Expected response

Immediate acknowledgment (HTTP 202):

{
  "status": 202,
  "message": "Accepted",
  "success": true,
  "data": {
    "completed": false,
  
    "detailsDto": {
      "status": "Transmitted",
      "isFinalDocumentStatus": false,
      "messages": [
        {
          "code": "104",
          "message": "Transmitted to the tax authority"
        }
      ],
      "keys": [
        {
          "key": "sessionReferenceNumber",
          "value": "20251218-SE-ABC123DEF456-01"
        },
        {
          "key": "invoiceReferenceNumber",
          "value": "20251218-INV-123456-01"
        }
      ]
    }
  }
}

Note:

Review payload samples to send invoices.

Offline mode submission

Use offline mode when you need to deliver invoices to buyers before receiving tax authority clearance, during connectivity problems, or when the tax authority system is unavailable.

Automatic retry only works for offline flow. When the tax authority is unavailable:

Offline flow (Transmission.OperationType=Offline): If KSeF is unavailable, Sovos automatically retries offline-mode submissions for up to seven days..
Online flow (no offline scope): Fails immediately with no automatic retry.

If you submit invoices in online mode and the tax authority experiences an outage, your submission will fail permanently. You'll need to detect the failure, implement your own retry logic, and resubmit manually.

Enable offline processing

Add the Transmission.OperationType scope to your SBD to enable offline mode and automatic retry:

<sbd:BusinessScope>
  <sbd:Scope>
    <sbd:Type>Transmission.OperationType</sbd:Type>
    <sbd:InstanceIdentifier>Offline</sbd:InstanceIdentifier>
  </sbd:Scope>
</sbd:BusinessScope>

Offline mode response

When offline processing completes, the response returns HTTP 202 with two QR code links:

{
    "timestamp": 1605282724079,
    "status": 202,
    "success": true,
    "message": "Document Received",
    "data": {
        "documentId": "3add2b7104dc0049ff0bf410f57e0a19afaf"
    }
}

For complete details on offline mode, see Offline mode and retry behavior.

Offline mode and retry behavior

Poland's Krajowy System e-Faktur (KSeF) system supports both online and offline invoice issuance, with automatic retry handling for system unavailability.

If you use offline mode, a Type 2 (Offline) certificate is also needed. This certificate generates the cryptographic signature embedded in the CERTYFIKAT QR code that accompanies offline invoices delivered to buyers before KSeF submission. For certificate configuration steps, see Set up credentials.

Understanding online and offline modes

KSeF 2.0 includes two fundamental approaches to invoice issuance:

Online mode is the standard method where invoices are submitted to KSeF in real-time. For an invoice to be considered issued in online mode, the date in field P_1 (invoice date) of the FA(3) schema must match the date of submission to KSeF.
Offline mode means the invoice is created outside KSeF with submission to the system within specified deadlines. If the P_1 date is earlier than the submission date, KSeF automatically treats the invoice as Offline24.

If KSeF is unavailable, Sovos automatically retries offline-mode submissions for up to seven days. Online-mode submissions do not retry automatically and require you to resubmit.

Important:

KSeF determines the mode based on date matching. If your invoice date (P_1 field) does not match the submission date, KSeF flags it as offline automatically, regardless of how you submitted it.

Offline mode types

The Offline category includes four separate procedures, each with different triggers, deadlines, and requirements.

Offline24: Voluntary, no restrictions on use. Designed primarily to address internet connectivity problems but can be used at any time. Deadline: Submit to KSeF by the next business day after issuance.
Offline (System Unavailability): For planned maintenance announced by the Ministry of Finance. Deadline: Submit to KSeF within one business day after unavailability ends.
Failure Mode: For announced KSeF failures. Deadline: Submit to KSeF within seven business days after failure ends.
Total Failure: Extraordinary circumstances announced through mass media (TV, radio, press). Invoices issued in paper or electronic form. No obligation to submit to KSeF afterward.

From a technical perspective, the first three modes use the same offline processing mechanism. The difference lies in the legal context and submission deadline. All three need two QR codes when delivering invoices to buyers before KSeF submission.

Sovos monitors KSeF system status and will support you through any of these scenarios should they occur.

Invoice delivery requirements

Delivery requirements differ by offline mode type and buyer characteristics.


Offline mode	Domestic buyer with Polish NIP	Foreign entities, consumers, domestic without NIP
Offline24	Must receive through KSeF	Parties agree on format (can be outside KSeF)
System unavailability	Must receive through KSeF	Parties agree on format (can be outside KSeF)
Failure mode	Parties agree (inside or outside KSeF)	Parties agree (inside or outside KSeF)
Total failure	Paper or electronic outside KSeF	Paper or electronic outside KSeF

Domestic taxpayers with a Polish Numer Identyfikacji Podatkowej (NIP) must receive their invoices through KSeF for Offline24 and System Unavailability modes. In Failure Mode, parties can agree on delivery method regardless of buyer type.

KSeF rate limiting

Poland's Krajowa Administracja Skarbowa (KAS) tax authority system has more restrictive rate limits than typical e-invoicing systems.

These limits vary by API endpoint:

Document submission endpoint: 180 documents per hour
Token authentication endpoint: 120 authentications per hour. Each document submission uses token authentication, effectively limiting throughput to 120 documents per hour.

The following options are available to address rate limit constraints.


Option	Short description	Best for
Batch transmission	Submit invoices with batch scope; Sovos groups them for batch transmission to KSeF	High volumes (>120/hour) needing a scalable long-term solution
Customer-side metering	Implement rate limiting in your system to control submission pace	Volumes under 2,880 documents/day
Offline mode	Generate and deliver PDFs immediately while KSeF validation continues in the background	Time-critical invoice delivery to customers
Request TA Limit Increase	Submit formal request to KSeF to increase your organization's rate limits	Very high volumes with documented business justification

Batch transmission

Best for sustained high volumes. Sovos groups your documents and sends them to KSeF in batches of up to 200 invoices, reducing API calls and bypassing rate limit constraints.

How it works

Add the batch processing scope to the SCI for each invoice you want sent in batch.
Submit invoices individually to Sovos as normal (one API call per invoice).
Sovos automatically groups batch-scoped documents for batch transmission to KSeF.
Each document gets its own individual response from KSeF.

Enabling batch processing

Add this scope to your SBD's BusinessScope element:

<sbd:BusinessScope>
  <!-- Your existing scopes remain unchanged -->
  <sbd:Scope>
    <sbd:Type>DOCUMENTIDENTIFICATION</sbd:Type>
    <sbd:InstanceIdentifier>[YOUR_INVOICE_NUMBER]</sbd:InstanceIdentifier>
  </sbd:Scope>
  
  <!-- ADD THIS SCOPE FOR BATCH PROCESSING -->
 <sbd:Scope>
 	<sbd:Type>Transmission.OptionalInputValue</sbd:Type>
 	<sbd:InstanceIdentifier/>
	<sbd:Identifier>Batch</sbd:Identifier>
 </sbd:Scope>

Important:

The batch scope must be included on every invoice you want sent in batch. Invoices without the batch scope will be sent individually.

Batch transmission behavior

Sovos groups batch-scoped documents based on timing and volume thresholds:

200 documents with batch scope are queued, OR
5 minutes have elapsed since the first batch-scoped document was received

For response handling, each document gets its own individual response from KSeF. Poll for document status using standard endpoints. Batch-scoped documents may take up to 5 minutes longer to get responses as Sovos waits to group documents before transmission.

Customer-side metering

Alternative for moderate volumes with concentrated peaks. Use when your daily volume stays under 2,880 documents but you experience submission spikes during business hours, implement metering to spread submissions evenly across the day.

How it works

Implement a queuing or throttling mechanism in your integration that:

Limits invoice submissions to 120 documents per hour or fewer.
Spreads submissions evenly across your business day.
Monitors for rate limit errors and backs off when encountered.

KSeF recommended limits


Measure	req/s	req/m	req/h	group
Request number limits	10	30	120	onlineSession

Recommended approach

Queue invoices and process at a steady rate (For example, 2 per minute = 120 per hour)
Implement retry logic with appropriate delays for any rate limit errors
Spread high-volume processing across 24-hour periods

Offline mode

For time-sensitive flows or when rate limits are hit. Offline mode is an independent transmission option (not combinable with batch or metering) that allows immediate invoice issuance and delivery while KSeF processing happens separately within a 24-hour window.

Use this when specific invoices need immediate delivery without waiting for batch grouping or metering delays, or when you've hit rate limits and need to continue issuing invoices.

Use this option when:

Specific invoices need immediate delivery (cannot wait for batch grouping or metering)
You've hit rate limits and need to continue issuing invoices while adjusting your approach
Time-critical B2C or urgent B2B scenarios requiring instant delivery
You have Type 2 certificates configured (needed for offline mode)

How it works

Set OperationType to offline in your Standard Business Document (SBD) when submitting invoices.
Sovos generates both needed QR codes immediately without attempting KSeF transmission.
Deliver the PDF invoice to your buyer with both QR codes.
Submit the invoice to KSeF within 24 hours.

For full details, go to Offline mode and retry behavior.

Important:

Offline24 mode is legally permitted for voluntary use under Polish regulations. Submit invoices to KSeF by the next business day after issuance.

Requesting higher limits

For extreme volume cases.When your volume exceeds what batch transmission can handle, submit a formal request to the Polish tax authority (KSeF) to increase your organization's rate limits.

Submit your request through the official KSeF contact form at: https://ksef.podatki.gov.pl/formularz/. Include a detailed description of your intended use to support your request.

Important:

Processing time is uncertain (responses can take 2-3 weeks, but timing may vary)
No guarantee of approval
Limits are per tax ID (NIP)

Monitor submission status

Track invoice processing and retrieve authorization results from the tax authority.

After submitting an invoice, you can use notifications to keep you informed as your document moves through its lifecycle. Notifications offer status updates, attachments, and other legal information, and alert you to status changes. When an event occurs on a document, like transmission or approval, Indirect Tax API creates a Notification object. Learn more about the Notification endpoints and how to Check notifications.

Error handling and retry logic

Learn how to handle errors and the automatic retry behavior for invoice submissions.

When you submit documents through the Sovos API, you may receive error responses.

Understand:

How can we help?

Send invoices

Prerequisites

How invoice submission works

Submit an invoice

Standard online submission

Offline mode submission

Offline mode and retry behavior

Understanding online and offline modes

Offline mode types

Invoice delivery requirements

KSeF rate limiting

Batch transmission

Customer-side metering

Offline mode

Requesting higher limits

Monitor submission status

Error handling and retry logic

sovos-footer