Foreign currency invoice

An invoice in GBP whose tax amount is additionally stated in EUR – including the exchange rate and its date. Plus a tax representative, a separate payee, an invoicing period, a prepayment and line-level allowances.

The basis is the official sample invoice X07_01_Fremdwaehrung from the Factur-X / ZUGFeRD documentation (FeRD sample package, ZUGFeRD 2.5.0, EXTENDED profile). The code below produces exactly that document, field by field and in the same order.

Some links on this page lead into the in-depth documentation in the customer area and require a sign-in.

This is the most demanding of the three sample documents: it brings together in one file what is otherwise spread across many pages. If you are building an EXTENDED document for the first time, the extended goods invoice is the better starting point; this page is about the special cases.

What this example covers

  • Two currencies: invoice currency GBP (BT-5), accounting currency EUR (BT-6)
  • The tax amount twice – once per currency (BT-110 and BT-111) – plus the exchange rate (BG-X-41)
  • Seller tax representative (BG-11) and a separate payee (BG-10)
  • Allowances at line level as SpecifiedTradeAllowanceCharge
  • Invoicing period (BT-73/BT-74) and a prepayment (BT-113)

1. Invoice header and the two currencies

The decisive line is invoice.TaxCurrency. All amounts in the document are stated in the invoice currency BT-5, here GBP; the accounting currency BT-6 concerns only the additionally stated tax amount.

2. Free-text notes

The code TXD (tax information) tells the human reader why two currencies appear in the document at all – a useful complement to the structured fields further down.

Line breaks and indentation inside a note are significant in the XML. The tabs in the first call are not decoration – they are taken character for character from the reference file, and without them the cross-check reports a difference.

Note texts, product names and allowance reasons stay in German throughout this page: they are the payload of the official reference document, and translating them would break the comparison with it.

3. Seller and tax representative

The tax representative (BG-11) is a party in its own right with its own VAT ID – typical when a foreign supplier operates domestically through a fiscal representative. It is set like any other party, but its tax number goes through a dedicated method.

4. Buyer

Two small things that are often searched for: street2 fills ram:LineTwo, i.e. the second address line, and the buyer's electronic address (BT-49) carries a Leitweg-ID here.

5. Delivery and invoicing period

The ship-to party carries an electronic address as well. Unlike seller and buyer, there is no Set… method for it: the ElectronicAddress field hangs directly off the party and is written in the EXTENDED profile only.

6. Payee and bank account

Payment goes not to the seller but to its financial services provider (BG-10). The bank account is set separately through AddCreditorFinancialAccount.

7. Line item with allowances

A single line, but with the distinction that gets confused most often in practice: there are two different kinds of allowance at line level.

Method XML element Effect
AddTradeAllowance ram:AppliedTradeAllowanceCharge
(inside the gross price)		 Amount per unit. Lowers the net price. This is what the goods invoice does.
AddSpecifiedTradeAllowance ram:SpecifiedTradeAllowanceCharge
(in the line settlement)		 Amount for the entire line. Lowers the line total, the price stays unchanged. That is the route used here.

Concretely: the unit price stays at GBP 100, while the two allowances bring the line total down from 1,000 to GBP 850.

8. Document-level charges and allowances

A charge for single-use packaging and a percentage loyalty discount. In the XML both share the same element ram:SpecifiedTradeAllowanceCharge and are distinguished only by ram:ChargeIndicator. The writer emits them in the order they were added, which is why the charge comes first in the code.

9. VAT in the invoice currency

At first entirely ordinary, in GBP: 850.00 + 30.00 − 21.25 = 858.75, of which 19 % = 163.1625 → GBP 163.16.

10. Tax amount in the accounting currency and the exchange rate

For the VAT return, the tax amount in a foreign currency is not enough: Art. 230 of the EU VAT Directive (2006/112/EC) requires the amount in the seller's national currency as well. Three related pieces of information exist for that:

Code Field Meaning
BT-6 TaxCurrency The accounting currency itself, here EUR.
BT-111 TaxTotalAmountInAccountingCurrency The same tax amount, converted into BT-6: EUR 183.14.
BG-X-41 TaxCurrencyExchange (group) The rate the conversion was made with.
BT-X-258 SourceCurrency Invoice currency, i.e. BT-5 (GBP). FactoorSharp derives it automatically.
BT-X-259 TargetCurrency Accounting currency, i.e. BT-6 (EUR).
BT-X-260 ConversionRate The rate itself, here 1.12244.
BT-X-261 ConversionRateTimestamp Rate date, optional. Here the delivery date, 25 November 2025.

Without BG-X-41 the document would carry only the result, not the way there – and for an accounting department that wants to recompute the amount or check it against the daily rate, that is exactly the missing piece.

Why one method for three business terms? Because EN 16931 business rule BR-53 requires that if BT-6 is present, BT-111 must be supplied too. And the rate in BG-X-41 is the justification for the value in BT-111. Separate setters would have allowed a tax amount in the accounting currency to be set without ever stating which rate produced it – or conversely, a rate to be recorded that matches no reported amount.

The former method SetTaxTotalInAccountingCurrency set only BT-111 and BT-6, without a rate. It was removed in version 20.0; use SetTaxCurrencyExchange instead.

About the rate itself: BT-X-260 is defined in the schema as a plain xs:decimal with no digit limit, and the FeRD reference writes five decimal places. The writer therefore rounds adaptively – to two places where that is lossless, otherwise to up to five – and reproduces 1.12244 exactly. The rate date, like every date field in this library, is written in UN/CEFACT format 102 (CCYYMMDD).

BG-X-41 exists in the EXTENDED profile only and is modelled on the CII side exclusively. UBL does have a structurally comparable element in cac:TaxExchangeRate, but that lies outside the EN 16931 CIUS and is therefore not served by FactoorSharp – see UBL vs. CII.

11. Payment terms

Two stages, deliberately as plain free text with a date here. How an early payment discount is made machine-readable instead is shown in the goods invoice.

12. Document totals

All totals are in GBP. New compared to the other examples is the prepayment (BT-113), which is deducted from the grand total:

BT code Parameter Calculation (GBP)
BT-106 lineTotalAmount 850.00 (line total after the two allowances)
BT-108 chargeTotalAmount 30.00 (single-use packaging)
BT-107 allowanceTotalAmount 21.25 (loyalty discount)
BT-109 taxBasisAmount 850.00 + 30.00 − 21.25 = 858.75
BT-110 taxTotalAmount 858.75 × 19 % = 163.16
BT-112 grandTotalAmount 858.75 + 163.16 = 1,021.91
BT-113 totalPrepaidAmount 500.00. How individual instalments are itemised is covered under advance payments.
BT-115 duePayableAmount 1,021.91 − 500.00 = 521.91

13. Saving and checking

The result has to have the same tree structure as X07_01_Fremdwaehrung.xml from the FeRD sample package. Whether the document also complies with the rule set is something you check either in the browser or straight from your code.

One finding is to be expected there and does not come from the rebuild: the FeRD reference carries 04011000-1234512345-35 as its Leitweg-ID, and that value's check digit is wrong. It is taken character for character from the template, so the finding hits the template just as much. If you use this invoice as a document of your own, put a valid Leitweg-ID in that place.

A human-readable rendition is produced by the visualizer; how it becomes a PDF/A-3 with embedded XML is covered under working with PDF files.