GetbeelDocs

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/invoices with withholding (the DatiRitenuta block) and, if needed, cassa_previdenziale. The customer pays amount_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/withholdings keeps one fee per row; at year end /v1/withholdings/cu gives 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.amount can be left out: Getbeel computes rate × (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 send subject_to_withholding: true. Subject lines get <Ritenuta>SI</Ritenuta>.
  • For commissions (reason Q to V) the rate applies to part of the amount only (art. 25-bis DPR 600/1973): amount is required.
  • withholding.contributions: further DatiRitenuta blocks for contributions the customer withholds (RT03 INPS, RT04 ENASARCO, RT05 ENPAM, RT06 other). They also reduce amount_due and ImportoPagamento.
  • cassa_previdenziale.amount can be left out: rate × fees (lines except N1); Getbeel also writes ImponibileCassa. subject_to_withholding is 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).
  • reason is 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:

FieldCUHow
gross_amountpunto 4Lines without VAT + cassa contribution subject to withholding. The integrative contribution (cassa without Ritenuta SI) is left out
not_subject_amountpunto 7The rest: expenses advanced, the non-subject share of commissions (50% or 80%)
taxable_amountpunto 8The base the issuer applied the rate to: the lines with Ritenuta SI, or the share that matches ImportoRitenuta
withheld_amountpunto 9Sum 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} with paid_on.
  • withheld: fee paid, withholding to pay by due_date (the 16th of the next month, moved to the next working day). overdue after 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, PATCH with { "remitted": true } links and locks it (409 no_paid_filing when 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

On this page