Skip to main content

VAT rate required on every new order line

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

A new order line without vatRate is rejected with 422 https://orderex.io/problems/vat-required.

What changed

  • Every line of POST /api/v1/orders and the body of POST /api/v1/orders/{id}/lines carry vatRate, the VAT rate in percent from 0 to 100 with at most 2 decimals; 0 is a line without VAT. Absent and null are both missing.
  • The 422 names each missing field in errors, keyed as in the body: errors["lines[1].vatRate"] for the second line of a create, errors["vatRate"] for an added line.
  • A rate below 0, above 100 or with more decimals is a 400 validation problem with the validator's own keys, errors["Lines[0].VatRate"] and errors["VatRate"]: only the 422 keys are camelCase.
  • Changing an existing line's quantities, status or metadata needs no rate.
  • OrderEx then returns the line's pricing.lineTotalExcludingVat, pricing.vatAmount and pricing.lineTotalIncludingVat, computed once on the line total after discount (not per unit) and rounded once to a whole minor unit away from zero; shipping and fees are lines with their own rate.
  • A line created before this change without a rate has pricing.vatRateMissing true and the three amounts null; no rate or amount is guessed.

Affected operations

  • POST /api/v1/orders
  • POST /api/v1/orders/{id}/lines
  • GET /api/v1/orders/{id}, which returns the pricing of each line

What you do

  • Send vatRate on every new line, and 0 for a line without VAT, such as a gift card.

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