What Is UBL-TR 1.2.1 and Do Small Turkish Businesses Need to Care?

Last updated: June 2026

Every Turkish e-Arşiv and e-Fatura invoice is, under the surface, an XML file structured to the UBL-TR 1.2.1 standard. Most small business owners will never see this XML. It is generated, submitted, and archived automatically by the GİB portal or by integrated tools like AccountsOS. But understanding what UBL-TR is, why it exists, and what it contains answers a lot of practical questions about Turkish e-invoicing compliance.

What is UBL?

UBL stands for Universal Business Language, an international open standard for business documents, maintained by OASIS (Organization for the Advancement of Structured Information Standards). UBL defines XML schemas for common business documents: invoices, credit notes, purchase orders, despatch advices, and others.

The core idea: if every business uses the same XML structure for an invoice, machines can read and process any invoice without custom parsing. A Turkish business's invoice and a Dutch business's invoice (PEPPOL BIS 3.0, another UBL profile) are both based on the same underlying UBL standard, which is why cross-border e-invoicing networks can operate.

What is UBL-TR specifically?

UBL-TR is Turkey's national implementation profile of the UBL standard. "TR" denotes the Turkish customisation, and "1.2.1" is the current version mandated by GİB.

GİB developed UBL-TR to fit Turkey's specific tax law requirements: Turkish KDV structure, VKN and TCKN identifiers, the specific invoice numbering format, the GİB UUID field, and other Turkish-specific elements that do not exist in the generic UBL standard.

UBL-TR 1.2.1 was mandated by GİB as the required format from 2 February 2026. Previous versions (UBL-TR 1.2, UBL-TR 1.0) are no longer accepted for new invoices. If your invoicing software has not been updated to produce UBL-TR 1.2.1, it will fail GİB validation.

What does a UBL-TR 1.2.1 invoice file look like?

The file is an XML document. If you were to open one, you would see something like this (simplified illustration):

<?xml version="1.0" encoding="UTF-8"?>
<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2"
         xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2"
         xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2"
         xmlns:ext="urn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2">
  <ext:UBLExtensions>
    <!-- GİB-specific UUID and signature extension -->
  </ext:UBLExtensions>
  <cbc:UBLVersionID>2.1</cbc:UBLVersionID>
  <cbc:CustomizationID>TR1.2.1</cbc:CustomizationID>
  <cbc:ID>GIB2026000000001</cbc:ID>
  <cbc:IssueDate>2026-06-01</cbc:IssueDate>
  <cbc:IssueTime>14:30:00</cbc:IssueTime>
  <cbc:InvoiceTypeCode>SATIS</cbc:InvoiceTypeCode>
  <!-- Seller (AccountParty) -->
  <cac:AccountingSupplierParty>
    <cac:Party>
      <cbc:PartyName>ACME BİLİŞİM LİMİTED ŞİRKETİ</cbc:PartyName>
      <!-- VKN, address, contact details -->
    </cac:Party>
  </cac:AccountingSupplierParty>
  <!-- Buyer (AccountParty) -->
  <cac:AccountingCustomerParty>
    <!-- Buyer VKN or TCKN, name, address -->
  </cac:AccountingCustomerParty>
  <!-- Line items -->
  <cac:InvoiceLine>
    <cbc:InvoicedQuantity unitCode="C62">10</cbc:InvoicedQuantity>
    <cbc:LineExtensionAmount currencyID="TRY">5000.00</cbc:LineExtensionAmount>
    <cac:TaxTotal>
      <cbc:TaxAmount currencyID="TRY">1000.00</cbc:TaxAmount>
    </cac:TaxTotal>
    <cac:Item>
      <cbc:Name>Web Geliştirme Hizmeti</cbc:Name>
    </cac:Item>
    <cac:Price>
      <cbc:PriceAmount currencyID="TRY">500.00</cbc:PriceAmount>
    </cac:Price>
  </cac:InvoiceLine>
</Invoice>

This is a heavily simplified excerpt. A complete UBL-TR 1.2.1 invoice XML includes dozens of required and optional fields, namespace declarations, GİB extension blocks for the UUID and digital signature, and specific code lists for unit codes, currency codes, KDV exemption codes, and invoice type codes.

Key fields in a UBL-TR 1.2.1 invoice

While small businesses do not generate the XML directly, understanding what the standard captures helps when you are filling in invoice details:

The fields you interact with in the GİB portal or in AccountsOS map directly to these UBL-TR fields. When you type a customer's VKN, that value goes into AccountingCustomerParty. When you add a line item, it becomes an InvoiceLine element. You never see the XML tags, but everything you enter populates the standard.

The four invoice type codes

UBL-TR defines invoice type codes that determine what kind of transaction the invoice represents:

SATIS (Sale): The standard commercial invoice for a sale of goods or services. Most invoices are this type.

IADE (Return): A credit note or return invoice. Issued when goods are returned or a sale is reversed.

TEVKIFAT (Withholding): Used for KDV withholding transactions where the buyer is responsible for a portion of the KDV remittance.

İSTİSNA (Exemption): For transactions that are KDV-exempt under specific legal provisions.

AccountsOS sets the correct type code automatically based on the invoice scenario. The GİB portal prompts you to select the transaction type when creating an invoice.

What changed in UBL-TR 1.2.1 compared to earlier versions?

GİB mandated UBL-TR 1.2.1 from 2 February 2026. The key changes from UBL-TR 1.2 (the previous version) include:

Stricter UUID structure: The GİB UUID (Unique Universal ID assigned to each invoice) must conform to RFC 4122 Version 4 format (true random UUID). Earlier versions allowed looser UUID formats that occasionally caused downstream processing issues.

Updated code lists: The allowed values for unit codes (UN/ECE Recommendation 20), KDV exemption codes, and payment means codes were updated and tightened.

Extended address structure: The buyer and seller address fields now require more granular structured data (province code, district code) rather than free-text address lines.

Digital signature updates: The XML digital signature profile used in the GİB extension blocks was updated to align with current security standards.

For businesses using the GİB portal or AccountsOS, these changes were absorbed by the system update. You were not required to do anything manually. The change only required action from:

• Özel entegratörler (private integrators), who updated their XML generation engines
• Developers of custom invoicing or ERP integrations to GİB

Do small businesses need to understand UBL-TR?

The short answer: not in technical detail. The practical answer: enough to make smart choices about tooling.

Here is what the level of understanding you actually need looks like:

You need to know that UBL-TR exists so you can evaluate whether your invoicing software is compliant. A Word document invoice or a PDF generated from a spreadsheet is NOT UBL-TR compliant. If someone tries to sell you an invoicing solution for Turkey that produces only PDFs (without the XML), it does not satisfy the GİB requirement.

You need to know that only GİB-approved systems can generate valid UBL-TR invoices: The XML alone is not enough. It must also be submitted to GİB and receive a UUID. The UUID is GİB's confirmation that it has received and archived the invoice. Without a valid UUID, the invoice is not legally compliant even if the XML is perfectly formatted.

You do NOT need to write or edit XML: Neither the GİB portal nor AccountsOS requires you to touch the raw XML. You fill in a form, and compliant UBL-TR is generated and submitted automatically.

You do NOT need to store or manage the XML yourself: The GİB portal archives all submitted invoices. AccountsOS also maintains the XML archive. You are legally required to keep invoices for 10 years, but the archiving is handled for you.

When do you need to understand UBL-TR in depth?

Technical understanding of UBL-TR matters if you are:

Building a custom e-invoicing integration: If you have a bespoke billing system, ERP, or SaaS platform that generates invoices for Turkish customers, you need to either integrate with an özel entegratör API or build a UBL-TR 1.2.1 XML generator that passes GİB validation. GİB publishes the full technical specifications, schema files (XSD), and code lists at efatura.gov.tr.

Validating inbound e-Fatura invoices: Businesses on the e-Fatura network receive UBL-TR XML invoices from their suppliers. If you need to parse, validate, and process these programmatically, you need to understand the schema.

Developing an accounting application for Turkey: Any accounting software that supports Turkish e-invoicing must produce valid UBL-TR 1.2.1. This requires implementing GİB's technical specifications, including the UUID generation, digital signature, and XML validation rules.

For these use cases, GİB's developer documentation at efatura.gov.tr is the authoritative reference, alongside GİB Communiqué 509 (the primary legal instrument governing e-invoice format and content).

How does AccountsOS handle UBL-TR?

AccountsOS generates UBL-TR 1.2.1 XML internally from the invoice details you enter. The process is:

1. You fill in the invoice form (customer, line items, KDV rates, dates)
2. AccountsOS constructs the UBL-TR 1.2.1 XML document with all required fields
3. AccountsOS submits the XML to GİB via the e-Arşiv Portal API
4. GİB validates the XML against the UBL-TR 1.2.1 schema and the Turkish business rules
5. If validation passes, GİB triggers the SMS approval to your phone
6. After you enter the SMS code, GİB assigns the UUID and returns it to AccountsOS
7. AccountsOS inserts the UUID into the PDF and the XML, and archives both

You see a clean invoice interface. The UBL-TR XML is the technical layer that makes it legally valid, generated and handled entirely by AccountsOS.

Issued invoices in AccountsOS feed directly into your accounting books: accounts receivable, KDV output, and financial reports are updated automatically. Finn, the AI accountant, can answer questions about your outstanding invoices, monthly revenue, or KDV liability at any time.

AccountsOS issues e-Arşiv invoices directly through GİB, with no özel entegratör required. Try it free for 14 days at accounts-os.com/signup.

Turkish e-invoicing technical standards: a reference map

Frequently Asked Questions

Is UBL-TR the same as PEPPOL?

No, but they share the same underlying standard. PEPPOL BIS 3.0 (used in the EU, UK, and Singapore) is also based on UBL 2.1. UBL-TR 1.2.1 is Turkey's own national profile. The XML structures are similar but not identical. A PEPPOL invoice is not a valid Turkish UBL-TR invoice, and vice versa. Turkey is not part of the PEPPOL network; it has its own GİB-operated network.

What happens if my UBL-TR XML fails GİB validation?

GİB returns an error code and description specifying which rule was violated. Common failures: missing mandatory field, invalid code list value, incorrect UUID format, schema validation error. The GİB portal and AccountsOS both surface the specific error. Correct the issue and resubmit. Invoices are not created or charged to your quota until they pass validation.

Can I view the UBL-TR XML of invoices I have issued?

Yes. The GİB e-Arşiv Portal allows you to download the XML of any invoice you have issued. In AccountsOS, the XML is stored against each invoice record and can be downloaded. Both the PDF (for human reading) and the XML (for machine processing and legal archive) are available.

Why is the invoice number in a specific format (e.g. GIB2026000000001)?

Turkish e-invoicing rules require invoice numbers to follow a GİB-specified format: a prefix (which for portal-issued invoices includes "GIB") followed by the 4-digit year and a zero-padded sequential number. The portal and AccountsOS manage this sequence automatically. You cannot use arbitrary invoice numbers. They must follow the format or GİB will reject the submission.

Does the UBL-TR format support instalment payment terms?

Yes. UBL-TR includes payment means and payment terms elements where you can specify payment due date, bank account details for transfer, and multi-instalment arrangements. AccountsOS supports specifying payment terms on invoices, which are included in the UBL-TR XML.

What is GİB Communiqué 509 and why does it matter?

GİB Communiqué 509 (Genel Tebliğ 509) is the primary legal document governing Turkey's e-invoice regime. It defines which businesses must use e-Fatura and e-Arşiv, the technical requirements for each, the content rules for invoices, and the archive obligations. It has been amended multiple times since its original publication. The threshold removal from 1 January 2026 was implemented via a subsequent communiqué (Communiqué 535). When in doubt about a compliance question, Communiqué 509 and its amendments are the authoritative source. See gib.gov.tr.

Can I create an e-Arşiv invoice offline?

No. e-Arşiv invoices require real-time submission to GİB for approval and UUID assignment. You cannot create a compliant e-Arşiv invoice without an internet connection and active GİB communication at the moment of issuance. The SMS approval also requires mobile network access. There is no offline mode.

Do I need a digital signature for e-Arşiv?

The UBL-TR XML submitted to GİB includes a digital signature element. However, for businesses using the GİB e-Arşiv Portal (or AccountsOS, which connects to the portal), the digital signature is applied by GİB's own systems as part of the archiving process. You do not need a separate digital signature certificate for e-Arşiv. For e-Fatura (the larger-business system), the requirements may differ. Some paths require a qualified electronic certificate (NES or Mali Mühür).