Create a document
Every invoice sent to Sovos must be wrapped in a Standard Business Document that contains routing metadata and the Sovos Canonical Invoice (SCI) in UBL 2.1 format.
This section covers how to construct the full document, from the SBD wrapper through the invoice body and any Poland-specific extensions.
Poland technical requirements
Poland has specific technical requirements for tax ID format, VAT rates, date formats, and QR codes.
Tax ID format
-
Length: 10 digits
-
Format: XXXXXXXXXX (no separators, hyphens, or spaces)
VAT rates and calculations
- Standard rates
-
-
23% - Standard rate for most goods and services
-
8% - First reduced rate (food, passenger transport, hotels, restaurants)
-
5% - Second reduced rate (basic food items, books, newspapers)
-
0% - Zero rate (exports, intra-community supply, international transport)
-
- Exempt categories
-
-
ZW (VAT exempt) - Financial services, insurance, education, medical
-
NP (Not subject) - Activities outside Polish VAT scope
-
- Tax calculation
-
Tax Amount = Base Amount x Rate Gross Amount = Base Amount + Tax AmountRounding: Round all amounts to two decimal places using standard rounding (half up).
Exchange rates: Four decimal places (for example, 4.3214)
Important:Always use decimal arithmetic, not floating point, to avoid rounding errors in tax calculations.
Amount precision
-
Currency amounts: Two decimal places. For example, 1234.56.
-
Quantities: Up to four decimal places. For example, 10.2500.
-
Unit prices: 2-4 decimal places depending on precision needs.
-
Tax percentages: Two decimal places. For example: 23.00.
-
Exchange rates: Four decimal places. For example: 4.3214.
Always use decimal arithmetic, not floating point, to avoid rounding errors in tax calculations.
Date and time format
Date format: YYYY-MM-DD (ISO 8601)
-
Example: 2025-12-18
DateTime format: YYYY-MM-DDTHH:MM:SS (with optional timezone)
-
Example: 2025-12-18T14:32:45Z
-
Example with timezone: 2025-12-18T14:32:45+01:00
Time zone: Poland uses CET (Central European Time) / CEST (Central European Summer Time)
-
CET: UTC+01:00 (winter)
-
CEST: UTC+02:00 (summer)
Issue date rules:
-
Cannot be future-dated
-
Typically not more than 30 days in the past
-
Submit invoices promptly for best operational efficiency
Document numbering
KSeF does not require a specific format; you maintain your own numbering.
Here are some best practices to number and organize your documents:
-
Must be unique within your NIP scope
-
Sequential numbering with no gaps (recommended practice)
-
Cannot reuse numbers from voided or failed submissions
-
Maintain separate sequences for different document types if needed
Common patterns:
-
Series-based:
FV/2025/12/001(type/year/month/sequence) -
Sequential:
INV-001,INV-002,INV-003. -
Prefix-based:
FAKTURA-2025-001
QR codes
QR codes are only needed when invoices are delivered outside the KSeF system.
Poland's KSeF mandate includes specific QR code requirements based on how invoices are delivered to recipients and whether delivery occurs before or after KSeF clearance.
| Scenario | Recipients | Transmission | QR codes |
|---|---|---|---|
| Delivered through KSeF | Domestic B2B (standard online mode). | Buyer retrieves from the KSeF portal or through API | None or one when offering a courtesy file such as PDF outside KSeF |
| Delivered outside KSeF after clearance | Foreign buyers, B2C customers, and domestic buyers without a Polish tax identification number (NIP). | Transmission outside KSeF (for example, through email or PDF) | One for the KSeF number |
| Delivered outside KSeF before clearance | Foreign buyers, B2C customers, and domestic buyers without a Polish TIN. All recipients (including domestic) if issued during a KSeF failure. | Transmission outside KSeF (for example, through email or PDF) | One for the KSeF number and one for the issuer certificate |
Unit of measure codes
Poland uses UN/CEFACT codes (Recommendation 20).
| Code | Description | Usage |
|---|---|---|
| PCE | Piece | Individual items |
| KGM | Kilogram | Weight in kg |
| MTR | Meter | Length in meters |
| LTR | Liter | Volume in liters |
| HUR | Hour | Time in hours |
| DAY | Day | Time in days |
| MTK | Square meter | Area in square meters |
| MTQ | Cubic meter | Volume in cubic meters |
The following example shows how to use these codes:
<cbc:InvoicedQuantity unitCode="PCE">10</cbc:InvoicedQuantity>
<cbc:InvoicedQuantity unitCode="KGM">25.50</cbc:InvoicedQuantity>
Standard Business Document (SBD) structure
SBD structure
The SBD contains the following components.
-
The Standard Business Document Header (SBDH) includes routing metadata, such as the sender, receiver, and product ID. For more information, see About the Standard Business Document.
-
The Sovos document contains the Sovos Canonical Invoice (SCI) in UBL 2.1 format. For more information, see About Sovos Canonical Invoice.
Sovos transforms your SCI to Krajowy System e-Faktur (KSeF) FA(3) format and handles submission and clearance.
<sbd:StandardBusinessDocument>
<sbd:StandardBusinessDocumentHeader>
<!-- Sender, receiver, routing information -->
</sbd:StandardBusinessDocumentHeader>
<svs:SovosDocument>
<sci:SovosCanonicalInvoice>
<inv:Invoice>
<!-- UBL 2.1 invoice content -->
<ext:UBLExtensions>
<sov:SovosExtension>
<!-- Poland-specific fields -->
</sov:SovosExtension>
</ext:UBLExtensions>
</inv:Invoice>
</sci:SovosCanonicalInvoice>
</svs:SovosDocument>
</sbd:StandardBusinessDocument>
Configure the SBDH
- Sender
-
<sbd:Sender> <sbd:Identifier Authority="PL">[YOUR_NIP]</sbd:Identifier> <sbd:ContactInformation> <sbd:Contact>[Contact Name]</sbd:Contact> <sbd:EmailAddress>[Email]</sbd:EmailAddress> <sbd:TelephoneNumber>[Phone]</sbd:TelephoneNumber> </sbd:ContactInformation> </sbd:Sender> - Receiver
-
<sbd:Receiver> <sbd:Identifier Authority="PL">[BUYER_NIP]</sbd:Identifier> </sbd:Receiver>Note:For simplified invoices where buyer may not have Numer Identyfikacji Podatkowej (NIP), leave the field empty:
<sbd:Identifier Authority="PL"></sbd:Identifier> - Document identification
-
<sbd:DocumentIdentification> <sbd:Standard>Sovos</sbd:Standard> <sbd:TypeVersion>2.0</sbd:TypeVersion> <sbd:InstanceIdentifier>[YOUR_INVOICE_NUMBER]</sbd:InstanceIdentifier> <sbd:Type>Invoice</sbd:Type> <sbd:MultipleType>false</sbd:MultipleType> <sbd:CreationDateAndTime>[ISO8601_TIMESTAMP]</sbd:CreationDateAndTime> </sbd:DocumentIdentification> - Business scope
-
<sbd:BusinessScope> <sbd:Scope> <sbd:Type>Country</sbd:Type> <sbd:InstanceIdentifier>pl_Faktura__2.0</sbd:InstanceIdentifier> <sbd:Identifier>PL</sbd:Identifier> </sbd:Scope> </sbd:BusinessScope>
Build the invoice body
- Invoice header
-
The invoice header includes document-level identity fields that KSeF requests.
xml <inv:Invoice> <ext:UBLExtensions> <sov:SovosExtension> <!-- Poland-specific fields --> </sov:SovosExtension> </ext:UBLExtensions> <cbc:ID>FV/2025/12/001</cbc:ID> <cbc:IssueDate>2025-12-18</cbc:IssueDate> <cbc:InvoiceTypeCode>380</cbc:InvoiceTypeCode> <cbc:DocumentCurrencyCode>PLN</cbc:DocumentCurrencyCode> </inv:Invoice>Element Cardinality Description ID 1..1 Your invoice number. Must be unique within your NIP scope and sequential with no gaps. Do not reuse numbers from failed submissions. IssueDate 1..1 Invoice date in YYYY-MM-DDformat. Cannot be a future date.InvoiceTypeCode 1..1 Document type code. Use 380for invoices,381for credit notes,386for advance invoices.DocumentCurrencyCode 1..1 ISO 4217 currency code. For example: PLN,EUR,USD.Note:If your invoice is in a non-PLN currency, also include
<cbc:TaxCurrencyCode>PLN</cbc:TaxCurrencyCode>and a<cac:PaymentExchangeRate>block with the NBP exchange rate. - Seller block
-
xml <cac:AccountingSupplierParty> <cac:Party> <cac:PartyIdentification> <cbc:ID schemeID="TaxID">5252525252</cbc:ID> </cac:PartyIdentification> <cac:PostalAddress> <cac:AddressLine> <cbc:Line>ul. Warszawska 10, 00-001 Warszawa</cbc:Line> </cac:AddressLine> <cac:Country> <cbc:IdentificationCode>PL</cbc:IdentificationCode> </cac:Country> </cac:PostalAddress> <cac:PartyLegalEntity> <cbc:RegistrationName>ABC Sp. z o.o.</cbc:RegistrationName> </cac:PartyLegalEntity> </cac:Party> </cac:AccountingSupplierParty>Element Cardinality Description PartyIdentification/ID 1..1 Supplier NIP. schemeIDmust beNIP. 10 digits, no separators. Must match the NIP in your authentication certificate.PostalAddress 1..1 Supplier fiscal address as registered with KSeF. PostalAddress/Country/IdentificationCode 1..1 ISO 3166-1 alpha-2 country code. For example: PL. - Buyer block
xml <cac:AccountingCustomerParty> <cac:Party> <cac:PartyIdentification> <cbc:ID schemeID="TaxID">7777777777</cbc:ID> </cac:PartyIdentification> <cac:PostalAddress> <cac:AddressLine> <cbc:Line>ul. Krakowska 20, 30-001 Krakow</cbc:Line> </cac:AddressLine> <cac:Country> <cbc:IdentificationCode>PL</cbc:IdentificationCode> </cac:Country> </cac:PostalAddress> <cac:PartyLegalEntity> <cbc:RegistrationName>XYZ Sp. z o.o.</cbc:RegistrationName> </cac:PartyLegalEntity> </cac:Party> </cac:AccountingCustomerParty>Element Cardinality Description PartyIdentification/ID 0..1 Buyer NIP. Needed for domestic B2B invoices. For simplified invoices where the buyer has no NIP, leave the SBDH receiver identifier empty. - Tax total
<cac:TaxTotal> <cac:TaxSubtotal> <cbc:TaxableAmount>615.00</cbc:TaxableAmount> <cac:TaxCategory> <cac:TaxScheme> <cbc:Name>P_13_8</cbc:Name> </cac:TaxScheme> </cac:TaxCategory> </cac:TaxSubtotal> </cac:TaxTotal>- Monetary totals
<cac:LegalMonetaryTotal> <cbc:PayableAmount>615.00</cbc:PayableAmount> </cac:LegalMonetaryTotal>Element Cardinality Description PayableAmount 1..1 Amount due for payment. Note:All amounts must be rounded to two decimal places. For credit notes, amounts are negative.
- Attachments (Zalacznik)
-
KSeF 2 introduces the concept of attachments (Zalacznik). Attachments allow taxpayers to send structured data blocks inside the e-invoice XML. These are machine-readable, XML-based attachments (not files like PDFs or images).
To use it, you must notify and get approval from the Ministry of Finance. They're meant for regulated, specialized business cases, including:-
Utility usage details
-
Telecom service breakdowns
-
Energy consumption data
-
Similar analytical tables
After it is authorized, you can send attachments through a dedicated node in the invoice XML:<Zalaczniki> <Zalacznik> <KodZalacznika>ENERGIA</KodZalacznika> <DaneZalacznika> <!-- Structured data (e.g., XML or text) --> </DaneZalacznika> </Zalacznik> </Zalaczniki>Important:The entire invoice file (XML + attachments) must not exceed 3 MB.
-
Poland-specific extensions
Implement Poland-specific fields using the Sovos Canonical Invoice (SCI) extensions structure.
Standard UBL 2.1 does not cover all fields the FA(3) schema requires. To cover this, Sovos supports these fields through the extensions structure and maps them to FA(3) XML automatically before sending to KSeF. This way, extensions let you include FA(3) fields that don't exist in standard UBL 2.1, such as invoice annotation flags, payment details, custom key-value fields, and third-party entities.
If you need to build custom extension fields, see the Sovos Implementers Portal.
Common extension scenarios
This topic presents solutions for common extension errors, identification problems, and incorrect formats, to guarantee compliance with schema validation requirements.
Invoice annotations
Customer question: "How do I indicate split payment, self-billing, or reverse charge on my invoice?"
Solution: Use the Adnotacje group nested under Fa to set the invoice flags that Polish tax law requires.
<leg:HeaderFields>
<leg:GroupInformation>
<leg:Id>Fa</leg:Id>
<leg:GroupInformation>
<leg:Id>Adnotacje</leg:Id>
<leg:Field name="P_16">2</leg:Field> <!-- Cash method: 2=no -->
<leg:Field name="P_17">2</leg:Field> <!-- Self-billing: 2=no -->
<leg:Field name="P_18">2</leg:Field> <!-- Reverse charge: 2=no -->
<leg:Field name="P_18A">2</leg:Field> <!-- Split payment: 2=no -->
<leg:Field name="P_22N">1</leg:Field> <!-- No new transport: 1 -->
<leg:Field name="P_23">2</leg:Field> <!-- Intra-EU: 2=no -->
<leg:Field name="P_PMarzyN">1</leg:Field> <!-- No margin: 1 -->
</leg:GroupInformation>
</leg:GroupInformation>
</leg:HeaderFields>Common field combinations:
| Scenario | Fields |
|---|---|
| Standard domestic B2B | P_16=2, P_17=2, P_18=2, P_18A=2, P_22N=1, P_23=2, P_PMarzyN=1 |
| Self-billing invoice | P_17=1 (all others as appropriate) |
| Reverse charge invoice | P_18=1 (all others as appropriate) |
| Split payment mechanism | P_18A=1 (all others as appropriate) |
| Cash accounting method | P_16=1 (all others as appropriate) |
Payment terms
Customer question: "How do I specify the payment date and payment method?"
Platnosc group nested under Fa. For partial payments or specific payment methods, add the nested ZaplataCzesciowa group.- Simple payment date
-
<leg:HeaderFields> <leg:GroupInformation> <leg:Id>Fa</leg:Id> <leg:GroupInformation> <leg:Id>Platnosc</leg:Id> <leg:Field>LinkDoPlatnosci</leg:Field> </leg:GroupInformation> </leg:GroupInformation> </leg:HeaderFields> - Payment with method and link
-
<leg:HeaderFields> <leg:GroupInformation> <leg:Id>Fa</leg:Id> <leg:GroupInformation> <leg:Id>Platnosc</leg:Id> <leg:Field>LinkDoPlatnosci</leg:Field> <leg:GroupInformation> <leg:Id>ZaplataCzesciowa</leg:Id> <leg:Field name="FormaPlatnosci">6</leg:Field> <leg:Field name="OpisPlatnosci">Przelew bankowy</leg:Field> </leg:GroupInformation> </leg:GroupInformation> </leg:GroupInformation> </leg:HeaderFields> - Payment method codes (FormaPlatnosci)
-
Code Description 1 Cash 2 Card 3 Voucher 4 Check 5 Credit 6 Bank transfer 7 Mobile payment 8 Other
Use ZaplataCzesciowa when the invoice has multiple payment installments, different payment methods for different portions, or requests a payment description or electronic payment link.
Custom key-value fields
Customer question: "How do I add custom fields like PO number, project code, or delivery instructions?"
Solution: Use repeatable DodatkowyOpis groups nested under Fa to add custom fields such as purchase order numbers or project codes.
<leg:HeaderFields>
<leg:GroupInformation>
<leg:Id>Fa</leg:Id>
<leg:GroupInformation>
<leg:Id>DodatkowyOpis</leg:Id>
<leg:Field name="Klucz">po_number</leg:Field>
<leg:Field name="Wartosc">PO-2025-001234</leg:Field>
</leg:GroupInformation>
<leg:GroupInformation>
<leg:Id>DodatkowyOpis</leg:Id>
<leg:Field name="Klucz">project_code</leg:Field>
<leg:Field name="Wartosc">PROJ-ABC-123</leg:Field>
</leg:GroupInformation>
<leg:GroupInformation>
<leg:Id>DodatkowyOpis</leg:Id>
<leg:Field name="Klucz">delivery_instructions</leg:Field>
<leg:Field name="Wartosc">Call before delivery</leg:Field>
</leg:GroupInformation>
</leg:GroupInformation>
</leg:HeaderFields>
Field constraints:
-
Klucz: Maximum 100 characters. -
Wartosc: Maximum 240 characters.
Use cases include: Purchase order references, internal tracking codes, project identifiers, customer-specific metadata, delivery or handling instructions.
Footer and registry information
Customer question: "How do I include company registration numbers in the invoice footer?"
Stopka at root level, not nested under Fa, to include company registration details.- Footer text
-
<leg:HeaderFields> <leg:GroupInformation> <leg:Id>Stopka</leg:Id> <leg:GroupInformation> <leg:Id>Informacje</leg:Id> <leg:Field name="StopkaFaktury">Kapital zakladowy: 15 000 000 PLN</leg:Field> </leg:GroupInformation> </leg:GroupInformation> </leg:HeaderFields> - Registry numbers
-
<leg:HeaderFields> <leg:GroupInformation> <leg:Id>Stopka</leg:Id> <leg:GroupInformation> <leg:Id>Rejestry</leg:Id> <leg:Field name="KRS">0000099999</leg:Field> <leg:Field name="REGON">999999999</leg:Field> <leg:Field name="BDO">000099999</leg:Field> </leg:GroupInformation> </leg:GroupInformation> </leg:HeaderFields>
Common usage: Share capital information, company registration details, regulatory compliance statements, industry-specific identifiers.
Podmiot3 configuration
Podmiot3 represents third-party entities involved in a transaction other than the seller (Podmiot1) and buyer (Podmiot2).
By using this mechanism, you can declare third-party entities involved in a transaction beyond the seller and buyer, such as factors, agents, payees, or invoice issuers. You must provide the third-party data using standard UBL PartyIdentification structure in your SCI; Sovos handles the transformation to the FA(3) Podmiot3 element automatically before submission to KSeF.
When to use Podmiot3
For custom roles, use schemeID="OtherRole" with value "1" and include cbc:Name with role description.
<cac:PartyTaxScheme>
<cac:TaxScheme>
<cbc:ID schemeID="OtherRole">1</cbc:ID>
<cbc:Name>Przedstawiciel handlowy</cbc:Name>
</cac:TaxScheme>
</cac:PartyTaxScheme>
Podmiot3 structure
Podmiot3 uses standard UBL PartyIdentification structure, not LegalExtension GroupInformation.
-
Place it in
cac:PayeePartyor the applicable UBL party element depending on the role. -
Sovos transforms it to FA(3)
Podmiot3automatically. -
Do not use
leg:GroupInformationfor Podmiot3.
Identification options
Key requirements:
-
TaxID: 10 digits, no separators, valid checksum. -
EU_TaxID/ForeignerTaxID: Country code in PostalAddress, not in ID number.
Clearance data
After KSeF authorizes an invoice, Sovos returns the clearance data in the final status response. You must store the KSeF reference number and use it when delivering the invoice.
Sovos returns the authorized response (HTTP 200, status: Authorized) contains the following values:
| Key | Description | Neeeded action |
|---|---|---|
| ksefReferenceNumber | KSeF reference number. Format: {NIP}-{date}-{hash1}-{hash2}. Example: 1234567890-20251218-ABCD1234-EF. | Include on the invoice PDF delivered to the buyer. Store as proof of clearance. |
| invoiceVerificationUrl | Link for the KSeF invoice verification QR code. | Generate the QR code image from this link and include it on the invoice. |
| acquisitionTimestamp | Exact authorization time from KSeF. | Store for compliance record-keeping. |
The response also includes an AuthorizationProtocol attachment. This is the UPO (Urzędowe Poświadczenie Odbioru, the official KSeF receipt), encoded in Base64 XML. Store it for at least 10 years as legal proof of submission.
For QR code generation and delivery requirements, see PDF generation.
