Is this XML structure correct for invoices that include retention amounts?

Clearance and Reporting
1

@Ankit.K.Tiwari , @idaoud

Hello,

I am working on generating an e-invoice that includes a retention amount.
In my XML, I have included the retention value as an OutOfScope tax category under <cac:TaxSubtotal> in the <cac:TaxTotal> section.

Here’s the relevant part of the XML:

<cac:LegalMonetaryTotal>
    <cbc:LineExtensionAmount currencyID="SAR">1000.00</cbc:LineExtensionAmount>
    <cbc:TaxExclusiveAmount currencyID="SAR">950.00</cbc:TaxExclusiveAmount>
    <cbc:TaxInclusiveAmount currencyID="SAR">1100.00</cbc:TaxInclusiveAmount>
    <cbc:AllowanceTotalAmount currencyID="SAR">50.00</cbc:AllowanceTotalAmount>
    <cbc:PayableAmount currencyID="SAR">1100.00</cbc:PayableAmount>
</cac:LegalMonetaryTotal>

<cac:TaxTotal>
    <cbc:TaxAmount currencyID="SAR">150.00</cbc:TaxAmount>
    <cac:TaxSubtotal>
        <cbc:TaxableAmount currencyID="SAR">1000.00</cbc:TaxableAmount>
        <cbc:TaxAmount currencyID="SAR">150.00</cbc:TaxAmount>
        <cac:TaxCategory>
            <cbc:Percent>15.00</cbc:Percent>
            <cac:TaxScheme>
                <cbc:ID schemeID="UN/ECE 5153">VAT</cbc:ID>
            </cac:TaxScheme>
        </cac:TaxCategory>
    </cac:TaxSubtotal>

    <!-- Retention represented as Out of Scope -->
    <cac:TaxSubtotal>
        <cbc:TaxableAmount currencyID="SAR">50.00</cbc:TaxableAmount>
        <cbc:TaxAmount currencyID="SAR">0.00</cbc:TaxAmount>
        <cac:TaxCategory>
            <cbc:TaxExemptionReasonCode>VATEX-SA-0</cbc:TaxExemptionReasonCode>
            <cbc:TaxExemptionReason>Retention Amount</cbc:TaxExemptionReason>
            <cac:TaxScheme>
                <cbc:ID schemeID="UN/ECE 5153">VAT</cbc:ID>
            </cac:TaxScheme>
        </cac:TaxCategory>
    </cac:TaxSubtotal>
</cac:TaxTotal>

retentionImg
retentionImg1168×1051 350 KB

:red_question_mark:My Doubt:

Is it valid to represent the retention amount as an OutOfScope tax subtotal in this way?
Or is there a specific tag or structure ZATCA expects for handling retention in the invoice XML?

2 
    <cac:LegalMonetaryTotal>
        <cbc:LineExtensionAmount currencyID="SAR">1000.00</cbc:LineExtensionAmount>
        <cbc:TaxExclusiveAmount currencyID="SAR">950.00</cbc:TaxExclusiveAmount>
        <cbc:TaxInclusiveAmount currencyID="SAR">1100.00</cbc:TaxInclusiveAmount>
        <cbc:AllowanceTotalAmount currencyID="SAR">50.00</cbc:AllowanceTotalAmount>
        <cbc:PayableAmount currencyID="SAR">1100.00</cbc:PayableAmount>
    </cac:LegalMonetaryTotal>
....

<cac:TaxTotal>
    <cbc:TaxAmount currencyID="SAR">150.00</cbc:TaxAmount>
</cac:TaxTotal>
<cac:TaxTotal>
    <cbc:TaxAmount currencyID="SAR">150.00</cbc:TaxAmount>
    <cac:TaxSubtotal>
        <cbc:TaxableAmount currencyID="SAR">1000.00</cbc:TaxableAmount>
        <cbc:TaxAmount currencyID="SAR">150.00</cbc:TaxAmount>
         <cac:TaxCategory>
             <cbc:ID schemeAgencyID="6" schemeID="UN/ECE 5305">S</cbc:ID>
             <cbc:Percent>15.00</cbc:Percent>
            <cac:TaxScheme>
               <cbc:ID schemeAgencyID="6" schemeID="UN/ECE 5153">VAT</cbc:ID>
            </cac:TaxScheme>
         </cac:TaxCategory>
    </cac:TaxSubtotal>
    <cac:TaxSubtotal>
        <cbc:TaxableAmount currencyID="SAR">-50.00</cbc:TaxableAmount>
        <cbc:TaxAmount currencyID="SAR">0</cbc:TaxAmount>
        <cac:TaxCategory>
            <cbc:ID schemeAgencyID="6" schemeID="UN/ECE 5305">O</cbc:ID>
            <cbc:Percent>0.00</cbc:Percent>
            <cbc:TaxExemptionReasonCode>VATEX-SA-OOS</cbc:TaxExemptionReasonCode>
            <cbc:TaxExemptionReason>Retention</cbc:TaxExemptionReason>
            <cac:TaxScheme>
                <cbc:ID schemeAgencyID="6" schemeID="UN/ECE 5153">VAT</cbc:ID>
            </cac:TaxScheme>
        </cac:TaxCategory>
    </cac:TaxSubtotal>
</cac:TaxTotal>

<cbc:TaxableAmount currencyID=“SAR”>-50.00</cbc:TaxableAmount>

In the Pic is correct , and you should add This Part also

<cac:AllowanceCharge>
    <cbc:ChargeIndicator>false</cbc:ChargeIndicator>
    <cbc:AllowanceChargeReasonCode>64</cbc:AllowanceChargeReasonCode>
    <cbc:AllowanceChargeReason>Retention</cbc:AllowanceChargeReason>
    <cbc:Amount currencyID="SAR">50.00</cbc:Amount>
    <cac:TaxCategory>
        <cbc:ID schemeAgencyID="6" schemeID="UN/ECE 5305">O</cbc:ID>
        <cbc:Percent>0.00</cbc:Percent>
        <cac:TaxScheme>
            <cbc:ID schemeAgencyID="6" schemeID="UN/ECE 5153">VAT</cbc:ID>
        </cac:TaxScheme>
    </cac:TaxCategory>
</cac:AllowanceCharge>
3

I added it like:

        <cac:AllowanceCharge>
        <cbc:ChargeIndicator>false</cbc:ChargeIndicator>
        <cbc:AllowanceChargeReason>Retention</cbc:AllowanceChargeReason>
        <cbc:Amount currencyID="SAR">50</cbc:Amount>
        <cac:TaxCategory>
            <cbc:ID>O</cbc:ID>
            <cbc:Percent>0</cbc:Percent>
            <cbc:TaxExemptionReasonCode>VATEX-SA-OOS</cbc:TaxExemptionReasonCode>
            <cbc:TaxExemptionReason>Retention Amount</cbc:TaxExemptionReason>								
            <cac:TaxScheme>
                <cbc:ID>VAT</cbc:ID>
            </cac:TaxScheme>
        </cac:TaxCategory>
    </cac:AllowanceCharge>

is there any issue. the xml have no errors or warnings while submitting to ZATCA API

4

@Ankit.K.Tiwari @idaoud @SP_AlMizan

can you please help me on this.

in allowanceCharge which is correct both versions are not returning any error or warning so i am confused. which is correct 1 or 2

        <cac:AllowanceCharge>
        <cbc:ChargeIndicator>false</cbc:ChargeIndicator>
        <cbc:AllowanceChargeReason>Retention</cbc:AllowanceChargeReason>
        <cbc:Amount currencyID="SAR">50</cbc:Amount>
        <cac:TaxCategory>
            <cbc:ID>O</cbc:ID>
            <cbc:Percent>0</cbc:Percent>
            <cbc:TaxExemptionReasonCode>VATEX-SA-OOS</cbc:TaxExemptionReasonCode>
            <cbc:TaxExemptionReason>Retention Amount</cbc:TaxExemptionReason>								
            <cac:TaxScheme>
                <cbc:ID>VAT</cbc:ID>
            </cac:TaxScheme>
        </cac:TaxCategory>
    </cac:AllowanceCharge>

<cac:AllowanceCharge>
    <cbc:ChargeIndicator>false</cbc:ChargeIndicator>
    <cbc:AllowanceChargeReasonCode>64</cbc:AllowanceChargeReasonCode>
    <cbc:AllowanceChargeReason>Retention</cbc:AllowanceChargeReason>
    <cbc:Amount currencyID="SAR">50.00</cbc:Amount>
    <cac:TaxCategory>
        <cbc:ID schemeAgencyID="6" schemeID="UN/ECE 5305">O</cbc:ID>
        <cbc:Percent>0.00</cbc:Percent>
        <cac:TaxScheme>
            <cbc:ID schemeAgencyID="6" schemeID="UN/ECE 5153">VAT</cbc:ID>
        </cac:TaxScheme>
    </cac:TaxCategory>
</cac:AllowanceCharge>