# Taxes and deadlines (https://docs.getbeel.com/en/api/taxes)

Your Italian company's tax calendar, as JSON or as an .ics calendar, and the VAT position estimate.

Getbeel works out the company's tax deadlines from its profile (country, regime fiscale) and two settings you choose once, in the app (**Taxes**) or with `PATCH /companies/me/tax-settings`: monthly or quarterly VAT (`vat_periodicity`), whether the company pays professionals' fees with a withholding (`withholding_agent`) and, for companies registered in the OSS (VAT on B2C sales to consumers in other EU countries), the dates of the registration (`oss_from`, `oss_until`; `null` clears them). It is the same list as the **Taxes → Deadlines** page.

Scope: `taxes:read`. Italian companies only.

```bash
curl -X PATCH https://www.getbeel.com/api/v1/companies/me/tax-settings \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "vat_periodicity": "quarterly" }'
```

Changing them needs `taxes:write` and a live key; a `PATCH` changes only what it sends, and `GET /companies/me/tax-settings` reads them (`null` = not set yet). Set the periodicity as the company actually settles VAT: it decides the VAT periods of the registers, the liquidazioni and the F24. MCP tools: `get_tax_settings`, `update_tax_settings`.

<Callout title="Getbeel prepares, you pay">
  Getbeel never signs in to your Agenzia delle Entrate area and never pays for
  you. It prepares the amounts and the F24 (see [Filings](/en/api/filings)); you
  pay it in F24 web or from your bank.
</Callout>

## Tax profile [#tax-profile]

Each company pays different taxes. The tax profile says which apply and why: legal form, regime fiscale, VAT periodicity, withholding agent, employees, foreign suppliers (reverse charge), Intrastat, OSS, liquidation, first tax year and, for persons, social security and special income tax regimes (forfettario, impatriati, rientro docenti, neo-residenti). It is the same card as **Taxes → Your tax profile** in the app. Free on every plan.

```bash
curl https://www.getbeel.com/api/v1/companies/me/tax-profile \
  -H "Authorization: Bearer $GETBEEL_API_KEY"
```

Getbeel detects what it can from data it already has, and shows the evidence in `detection.fields.<field>` (`value`, `confidence`, `evidence.key` and `evidence.params`):

| Field                      | Detected from                                                                            |
| -------------------------- | ---------------------------------------------------------------------------------------- |
| `legal_form`               | The company name (S.r.l., S.p.A., …); a personal codice fiscale is only a hint           |
| `regime_fiscale`           | The company profile (the RF code on every issued invoice)                                |
| `vat_periodicity`          | Last year's turnover: above €800,000 it must be monthly (art. 7 DPR 542/1999)            |
| `withholding_agent`        | Withholdings recorded in the last 12 months                                              |
| `reverse_charge_suppliers` | Received invoices from suppliers outside Italy                                           |
| `intrastat`                | Sales to businesses in other EU countries                                                |
| `oss_suggested`            | Sales to consumers in other EU countries above €10,000 a year (art. 7-octies DPR 633/72) |
| `in_liquidation`           | "in liquidazione" in the company name                                                    |

Never a silent guess: a value you set always wins (`sources.<field>` = `user`); a high-confidence detection is used (`detected`); anything else stays `null` and is listed in `questions`, each with a plain-language question to ask the user once. Employees, the OSS registration, social security and special regimes are never taken from a detection: they are always asked.

```bash
curl -X PATCH https://www.getbeel.com/api/v1/companies/me/tax-profile \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "has_employees": true, "oss_registered": true, "confirm": ["legal_form"] }'
```

A `PATCH` changes only what it sends and marks it confirmed; `null` clears a value back to the detection; `confirm` confirms detected values as they are; `regimes` replaces the special income tax regimes (`[]`: none). `POST /companies/me/tax-profile/detect` runs the detection again now.

Every month (the 2nd) getbeel runs the detection again for every company that has run it before. A new obligation (withholdings, foreign suppliers, Intrastat) is applied and announced in the app ("New obligation: …"). A change that would take a deadline away or change it (for example no withholdings in the last 12 months, monthly instead of quarterly VAT, or a different legal form) is **never applied by a detection**, monthly or `POST …/detect`: the earlier value stays and the field carries `held` (`value`, `confidence`, `evidence`, `since`: what the new data say). The owner gets one notice in their language, and the app shows the field as "To check". Only your answer changes it: a `PATCH` with the value, or `confirm` to keep the earlier one. Changing the profile and running the detection need `taxes:write` and a live key; every change goes to the audit log with the key and the channel (API or MCP). MCP tools: `get_tax_profile`, `update_tax_profile`, `detect_tax_profile`.

When a special regime ends within a year (its last day is the `effect.ends_year` of each regime, or its own `valid_until` when earlier), the owners and the commercialisti get an email and the app shows a notice ("Impatriati (before 2024): ends on 31 December 2027, from 2028 it no longer applies"): once about a year before and once a month before. The end of the forfettario start-up rate is announced the same way, with both rates from the rule values (5% and then 15% today).

The profile changes the calendar: deadlines that do not apply are left out, and each one says why it applies in `applies_because`.

## The calendar [#the-calendar]

```bash
curl "https://www.getbeel.com/api/v1/companies/me/tax-calendar?from=2026-10-01&to=2027-03-31" \
  -H "Authorization: Bearer $GETBEEL_API_KEY"
```

Without `from` and `to`: from 90 days ago to a year from today (three years at most).

| `kind`               | What                                                                                  | Codici tributo                                         | Source                                                       |
| -------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------ |
| `bollo`              | Stamp duty on e-invoices, per quarter                                                 | 2521–2524                                              | Art. 6 DM 17/06/2014; Ris. AdE 42/E/2019                     |
| `withholdings`       | Withholding tax on professionals' fees and, with employees, on salaries, per month    | 1040; 1001                                             | Arts. 23, 25 DPR 600/1973; art. 18 D.Lgs. 241/97             |
| `vat_payment`        | Monthly or quarterly VAT payment                                                      | 6001–6012, 6031–6033                                   | DPR 100/1998; art. 7 DPR 542/1999                            |
| `vat_advance`        | VAT advance (27 December)                                                             | 6013, 6035                                             | Art. 6 L. 405/1990                                           |
| `vat_annual_balance` | Annual VAT balance (16 March)                                                         | 6099                                                   | Art. 6 DPR 542/1999                                          |
| `lipe`               | Quarterly VAT report (LIPE)                                                           | –                                                      | Art. 21-bis DL 78/2010                                       |
| `vat_return`         | Annual VAT return (30 April)                                                          | –                                                      | Art. 8 DPR 322/1998                                          |
| `pf_tax_return`      | Redditi PF return of an individual (31 October; 2 November 2026)                      | –                                                      | Art. 2 c. 1 DPR 322/1998                                     |
| `pf_tax_balance`     | Individual: saldo + first acconto (30 June; 20 July 2026 for ISA, forfettari, minimi) | 4001, 3801, 3844, 4033, 3843 / 1792, 1790 / 1795, 1793 | Art. 17 DPR 435/2001; DL 89/2026 art. 6                      |
| `pf_tax_advance`     | Individual: second acconto (30 November)                                              | 4034 / 1791 / 1794                                     | Art. 17 c. 3 DPR 435/2001                                    |
| `oss_return`         | OSS return and payment, per quarter (OSS only)                                        | – (Portale OSS)                                        | Arts. 369f, 369i Dir. 2006/112/EC; art. 74-sexies DPR 633/72 |

Each deadline has:

- `due_date`: the real date. Saturdays, Sundays and public holidays move to the next working day; 1–20 August moves to 20 August. `nominal_due_date` is the date the law names. When a published extension (proroga) moves the deadline, `due_date` is the new date and `extension` gives the official source (`source_title`, `source_url`); otherwise `extension` is `null`.
- `amount` and `amount_status`: stamp duty is computed from your issued invoices (`provisional` until the quarter ends). VAT amounts are `null` until you save the settlement; a saved settlement with nothing to pay makes the deadline `not_due`.
- `status`: `to_prepare`, `ready` (F24 prepared), `paid`, `filed` or `not_due` (no stamp duty due that quarter, or no VAT to pay).
- `can_prepare` and `filing_type`: whether Getbeel can prepare the filing: the F24 for bollo, withholdings and VAT (`vat_payment`, once the period is over) and the LIPE file (`lipe`).
- `needs_review`: for special VAT regimes the general rule may not fit. Check it ("da verificare").
- `source`: the law the deadline comes from.
- `applies_because`: why it applies to this company, from the tax profile, as keys with parameters: `issues_e_invoices`, `vat_monthly`, `vat_quarterly`, `vat_payer` (`regime`), `withholding_agent`, `has_employees`, `oss_registered`, `oss_sales` (`countries`).
- `review_key`: `in_liquidation` when the company is in liquidation and the deadline falls from that date: check it with the liquidator ("da verificare").
- OSS returns keep their date even on a weekend (EU rule) and are flagged `needs_review` then; they are paid from the Portale OSS, not with an F24.

`missing_settings` lists the settings still to choose in the app; until then the deadlines that depend on them are left out. Forfettari (RF19) and minimi (RF02) have no VAT deadlines.

### OSS (EU B2C sales) [#oss-eu-b2c-sales]

With `oss_from` set, the calendar adds `oss_return` for every quarter of the registration: the quarterly OSS return and its payment, due by the **last day of the month after the quarter** (30 April, 31 July, 31 October, 31 January), even with no sales (a nil return). Sources: Directive 2006/112/EC arts. 369f and 369i, Regulation (EU) 282/2011 art. 59a, DPR 633/72 arts. 74-quinquies and 74-sexies.

- The date is **not moved** on weekends or holidays: the European Commission's OSS page says so. The Agenzia does not say otherwise, so when it falls on a non-working day the deadline has `needs_review: true` ("da verificare").
- It is paid from the Agenzia's Portale OSS by direct debit or bank transfer with the reference `IT/<partita IVA>/Qn.YYYY`, **not with an F24**, and credits cannot offset it.
- From 2027 the rules move to the Testo unico IVA (D.Lgs. 10/2026, arts. 149–153); the dates are expected to stay the same (da verificare).

### Income taxes (companies) [#income-taxes-companies]

For a company that pays IRES (SRL, SpA), the calendar also lists, for a tax year that matches the calendar year and a bilancio approved within 120 days:

| `kind`                 | Due                                                                                                | F24 codes              | Source                                         |
| ---------------------- | -------------------------------------------------------------------------------------------------- | ---------------------- | ---------------------------------------------- |
| `income_tax_balance`   | IRES and IRAP saldo + first acconto: 30 June (ISA subjects, 2026 only: 20 July, DL 89/2026 art. 6) | 2003, 2001, 3800, 3812 | art. 17 c. 1-2 DPR 435/2001                    |
| `chamber_fee`          | Diritto annuale camerale, with the first acconto                                                   | 3850                   | art. 6 DM 21/04/2011                           |
| `income_tax_advance`   | Second acconto: 30 November (60%, or 50% for ISA subjects)                                         | 2002, 3813             | art. 17 c. 3 DPR 435/2001; art. 58 DL 124/2019 |
| `income_tax_return`    | Redditi SC and IRAP returns: 31 October (2 November in 2026)                                       | —                      | art. 2 c. 2 DPR 322/1998                       |
| `financial_statements` | Deposito del bilancio: 30 May (not moved: a civil-law deadline)                                    | —                      | artt. 2435 and 2478-bis c.c.                   |

Whether the company pays IRES and applies ISA comes from **Taxes → Tax estimate**, per tax year (`settings.income_tax`). Until it is saved there, nothing is guessed: the deadlines are left out and `missing_settings` contains `income_tax`. ISA subjects pay by 21 July in 2025 (DL 84/2025 art. 13) and 20 July in 2026. The deadlines are `needs_review` from 2027, because the payment rules move to the Testo unico versamenti (D.Lgs. 33/2025) and the same dates are assumed. Code 3813 (IRAP second acconto) is in the AdE codici tributo table (11 November 2026), and the IRAP return is due the same day as Redditi SC (DM 11 September 2008, art. 2 DPR 322/1998). Amounts are not computed here yet: see the tax estimate.

### INPS contributions (persons with partita IVA) [#inps-contributions-persons-with-partita-iva]

For a person, the calendar adds the INPS deadlines of the scheme in the tax profile (`social_security`):

| `kind`                   | Due                                                                                                                                                                    | F24 causale                             | Source                                                |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | ----------------------------------------------------- |
| `inps_fixed`             | Artigiani / commercianti, fixed contributions on the minimale: 16 May, 16 August (paid by 20 August), 16 November, 16 February of the next year. `period` is `YYYY-Qn` | AF / CF                                 | art. 18 c. 1-2 D.Lgs. 241/1997; INPS circ. 14/2026 §9 |
| `inps_balance`           | Saldo of last year + first acconto: 30 June (30 July with 0.40%)                                                                                                       | AP / CP; PXX or P10 (gestione separata) | art. 18 c. 4 D.Lgs. 241/1997; INPS circ. 62/2026 §3   |
| `inps_advance`           | Second acconto: 30 November                                                                                                                                            | AP / CP; PXX or P10                     | art. 18 c. 4 D.Lgs. 241/1997; INPS circ. 62/2026 §3   |
| `inps_reduction_request` | Forfettari artigiani / commercianti: request for the 35% reduction by 28 February (not moved; `needs_review` when it is not a working day)                             | —                                       | art. 1 c. 83 L. 190/2014; INPS circ. 14/2026 §8       |

- A **cassa professionale** has its own calendar: nothing is listed for it. With no scheme in the profile, nothing is guessed.
- In the first fiscal year there is no saldo of the year before, no second acconto and no 28 February request (a new business asks for the 35% when it enrols). The four fixed instalments are listed: when you start during the year, only the months from the enrolment are due (INPS circ. 14/2026 §2), and the calendar, which knows only the year, cannot tell which ones.
- Amounts come from the INPS Cassetto previdenziale (fixed instalments, codeline). Above the minimale they follow the income: see the tax estimate.
- PXX is the 26.07% rate, P10 the 24% rate for pensioners and people insured elsewhere. ISA subjects and forfettari: whether the 2026 extension to 20 July (DL 89/2026 art. 6) also covers contributions is not confirmed by INPS, so 30 June is shown.
- From 2027 the same dates are assumed and flagged (`needs_review`): the payment rules move to D.Lgs. 33/2025, and the 35% regime's commi of L. 190/2014 are repealed by D.Lgs. 117/2026.

### Automatic preparation [#automatic-preparation]

On by default (`auto_prepare: true` in the tax settings): every morning getbeel prepares the F24 of stamp duty (bollo), withholdings (ritenute) and periodic VAT whose due date is within `auto_prepare_days` days (default 5), once the period is over and the amount is known. It is the same as pressing **Prepare** (the same checks and the same `filing.ready` webhook), plus an in-app notice. You check the F24 and pay it, and you can still recompute it, prepare it by hand or upload the receipt. LIPE and the annual VAT return need a signer and your answers, so they are never prepared automatically; neither are deadlines marked `needs_review`, nor the December VAT of monthly payers until the acconto IVA is saved in its liquidazione. VAT is prepared with the liquidazione's saved inputs (credits carried, acconto). Switch it off with `PATCH /companies/me/tax-settings` and `{"auto_prepare": false}` (or in **Taxes → Settings**, or with the MCP tool `update_tax_settings`): you then only get reminders.

## In your calendar (.ics) [#in-your-calendar-ics]

In the app, **Taxes → Add to calendar** shows a private address to add to Google Calendar, Outlook or Apple Calendar:

```
https://www.getbeel.com/api/v1/companies/me/tax-calendar.ics?token=…
```

The token replaces the API key (calendar apps cannot send headers). Anyone with the address sees the deadlines: if you shared it by mistake, regenerate it in the app and the old one stops working.

## VAT position (estimate) [#vat-position-estimate]

```bash
curl "https://www.getbeel.com/api/v1/companies/me/vat-position?period=2026-Q3" \
  -H "Authorization: Bearer $GETBEEL_API_KEY"
```

`period` is a month (`2026-10`) or a quarter (`2026-Q3`).

- `sales_vat`: VAT on the issued invoices SDI accepted in the period. Credit notes subtract; split payment is left out (`split_payment_invoices`); deferred VAT is apart (`deferred_sales_vat`).
- `purchase_vat_estimate`: VAT on the reviewed supplier invoices, in euros.
- `balance_estimate`: positive to pay, negative in credit.

<Callout title="It is an estimate" type="warn">
  `reliable` is always `false`: Getbeel does not know deductibility, the month
  supplier invoices were received or reverse-charge self-invoices. Use it to get
  an idea and check it with your accountant. Getbeel prepares no VAT F24 from
  it.
</Callout>

For the actual settlement, with its F24 and the LIPE, use the [VAT registers and settlements](/en/api/vat-registers).

Profit and loss, cash flow, receivables aging and the ZIP for the accountant: [Reports and export](/en/api/reports).

## OSS return (draft) [#oss-return-draft]

For a company registered in the OSS union scheme (tax settings `oss_from` / `oss_until`), the draft of the quarterly return, to enter in the Agenzia delle Entrate's Portale OSS:

```bash
curl "https://www.getbeel.com/api/v1/companies/me/oss-return?period=2026-Q3" \
  -H "Authorization: Bearer $GETBEEL_API_KEY"
```

- **What counts:** issued invoices of the quarter to a consumer (no VAT number) in another EU country, lines with Natura N7 ("IVA assolta in altro stato UE").
- **`countries`:** per Member State and rate, the taxable amount and the VAT at that country's standard rate on the invoice date (European Commission TEDB). VAT is computed per line, rounded to the cent, then added up; `vat_country_level` is the same VAT computed once on the country total, as the portal may do, and `rounding_gap` is true when they differ by more than €0.01.
- **`corrections`:** credit notes (TD04, TD08) on sales of an earlier quarter, as corrections of that quarter (within three years). `balances` per country; a negative balance is refunded by that country (`refunds`), never set against another; `total_due` is never negative.
- **`deadline`:** the last day of the month after the quarter, as the EU rules set it. Getbeel does not move it for weekends or holidays: check for any extension.
- **`reference`:** the payment reference `IT/IT{partita IVA}/Q{n}.{YYYY}`. Payment: from the portal (SEPA direct debit) or by bank transfer to the Banca d'Italia, never with F24 or by offsetting.
- **`nil_return`:** no OSS sales and no corrections: a nil return is still due.
- **`doubtful`:** invoices that need a decision, with the `reason`: `n7_not_eu_consumer`, `italian_vat_to_eu_consumer`, `outside_registration`, `foreign_currency` (it needs the ECB rate of the quarter's last day), `rate_unknown`, `credit_note_unlinked`, `credit_note_before_sale`, `correction_too_old`. They are left out of the totals.

<Callout title="A draft to check" type="warn">
  `reliable` is always `false`: reduced rates and goods are not modelled yet
  (every sale is counted as a service at the standard rate). Getbeel never files
  or pays the return: you do it in the Portale OSS with your own credentials (no
  intermediary is allowed). Free. MCP: `get_oss_return`.
</Callout>

## Webhook [#webhook]

`tax_deadline.upcoming` arrives 7 days and 1 day before each deadline not yet paid, once each, to live endpoints only. `data.object` is the deadline with `reminder_days_before`. See [Webhooks](/en/api/webhooks).

`tax_deadline.insufficient_funds` arrives once per due date, from 5 working days before it, when the F24 payments due that day (including amounts still estimated from the registers) are higher than the balance of every connected EUR bank account, using balances at most 3 days old. Due dates are taken in order and each one's F24s come out of the balance, so two close dates that together exceed it are flagged; bollo of small quarters counts on the day it is really paid (with Q2 or Q3). A new alert goes out when the amount due on that day changes. `data.object` is an `f24_funds_alert` with `due_date`, `amount_due`, `available_balance`, `shortfall`, `deadline_ids` and `bank_account_id`. The team's owners also get an email and an in-app notice. An F24 the bank cannot debit is rejected and paid late (sanctions, art. 13 D.Lgs. 471/1997).
