---
title: "Original invoice of a credit note"
description: "Link a credit note to the invoice it came from, without creating an allocation or moving any balance."
canonical: https://developer.billabex.com/en/guides/credit-note-original-invoice/
lang: en
alternate: https://developer.billabex.com/fr/guides/facture-d-origine-d-un-avoir/
last-updated: 2026-09-30
---

# Original invoice of a credit note

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

Source: https://developer.billabex.com/en/guides/credit-note-original-invoice/
Language: English (en)
French version: https://developer.billabex.com/fr/guides/facture-d-origine-d-un-avoir/

`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:

```http
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:

```http
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:

```json
{ "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.

When a connection moves the credit note or its original invoice to another customer in the same
organization, `originalInvoiceId` is preserved. The link can therefore point to an invoice on
another account after the move, without changing any amount. The same-account rule still applies
when you set or replace the link.

## 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.

---

Billabex developer portal. OpenAPI specification: https://developer.billabex.com/openapi.json.
Agent instructions: https://developer.billabex.com/llms.txt. Complete documentation: https://developer.billabex.com/llms-full.txt.