Withholding tax (ritenute)
Invoices with ritenuta and cassa previdenziale, withholdings owed as sostituto d'imposta, F24 code 1040 and data for the Certificazione Unica and the 770.
Two sides of the same withholding:
- You issue a professional's invoice:
POST /v1/invoiceswithwithholding(theDatiRitenutablock) and, if needed,cassa_previdenziale. The customer paysamount_due, the total less the withholdings. - You pay a professional or an agent: you are the sostituto d'imposta, you withhold the ritenuta and pay it yourself with an F24 (tax code 1040) by the 16th of the month after the payment.
/v1/withholdingskeeps one fee per row; at year end/v1/withholdings/cugives the data for the CU and the 770.
Scopes: taxes:read to read, taxes:write to write (live key, like filings). Recording withholdings is free.
Issuing an invoice with a withholding
curl -X POST https://www.getbeel.com/api/v1/invoices \
-H "Authorization: Bearer $GETBEEL_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"customer": { "denominazione": "Cliente S.r.l.", "partita_iva": "01234567890" },
"lines": [
{ "description": "Consulting, October", "unit_price": "1000.00", "vat_rate": "22" },
{ "description": "Expenses advanced", "unit_price": "50.00", "natura": "N1" }
],
"cassa_previdenziale": { "type": "TC22", "rate": "4", "vat_rate": "22", "subject_to_withholding": true },
"withholding": { "type": "RT01", "rate": "20", "reason": "A" }
}'withholding.amountcan be left out: Getbeel computesrate× (subject lines + the cassa contribution when subject). Natura N1 lines (expenses advanced in the customer's name, art. 15 DPR 633/72) are not subject unless you sendsubject_to_withholding: true. Subject lines get<Ritenuta>SI</Ritenuta>.- For commissions (
reasonQ to V) the rate applies to part of the amount only (art. 25-bis DPR 600/1973):amountis required. withholding.contributions: furtherDatiRitenutablocks for contributions the customer withholds (RT03 INPS, RT04 ENASARCO, RT05 ENPAM, RT06 other). They also reduceamount_dueandImportoPagamento.cassa_previdenziale.amountcan be left out:rate× fees (lines except N1); Getbeel also writesImponibileCassa.subject_to_withholdingis for a rivalsa that is part of the fee; the integrative contribution of the professional funds is not part of it (CU 2026 instructions, punto 4).reasonis the CU causale: accepted codes are those of the FatturaPA schema that are also CU 2026 causali (A, B, C, D, E, G, H, I, L, L1, M, M1, M2, N, O, O1, P, Q, R, S, T, U, V, V1, W, ZO).
The invoice returned has withholdings (type, rate, amount and causale of each block) and amount_due net of all of them.
Withholdings you owe
curl https://www.getbeel.com/api/v1/withholdings?paid_in=2026-10 \
-H "Authorization: Bearer $GETBEEL_API_KEY"Invoices received from SDI with DatiRitenuta RT01 or RT02 become a withholding on arrival (source: sdi). POST /v1/withholdings/sync reads the ones received earlier (100 per call, has_more). Getbeel derives the amounts the way the CU wants them:
| Field | CU | How |
|---|---|---|
gross_amount | punto 4 | Lines without VAT + cassa contribution subject to withholding. The integrative contribution (cassa without Ritenuta SI) is left out |
not_subject_amount | punto 7 | The rest: expenses advanced, the non-subject share of commissions (50% or 80%) |
taxable_amount | punto 8 | The base the issuer applied the rate to: the lines with Ritenuta SI, or the share that matches ImportoRitenuta |
withheld_amount | punto 9 | Sum of ImportoRitenuta of the RT01/RT02 blocks |
When the figures do not add up, the professional's codice fiscale is missing (the CU needs it) or the invoice has a discount on the total, the withholding has needs_review: true and notes says why.
status:
unpaid: you have not paid the fee yet, so nothing is withheld yet. When you pay:PATCH /v1/withholdings/{id}withpaid_on.withheld: fee paid, withholding to pay bydue_date(the 16th of the next month, moved to the next working day).overdueafter that.remitted: paid with an F24 recorded in Getbeel. It no longer changes (409 withholding_remitted).- If a fee changes after the F24 was prepared, compute the F24 again: paid as it is, it remits only the fees that stayed the same; the others stay due.
- A fee recorded after the month's F24 was paid, or an F24 prepared with
amount: if that withholding was in the paid F24,PATCHwith{ "remitted": true }links and locks it (409 no_paid_filingwhen the month has no paid F24). - Test keys do not see withholdings (real data about professionals, like received invoices).
A fee that did not come through SDI (paper invoice, receipt for occasional work):
curl -X POST https://www.getbeel.com/api/v1/withholdings \
-H "Authorization: Bearer $GETBEEL_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"recipient": { "name": "Luca Bianchi", "fiscal_code": "BNCLCU85M01H501Z" },
"causale": "M",
"rate": "20",
"gross_amount": "500.00",
"paid_on": "2026-10-20"
}'withheld_amount is computed when left out: (gross_amount − not_subject_amount) × rate.
The month's F24
POST /v1/filings with { "type": "withholdings", "period": "2026-10" } adds up the withholdings with paid_on in the month and prepares the F24 (Erario section, code 1040, month 10, year 2026). See Filings. Once the receipt is uploaded, those withholdings become remitted.
Certificazione Unica and 770
curl "https://www.getbeel.com/api/v1/withholdings/cu?year=2026" \
-H "Authorization: Bearer $GETBEEL_API_KEY"Per percipiente and causale, the fees paid in the year (the payment date counts): gross (punto 4), sums not subject (7), taxable (8), withheld (9), and how much was paid with F24s recorded in Getbeel. form_770 lists per month the withholdings made, the amount paid and the date (quadro ST, section I: punti 1, 2, 7, 11, 14). format=csv returns a spreadsheet (semicolons, comma decimals).
Deadlines (CU 2026 instructions, tax year 2025; for 2026 fees the CU 2027 instructions of January 2027 apply): CU to the percipiente by 16 March; to the Agenzia by 16 March, or by 30 April for habitual self-employment (causale A) and non-occasional commissions; 770 by 31 October.
Not the telematic file
Getbeel does not prepare the file sent to the Agenzia and does not sign the CU: this is the data to check and give to whoever files it (often the accountant), or to type into the Agenzia's software.
Sources
- FatturaPA technical specifications, Allegato A, version 1.9.1 and XSD 1.2.3:
DatiRitenuta(0..N),TipoRitenutaRT01–RT06,CausalePagamento,Ritenutaon lines and cassa, controls 00411 and 00415. - Art. 25 and 25-bis DPR 600/1973 (20% withheld when the fee is paid; commissions) and art. 18 D.Lgs. 241/1997 (payment by the 16th).
- Tax code 1040 and Risoluzione 13/E of 17 March 2016 (from 2017 code 1038 for commissions is merged into 1040).
- Certificazione Unica 2026 instructions, "Certificazione lavoro autonomo, provvigioni e redditi diversi"; Modello 770/2026 instructions, quadro ST.