Skip to main content

API breaking changes

This page lists the v1 API changes that break an integration already in place: a renamed key, a removed key, a call now refused. Entries are dated and ordered from the most recent to the oldest.

If your integration stopped working without anything changing on your side, start here, then go back to the page of the resource concerned.

30 September 2026: a handover Scribee refuses before anything is sent answers 422, no longer 202​

What changes​

On POST /api/v1/payment_batches/{id}/submit, when Scribee cannot build the request to the payment provider on its side, the call used to answer a 202 carrying a failed batch. It now answers a 422 validation_failed, exactly like the refusal of a batch the channel cannot express as it stands: details.instructions carries the refusal message, nothing was sent to the provider, and the Idempotency-Key is not consumed. The batch still moves to failed, with submission_refused_by at local.

Two additions come with this change, removing nothing:

  • the batch publishes submission_refused_by: provider, local or null;
  • an instruction of a failed batch that carries no status from the bank publishes submission_failed, no longer submitted, and payment_instruction.updated announces that move.

The resources concerned​

  • POST /api/v1/payment_batches/{id}/submit and GET /api/v1/payment_batches/{id} (Payment batches).
  • GET /api/v1/payment_batches/{id}/instructions, its status filter, and GET /api/v1/payment_instructions/{id} (The status of an instruction).
  • The payment_instruction.updated event (Webhooks).

What you have to do​

  1. Treat a 422 on submit as a refusal that may have changed the batch: re-read it, and read submission_refused_by when it is failed.
  2. Accept submission_failed in the instructions' status and in the events. It is not a bank outcome: it neither confirms nor rules out a rejection or an execution at the bank, and the refusal reason is read in the batch's error_message.

How to recognise the symptom​

  • A submit that answered 202 with a failed batch now answers 422 validation_failed.
  • Instructions of a failed batch that you read as submitted now read submission_failed.

22 September 2026: amount_with_taxes becomes amount_without_taxes​

What changes​

In every tax_subtotals entry, the breakdown by VAT rate, the amount_with_taxes key is now called amount_without_taxes. The change covers reads as well as writes, with no alias and no compatibility period: the old name is no longer accepted on input and no longer appears in any response.

{
  "tax_subtotals": [
    {
      "tax_category_id": "S",
      "vat_rate": 20.0,
      "amount_without_taxes": 1000.0,
      "vat_amount": 200.0,
      "currency_code": "EUR"
    }
  ]
}

The value itself does not change: it is still the taxable base excluding tax for the rate concerned, BT-116 in EN 16931. Only its name changes.

The resources concerned​

  • Invoices, on write as well as on read: POST /api/v1/workspaces/{workspace_id}/invoices, PATCH /api/v1/invoices/{id}, and GET /api/v1/invoices/{id} (Issue a sales invoice).
  • Quotes, read-only: GET /api/v1/quotes/{id} with include=tax_subtotals. The quote endpoints have never accepted a breakdown on write (Quotes).
  • E-reporting invoices, on write as well as on read: POST /api/v1/e_reportings/{e_reporting_id}/invoices, PATCH /api/v1/e_reportings/invoices/{id}, and GET /api/v1/e_reportings/invoices/{id}.
  • E-reporting transactions, on write as well as on read: POST /api/v1/e_reportings/{e_reporting_id}/transactions, PATCH /api/v1/e_reportings/transactions/{id}, and GET /api/v1/e_reportings/transactions/{id} (Declare transactions).
  • E-reporting collections, read-only: GET /api/v1/e_reportings/payments/{id}. The field is returned there under its new name, and stays always null - a collection carries the collected amount alone (Declare collections).

Why this rename​

The old name asserted the opposite of what the field carries. amount_with_taxes reads as a tax-inclusive amount, whereas the expected value is the taxable base excluding tax for the rate. Integrations filled the field with the tax-inclusive amount, in good faith, and their invoices were refused much later, at deposit. The name is therefore corrected rather than kept.

What you have to do​

  1. Rename the key in the payloads you send: amount_with_taxes becomes amount_without_taxes.
  2. Rename it in the code that reads our responses. The old key is absent from the JSON, not present as null: an access that does not test for presence will return an empty value rather than an error.
  3. Check the value you put in it. It must be the taxable base excluding tax for the rate, never the tax-inclusive amount.

How to recognise the symptom​

  • An invoice creation or modification that worked yesterday now answers 422: the payload still sends amount_with_taxes, that unknown key is ignored, and the subtotal ends up without the taxable base excluding tax that Scribee requires.
  • Your response readers find the breakdown empty or at zero: they are still looking for amount_with_taxes in an object that exposes amount_without_taxes.