Data Management3 min

Original invoice of a credit note

Link a credit note to the invoice it came from, without creating an allocation or moving any balance.

originalInvoiceId names the invoice a credit note came from. It represents no allocated amount: adding, replacing or removing this link creates no allocation and changes neither a balance nor a payment status. Creating the credit note keeps its usual financial behaviour.

Create and complete a credit note

POST /api/public/v1/credit-notes accepts the optional multipart field originalInvoiceId: send the UUID of the invoice in Billabex, not its GEXTIA reference. A field that is omitted, empty, or holds the text null creates the credit note without a link.

If the invoice arrives later, find it by its source identifier:

GET /api/public/v1/invoices?organizationId=<organizationId>&filters=sourceId:is:<sourceId>

URL-encode the query parameter values. Then send the UUID you obtained, with the credit-notes:all scope:

PUT /api/public/v1/credit-notes/{creditNoteId}/original-invoice
Content-Type: application/json

{ "originalInvoiceId": "123e4567-e89b-42d3-a456-426614174000" }

The same endpoint replaces an existing link. To remove it:

{ "originalInvoiceId": null }

The PUT requires the field, even to remove the link. Unknown fields are rejected. The 200 response carries the updated credit note, originalInvoiceId included. The field is also present in lists and in details, holding null when there is no link. Sending the value it already has emits no extra event. Integrations that never send this field keep working as before.

Validation and deletion

The invoice must exist in the same organization, on the same customer account, and in the same currency. An invalid or incompatible reference returns 400:

  • app-invoicing.credit-note.original-invoice-invalid: invalid UUID, or invoice unavailable.
  • app-invoicing.credit-note.original-invoice-account-mismatch: different account.
  • app-invoicing.credit-note.original-invoice-currency-mismatch: different currency.

A credit note that does not exist returns 404. Write permissions are still required. The documentary link stays editable when readOnlyReason reports a synchronized credit note; the restrictions on its amounts and on its deletion still apply.

If the invoice is deleted, its UUID stays on the credit note as a documentary trace. The credit note is not deleted and its link stays correctable. Sending that retained reference again has no effect; trying to set it on another credit note is refused. Cleaning up existing financial allocations when an invoice is deleted stays independent of this reference.

MCP and webapp

MCP accepts originalInvoiceId in create-credit-note and offers set-credit-note-original-invoice, with the mcp:write scope. get-credit-note and list-credit-notes return the reference. The webapp lets you pick it at creation and from the credit note detail.

For GEXTIA, keep reversed_entry in the ETL until the Billabex invoice exists. Do not create a /credit-allocations entry from this reference alone: an allocation requires an amount actually applied, which the synchronized balances may already account for.