background

How to import existing invoices using a UBL file

Tags:importinvoicesublinvoice importfacturenfactuurimporterenubl importmappingcustomer numberklantnummerxmlemailtaallanguagecccopy
Show me

You can import invoices by uploading a UBL file. Twikey maps the UBL fields to the corresponding invoice and customer fields automatically.

Import invoices via UBL

  1. Navigate to Invoices in the left-hand navigation menu.
  2. Click Import.
  3. Set Type to Invoices.
  4. Set Source to UBL or UBL without automatic collection.
  5. Select a Profile.
  6. Upload your UBL file.
**UBL without automatic collection** — even if the customer has a signed mandate, the imported invoices will not be automatically collected via direct debit.

Customer identification

A reference to the customer is required for every invoice in the file. Either an email address or a customer number must be present, otherwise the file cannot be imported.

A customer number is strongly recommended to ensure invoices are imported to the correct customer. The mapping of the customer number can be set to a fixed field on request — contact our support team.

UBL field mapping

The sections below show how Twikey maps UBL fields to invoice and customer data.

Customer number

Twikey looks for the customer number in the following UBL fields, in this order:

AccountingCustomerParty > SupplierAssignedAccountID

<cac:AccountingCustomerParty>
    <cbc:SupplierAssignedAccountID>customerNumber123</cbc:SupplierAssignedAccountID>
</cac:AccountingCustomerParty>

AccountingCustomerParty > AdditionalAccountID

<cac:AccountingCustomerParty>
    <cbc:AdditionalAccountID>customerNumber123</cbc:AdditionalAccountID>
</cac:AccountingCustomerParty>

AccountingCustomerParty > Party > PartyIdentification > ID

<cac:AccountingCustomerParty>
    <cac:Party>
        <cac:PartyIdentification>
            <cbc:ID>CUSTOMERNUMBER123</cbc:ID>
        </cac:PartyIdentification>
    </cac:Party>
</cac:AccountingCustomerParty>
The value of this field is converted to uppercase (example: BE0533800797).

AccountingCustomerParty > Party > PartyIdentification > CompanyID

<cac:AccountingCustomerParty>
    <cac:Party>
        <cac:PartyIdentification>
            <cbc:CompanyID>CUSTOMERNUMBER123</cbc:CompanyID>
        </cac:PartyIdentification>
    </cac:Party>
</cac:AccountingCustomerParty>
The value of this field is converted to uppercase (example: BE0533800797).

AccountingCustomerParty > CustomerAssignedAccountID

<cac:AccountingCustomerParty>
    <cbc:CustomerAssignedAccountID>customerNumber123</cbc:CustomerAssignedAccountID>
</cac:AccountingCustomerParty>

Customer fields

Language: AccountingCustomerParty > Party > Language > ID

Emails for the invoice are sent in the language provided. When no language is provided:

  • Invoices for existing customers are sent in the customer's set language.
  • Invoices for new customers are sent in the language defined in your company information.
  • When the language is not enabled on the profile, the invitation defaults to English.
<cac:AccountingCustomerParty>
    <cac:Party>
        <cac:Language>
            <cbc:ID>NL</cbc:ID>
        </cac:Language>
    </cac:Party>
</cac:AccountingCustomerParty>

Email: AccountingCustomerParty > Party > Contact > ElectronicMail

<cac:AccountingCustomerParty>
    <cac:Party>
        <cac:Contact>
            <cbc:ElectronicMail>email@example.com</cbc:ElectronicMail>
        </cac:Contact>
    </cac:Party>
</cac:AccountingCustomerParty>

Emails in copy: AccountingCustomerParty > Party > Contact > OtherCommunication > Value

Add one or more CC email addresses. For new customers, the CC emails are saved on the customer record. For existing customers, the CC emails are added to the invoice only. When sending invitations or reminders, both the invoice CC and customer CC addresses are included.

To add multiple CC addresses, repeat the cac:OtherCommunication > cbc:Value block.

<cac:AccountingCustomerParty>
    <cac:Party>
        <cac:Contact>
            <cac:OtherCommunication>
                <cbc:Value>copyemail@example.com</cbc:Value>
            </cac:OtherCommunication>
        </cac:Contact>
    </cac:Party>
</cac:AccountingCustomerParty>

Mobile: AccountingCustomerParty > Party > Contact > Telephone

Street: AccountingCustomerParty > Party > PostalAddress > StreetName

City: AccountingCustomerParty > Party > PostalAddress > CityName

ZIP: AccountingCustomerParty > Party > PostalAddress > PostalZone

Country: AccountingCustomerParty > Party > PostalAddress > Country

Company fields

Company name: AccountingCustomerParty > Party > PartyName > Name

<cac:AccountingCustomerParty>
    <cac:Party>
        <cac:PartyName>
            <cbc:Name>Company Name</cbc:Name>
        </cac:PartyName>
    </cac:Party>
</cac:AccountingCustomerParty>

Company name: AccountingCustomerParty > Party > PartyLegalEntity > RegistrationName

<cac:AccountingCustomerParty>
    <cac:Party>
        <cac:PartyLegalEntity>
            <cbc:RegistrationName>Company Name</cbc:RegistrationName>
        </cac:PartyLegalEntity>
    </cac:Party>
</cac:AccountingCustomerParty>

Chamber of commerce: AccountingCustomerParty > PartyIdentification > ID

Chamber of commerce: AccountingCustomerParty > PartyIdentification > CompanyID

Last Update: 2026-03-10