Skip to main content

VAT basis required on every new order

2026-11-14 · Breaking change · Upcoming: not yet in production

A new order without pricesIncludeVat is rejected with 422 https://orderex.io/problems/vat-required and errors["pricesIncludeVat"]; absent and null are both missing, and with lines without a rate one 422 names them all.

What changed

  • true means unitPrice and the line totals include VAT, false that they exclude it; subTotal, totalDiscount and totalAmount are still the sums of the lines, unchanged by VAT.
  • GET /api/v1/orders/{id} returns pricesIncludeVat, which is null for an order created before this change: its basis is unknown, so its lines show null VAT amounts, also when a VAT amount was stored, and a line added to it later gets its rate but no amounts.
  • The checks run in this order: 400 for a body that does not bind or does not validate, 422 unsupported-currency, then 422 vat-required and 422 invalid-amount, then 409 order-already-exists.
  • With an Idempotency-Key the key is looked up before the 422s, so a create that got 201 before this change replays when the same body is sent again within 7 days. The same key with the new fields added is another body and gets 409 https://orderex.io/problems/idempotency-key-reused; a create that got 422 vat-required can be retried with its key once the fields are added.

Affected operations

  • POST /api/v1/orders
  • GET /api/v1/orders/{id}, which returns pricesIncludeVat

What you do

  • Send pricesIncludeVat on every new order.

How breaking changes are announced and how long a deprecated endpoint stays: see the versioning policy.