Draft of the quarterly OSS return
For a company registered in the OSS union scheme: per Member State of the consumer, the taxable amount and the VAT of the quarter from the issued invoices with Natura N7 to EU consumers, at each State's standard rate on the invoice date (VAT rounded per line, then added up; vat_country_level shows the per-country computation, rounding_gap when they differ by more than €0.01). Credit notes on earlier quarters are corrections; a State's negative balance is refunded, never offset. doubtful lists the invoices that need a decision (reason). deadline is the nominal date, never moved; reference is the payment reference. Free and read-only: the return is entered and paid in the AdE Portale OSS with the company's own credentials, never with F24. reliable is always false (reduced rates and goods are not modelled).
For a company registered in the OSS union scheme: per Member State of the consumer, the taxable amount and the VAT of the quarter from the issued invoices with Natura N7 to EU consumers, at each State's standard rate on the invoice date (VAT rounded per line, then added up; vat_country_level shows the per-country computation, rounding_gap when they differ by more than €0.01). Credit notes on earlier quarters are corrections; a State's negative balance is refunded, never offset. doubtful lists the invoices that need a decision (reason). deadline is the nominal date, never moved; reference is the payment reference. Free and read-only: the return is entered and paid in the AdE Portale OSS with the company's own credentials, never with F24. reliable is always false (reduced rates and goods are not modelled).
apiKeyAuthorizationBearer <token>API key: gb_test_… or gb_live_…
period*stringA quarter (2026-Q3): the OSS return is quarterly
^\d{4}-Q[1-4]$OK
application/json- response
object*stringperiod*stringregistered*booleanRegistered in the OSS union scheme (tax settings oss_from / oss_until) for some day of the quarter
registration*deadline*stringLast day of the month after the quarter. Not moved for weekends or holidays: verify any extension (proroga)
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$datereference*|The payment reference IT/IT{partita IVA}/Q{n}.{YYYY} (null without a valid partita IVA)
currency*stringcountries*array<>corrections*array<>balances*array<>total_due*stringVAT to pay: positive balances only; a State's negative balance is refunded by that State
^-?\d+\.\d{2}$refunds*array<>nil_return*booleanNothing to declare: a nil return is still due
doubtful*array<>reliable*booleancurl -X GET 'https://www.getbeel.com/api/v1/companies/me/oss-return?period=string'{ "object": "oss_return_draft", "period": "2026-Q3", "registered": true, "registration": { "from": "2026-10-29", "until": "2026-10-29" }, "deadline": "2026-10-29", "reference": "IT/IT01234567897/Q3.2026", "currency": "EUR", "countries": [ { "country": "string", "rate": 0, "supply": "services", "taxable": "122.00", "vat": "122.00", "vat_country_level": "122.00", "rounding_gap": true, "invoices": -9007199254740991 } ], "corrections": [ { "period": "string", "country": "string", "vat": "122.00" } ], "balances": [ { "country": "string", "vat": "122.00" } ], "total_due": "122.00", "refunds": [ { "country": "string", "vat": "122.00" } ], "nil_return": true, "doubtful": [ { "invoice_id": "string", "number": "string", "date": "2026-10-29", "reason": "n7_not_eu_consumer", "country": "string" } ], "reliable": false}VAT for a month or quarter (estimate) GET
Sales VAT from the issued e-invoices accepted by SDI (credit notes subtract, split payment left out, deferred VAT apart) and an estimate of purchase VAT from reviewed supplier invoices in euros. reliable is always false: deductibility, the month of receipt and reverse charge are not known, so treat it as an estimate to check with the accountant ("da verificare"). It is never used for an F24.
VAT registers of a month or quarter GET
Registro IVA vendite and acquisti, row by row with the amounts per rate and natura: issued e-invoices accepted by SDI (credit notes subtract; split payment recorded but not due; deferred VAT counted when paid or after a year), supplier invoices as soon as the AI has read them, those not reviewed yet flagged unreviewed (by the period of receipt; foreign VAT never counts) and autofatture TD16–TD19/TD28 on both sides (reverse charge). vat_counted is what enters the liquidazione after the user's exclusions and adjustments (made in the app, with a reason). missing lists the documents of the period not in the registers yet. Always to check ("da verificare").