# OSS / IOSS return

Source: https://veriport.io/docs/oss-return (published 2026-10-24)

OSS return validator (lines only; dispatch-country breakdown not implemented): the output is the set of return lines per member state of consumption, supply type and rate, checked against the rates table, not a filable return. Implementing Regulation (EU) 2020/194 Annex III also requires goods to be split by member state of dispatch or fixed establishment; the row model carries no dispatch country, so a seller shipping from stock in several member states cannot file from this output (assessment 2026-10-28). Send the quarter's (OSS) or month's (IOSS) B2C sales as JSON rows or as a CSV export (`Content-Type: text/csv`, header row in English, French or German; or JSON `{period, scheme, csv}`). Each row names the member state of consumption, the rate (or a rates-table category), the net amount, optionally the VAT amount, the supply date and the supply type. The service aggregates per member state, supply type and rate; validates every row against the dated rates table (the rate must be one the member state applies; a rate changed inside the table's window is accepted with a warning when the supply predates the change), reconciles VAT with net × rate, checks the dates against the period, and nets credit notes; rows marked `correctionOfPeriod` become the corrections section. Returns the per-country summary and the upload file. On 2026-10-24 no national portal format could be fetched (the BZSt publishes its CSV record layout only inside the logged-in form; the DGFiP publishes none), so the file is a clearly labelled generic CSV and `portals[]` says so per member state. Up to 50000 rows or 4.5 MB. Add `?output=csv` to receive the file itself instead of JSON. Send an `Idempotency-Key` header (1–128 characters, unique per request) and a retry after a dropped response replays the stored answer for 24 hours without a second charge (`Idempotent-Replayed: true`); the same key with a different body or query is refused with 409 `idempotency_conflict`.

## POST https://veriport.io/api/v1/vat/oss/return

OSS return validator (lines only; dispatch-country breakdown not implemented): the output is the set of return lines per member state of consumption, supply type and rate, checked against the rates table, not a filable return. Implementing Regulation (EU) 2020/194 Annex III also requires goods to be split by member state of dispatch or fixed establishment; the row model carries no dispatch country, so a seller shipping from stock in several member states cannot file from this output (assessment 2026-10-28). Send the quarter's (OSS) or month's (IOSS) B2C sales as JSON rows or as a CSV export (`Content-Type: text/csv`, header row in English, French or German; or JSON `{period, scheme, csv}`). Each row names the member state of consumption, the rate (or a rates-table category), the net amount, optionally the VAT amount, the supply date and the supply type. The service aggregates per member state, supply type and rate; validates every row against the dated rates table (the rate must be one the member state applies; a rate changed inside the table's window is accepted with a warning when the supply predates the change), reconciles VAT with net × rate, checks the dates against the period, and nets credit notes; rows marked `correctionOfPeriod` become the corrections section. Returns the per-country summary and the upload file. On 2026-10-24 no national portal format could be fetched (the BZSt publishes its CSV record layout only inside the logged-in form; the DGFiP publishes none), so the file is a clearly labelled generic CSV and `portals[]` says so per member state. Up to 50000 rows or 4.5 MB. Add `?output=csv` to receive the file itself instead of JSON. Send an `Idempotency-Key` header (1–128 characters, unique per request) and a retry after a dropped response replays the stored answer for 24 hours without a second charge (`Idempotent-Replayed: true`); the same key with a different body or query is refused with 409 `idempotency_conflict`.

Tiers: free, credits, plan. Cost: 25 calls per accepted return (0 when the rows are refused with 422; 0 on an Idempotency-Key replay).

- `output` (query): `json` (default): summary, files and portal notes. `csv`: the generic CSV file alone, with `Content-Disposition`.
- `Idempotency-Key` (header): Unique per request (a UUID will do; `^[A-Za-z0-9_.:-]{1,128}$`). A retry with the same key, query and body replays the stored answer for 24 hours (`Idempotent-Replayed: true`) instead of building and charging a second return; another body under the same key is 409.

Example 200:

```json
{
  "scheme": "union",
  "period": {
    "label": "2026-Q3",
    "kind": "quarter",
    "start": "2026-07-01",
    "end": "2026-09-30",
    "dueDate": "2026-10-31"
  },
  "currency": "EUR",
  "lines": [
    {
      "country": "DE",
      "countryName": "Germany",
      "supplyType": "goods",
      "rateKind": "standard",
      "rate": 19,
      "rows": 1,
      "net": 1250,
      "vat": 237.5,
      "vatComputed": 237.5
    },
    {
      "country": "DE",
      "countryName": "Germany",
      "supplyType": "goods",
      "rateKind": "reduced",
      "rate": 7,
      "rows": 1,
      "net": 310,
      "vat": 21.7,
      "vatComputed": 21.7
    },
    {
      "country": "FR",
      "countryName": "France",
      "supplyType": "services",
      "rateKind": "standard",
      "rate": 20,
      "rows": 1,
      "net": 980,
      "vat": 196,
      "vatComputed": 196
    }
  ],
  "corrections": [
    {
      "period": "2026-Q2",
      "country": "IT",
      "countryName": "Italy",
      "rows": 1,
      "vat": -9.9,
      "net": -45
    }
  ],
  "totals": {
    "rows": 4,
    "countries": 2,
    "net": 2540,
    "vat": 455.2,
    "correctionsVat": -9.9,
    "vatPayable": 445.3
  },
  "byCountry": [
    {
      "country": "DE",
      "countryName": "Germany",
      "net": 1560,
      "vat": 259.2
    },
    {
      "country": "FR",
      "countryName": "France",
      "net": 980,
      "vat": 196
    }
  ],
  "rates": {
    "verifiedOn": "2026-10-24"
  },
  "warnings": [],
  "files": [
    {
      "id": "generic_csv",
      "filename": "oss-return-union-2026-Q3-generic.csv",
      "contentType": "text/csv; charset=utf-8",
      "portal": null,
      "content": "period,scheme,member_state,member_state_name,supply_type,rate_kind,rate_percent,taxable_amount_eur,vat_amount_eur,rows,correction_of_period\r\n2026-Q3,union,DE,Germany,goods,standard,19,1250.00,237.50,1,\r\n…"
    }
  ],
  "portals": [
    {
      "memberState": "FR",
      "portal": "impots.gouv.fr — guichet unique TVA (espace professionnel)",
      "status": "generic",
      "note": "No public file-import specification was found; key the lines in."
    },
    {
      "memberState": "DE",
      "portal": "BZStOnline-Portal (Mein BOP)",
      "status": "generic",
      "note": "CSV import exists; its record layout is published only inside the logged-in form."
    }
  ]
}
```