# Withholding tax (ritenute) (https://docs.getbeel.com/en/api/withholdings)

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](/en/api/filings)). Recording withholdings is free.

## Issuing an invoice with a withholding [#issuing-an-invoice-with-a-withholding]

```bash
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 [#withholdings-you-owe]

```bash
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}` 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):

```bash
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 [#the-months-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](/en/api/filings). Once the receipt is uploaded, those withholdings become `remitted`.

## Certificazione Unica and 770 [#certificazione-unica-and-770]

```bash
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.

<Callout title="Not the telematic file" type="warn">
  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.
</Callout>

## Sources [#sources]

- [FatturaPA technical specifications, Allegato A, version 1.9.1](https://www.agenziaentrate.gov.it/portale/documents/d/guest/allegato-a-specifiche-tecniche-vers-1-9-1) and [XSD 1.2.3](https://www.fatturapa.gov.it/it/norme-e-regole/documentazione-fattura-elettronica/formato-fatturapa/): `DatiRitenuta` (0..N), `TipoRitenuta` RT01–RT06, `CausalePagamento`, `Ritenuta` on 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](https://www1.agenziaentrate.gov.it/servizi/codici/ricerca/SezioneErario.php?CT=1040) and [Risoluzione 13/E of 17 March 2016](https://www.agenziaentrate.gov.it/portale/documents/20143/303158/Risoluzione+n.+13+del+17+marzo+2016_RIs+13e+del+17.03.16.pdf/21945510-c111-1c5d-bc36-ea35db076953) (from 2017 code 1038 for commissions is merged into 1040).
- [Certificazione Unica 2026 instructions](https://www.agenziaentrate.gov.it/portale/documents/20143/9602395/CU_istruzioni_2026.pdf/4184818b-05a3-acce-5956-70811c7d2233), "Certificazione lavoro autonomo, provvigioni e redditi diversi"; Modello 770/2026 instructions, quadro ST.
