How to Correctly Include Multiple Prepayment Items in a Single Invoice Line? (UBL 2.1 / ZATCA Compliance)

XML and business rules
1

Issue:
I’m trying to adjust a prepayment invoice (with multiple items) against a standard tax invoice. However, when I add multiple <cac:Item> elements under a single prepayment <cac:InvoiceLine>, I encounter two errors:

  1. SaxonApiException – “A sequence of more than one item is not allowed as the first argument of fn:string-length()”
  2. XSD_SCHEMA_ERROR – “Invalid content found: Only one <cac:Item> is allowed per <cac:InvoiceLine>”

Additionally, I received BR-KSA-80, warning that the prepaid amount must match the sum of taxable + tax amounts.

What I Tried:

  • Added multiple <cac:Item> tags under a single prepayment line (invalid per UBL 2.1).
  • Split into separate <cac:InvoiceLine> elements for each prepayment item (works but duplicates <DocumentReference>).

Questions:

  1. Is there a ZATCA-approved way to reference multiple prepayment items in a single line?
  • For example, can I use a generic <cbc:Name> like “Prepayment for Multiple Items” and aggregate the amounts?
  • Or must each item have its own line (even if it repeats the same <DocumentReference>)?
  1. How should <cbc:PrepaidAmount> align with multiple prepayment taxable amounts?
  • If I split items into separate lines, should the total prepaid amount be the sum of all prepayment line totals (taxable + tax)?

Example XML Snippet:

xml

Option 1: Single line with generic description (allowed?)

<cac:InvoiceLine>
    <cbc:ID>2</cbc:ID>
    <cbc:InvoicedQuantity>0.00</cbc:InvoicedQuantity>
    <cac:Item>
        <cbc:Name>Prepayment for Laptop, Smartphone</cbc:Name>
    </cac:Item>
    <cac:TaxTotal>
        <cac:TaxSubtotal>
            <cbc:TaxableAmount>1500</cbc:TaxableAmount> <!-- Sum of items -->
            <cbc:TaxAmount>225</cbc:TaxAmount>         <!-- Sum of taxes -->
        </cac:TaxSubtotal>
    </cac:TaxTotal>
</cac:InvoiceLine>

Option 2: Separate lines (compliant but repetitive)

<cac:InvoiceLine> <!-- Laptop prepayment --> </cac:InvoiceLine>
<cac:InvoiceLine> <!-- Smartphone prepayment --> </cac:InvoiceLine>

Additional Context:

  • The prepayment was a single advance invoice (one <DocumentReference>) covering multiple items.
  • I need to ensure compliance with BR-KSA-80 (prepaid amount validation).

Would appreciate guidance on the correct approach!

2

@arjun_tech24 please go through Section 8 of the Detailed Technical Guideline. Also check the sample XMLs for advance payment scenarios included in SDK.