Credit Notes Guide

Document nature (business): Credit Note (NC)

Illustrative IDs

The values in the JSON examples (e.g. "documentTypeId": 7) are illustrations; the same number can represent a different document type in another client's database. Resolve the correct id with GET /gateway/document-type and match description / keyId to a credit note in the client's database. See Resolving document type IDs.

Credit notes are issued with the same endpoint as any sales document:

POST /gateway/invoice/invoices
Content-Type: application/json
Authorization: Bearer {token}
X-Timezone: Europe/Lisbon

Set documentTypeId to the credit-note type for credit notes (invoiceType NC).

Overview

A credit note (NC) reverses or corrects a previously issued invoice. Typical uses:

Full or partial product returns
Price or billing error correction
Post-sale discounts or commercial adjustments
Invoice cancellation (with or without physical return)

Issuance rules (NC)

Rule	Detail
Endpoint	`POST /gateway/invoice/invoices` with NC `documentTypeId`
`emissionReason`	Required for Portugal and Angola (max 50 characters)
Line quantities	Always positive — the document type defines credit semantics
`quantity`	Required and must be greater than zero
Stock movement	Handled by the NC document type configuration
`payments[]`	Required at header level together with `currencyId`
Origin linkage	Per-line `originBodyGuid` + `relationType` to identify the origin line
Same customer	NC must be issued to the same customer as the origin document
Art. 78 CIVA (PT)	Legal observation text is auto-appended to `obs` when references are valid

Quantities are positive

Use positive quantity on NC lines. The credited amount is always a positive value.

Step-by-step workflow

Step 1 — Get the original invoice

Retrieve the invoice you want to credit. Pass referencedQuantitiesRelationType=1 to receive, on each line, the quantity already credited by previous credit notes:

GET /gateway/invoice/invoices/{documentTypeId}/{serieId}/{number}/flat?referencedQuantitiesRelationType=1
Authorization: Bearer {token}

From the response, collect the fields below for each line you want to credit:

Field	Location	Used as
`documentBodies[].guid`	Each line	`originBodyGuid` on the NC line
`documentBodies[].quantity`	Each line	Original quantity on the invoice line
`documentBodies[].referencedQuantity`	Each line	Quantity already credited (`null` = none yet)

Remaining creditable quantity per line = quantity − (referencedQuantity ?? 0)

Example response (invoice FAC 1/5, documentTypeId=7, serieId=3, number=123):

{
  "id": 1001,
  "documentNumber": "FAC 1/5",
  "entityVat": "123456789",
  "documentBodies": [
    {
      "guid": "660e8400-e29b-41d4-a716-446655440001",
      "itemKeyId": "PROD001",
      "quantity": 2,
      "retailPrice": 50,
      "netPrice": 40.65,
      "taxId": 1,
      "totalAmount": 100,
      "totalNetAmount": 81.30,
      "referencedQuantity": 1
    },
    {
      "guid": "660e8400-e29b-41d4-a716-446655440002",
      "itemKeyId": "PROD002",
      "quantity": 1,
      "retailPrice": 30,
      "netPrice": 24.39,
      "taxId": 1,
      "totalAmount": 30,
      "totalNetAmount": 24.39,
      "referencedQuantity": null
    }
  ]
}

PROD001 has 1 of 2 units already credited — only 1 unit remains. PROD002 has not been credited yet.

Step 2 — Create the credit note

Build the NC payload:

Set NC documentTypeId and serieId.
Use the same customer (entityKeyId) as the original invoice.
Set emissionReason (PT/AO — max 50 chars).
Set currencyId and payments[] (sum must match the NC total).
On each credited line, set originBodyGuid and relationType together.
Use positive quantity.

Per-line reference fields (both required together, or omit both):

Field	Value
`originBodyGuid`	Line `guid` of the original invoice line
`relationType`	`1` (`ReferenceOrigin`)

Derived fields on referenced lines

When a line carries originBodyGuid + relationType, the following fields are optional — the API derives them from the origin line when omitted:

Field	Behaviour when omitted	Behaviour when supplied
`itemKeyId`	Derived from origin	Must match origin (→ `DocumentReference.ItemMismatch` if different)
`taxId`	Derived from origin	Accepted — tax may differ from origin
`retailPrice`	Derived as `originTotalAmount / originQuantity`	Accepted; locked to origin on Angolan sales (→ `DocumentReference.PriceMismatch` if different)
`netPrice`	Derived as `originTotalNetAmount / originQuantity`	Accepted; locked to origin on Angolan sales (→ `DocumentReference.PriceMismatch` if different)
`discountPercentage`	Defaults to zero	Accepted

Angola — always omit prices on referenced lines

In Angola, the unit prices on referenced lines must reflect the origin. The API enforces this: if retailPrice or netPrice is supplied, it must match totalAmount / quantity exactly — not the retailPrice field returned by GET /flat.

retailPrice in GET /flat is the stored unit price on the line; totalAmount / quantity is the effective charged price and may differ for various reasons (e.g. line discounts). Supplying the raw retailPrice when it diverges from totalAmount / quantity will cause DocumentReference.PriceMismatch.

Always omit retailPrice and netPrice on Angolan NC/ND lines. The API derives the correct fiscal value from the origin totals automatically.

If you cannot omit prices due to a technical constraint (e.g. a legacy integration that always populates all fields), supply:

retailPrice = totalAmount / quantity
netPrice = totalNetAmount / quantity

Full return (with line references)

Customer returns the entire purchase — both invoice lines referenced in full.

{
  "serieId": 3,
  "documentTypeId": 7,
  "entityVat": "123456789",
  "entityDescription": "Example Client, Ltd",
  "currencyId": 1,
  "emissionReason": "Full return - defective goods",
  "obs": "Return of invoice FAC 1/5",
  "payments": [
    {
      "paymentTypeId": 1,
      "amount": 153
    }
  ],
  "documentBodies": [
    {
      "quantity": 2,
      "originBodyGuid": "660e8400-e29b-41d4-a716-446655440001",
      "relationType": 1
    },
    {
      "quantity": 1,
      "originBodyGuid": "660e8400-e29b-41d4-a716-446655440002",
      "relationType": 1
    }
  ]
}

Item, tax, and prices are derived automatically from each origin line. You may override them following the rules in the table above.

Art. 78 CIVA (Portugal)

When valid per-line references are present, the following legal text is automatically added to obs:

Pursuant to No. 5 of article 78 of the CIVA, we would like to thank you for returning the duplicate of this Credit Note, duly stamped and signed.

Do not duplicate this text manually.

Partial return

Customer returns only part of the purchase — reference one line with a quantity lower than the original.

{
  "serieId": 3,
  "documentTypeId": 7,
  "entityVat": "123456789",
  "currencyId": 1,
  "emissionReason": "Partial return - 1 of 2 units",
  "obs": "Partial return on invoice FAC 1/5",
  "payments": [
    {
      "paymentTypeId": 1,
      "amount": 61.5
    }
  ],
  "documentBodies": [
    {
      "quantity": 1,
      "originBodyGuid": "660e8400-e29b-41d4-a716-446655440001",
      "relationType": 1
    }
  ]
}

quantity (1.0) must not exceed the remaining unreferenced quantity on origin line 660e8400-…440001 (originally 2.0, minus any prior NCs).

Value correction (no stock movement)

Use when correcting a billing error or granting a post-sale discount without a physical return. Reference the affected invoice line(s) and supply explicit prices reflecting the corrected value.

{
  "serieId": 3,
  "documentTypeId": 7,
  "entityVat": "123456789",
  "currencyId": 1,
  "emissionReason": "Price correction - billing error",
  "obs": "Correction on invoice FAC 1/5",
  "payments": [
    {
      "paymentTypeId": 1,
      "amount": 10
    }
  ],
  "documentBodies": [
    {
      "quantity": 1,
      "retailPrice": 10,
      "netPrice": 8.13,
      "originBodyGuid": "660e8400-e29b-41d4-a716-446655440001",
      "relationType": 1
    }
  ]
}

Stock behaviour is determined by the NC document type configuration.

Common errors

Error code	Cause	Resolution
`SaleDocumentRules.NCND.MissingReferences`	No per-line refs (in-app origin) (PT/AO)	Use per-line GUID refs for Soba invoices
`SaleDocumentRules.NCND.MissingEmissionReason`	`emissionReason` empty (PT/AO)	Set `emissionReason` (max 50 characters)
`DocumentReference.OriginBodyNotFound`	`originBodyGuid` does not exist or has been deleted	Verify GUIDs from `GET /gateway/invoice/invoices/{id}`
`DocumentReference.BalanceExceeded`	`quantity` + already-referenced qty > origin line qty	Reduce `quantity` or check prior NCs on the same line
`DocumentReference.ItemMismatch`	Supplied `itemKeyId` does not match the origin line's item	Omit `itemKeyId` or send the same item as the origin
`DocumentReference.PriceMismatch`	Supplied price differs from origin-derived price on an Angolan rectifying document	For Angola, always omit `retailPrice`/`netPrice` — the API derives prices from the origin totals. If supplied, values must equal `totalAmount / quantity` and `totalNetAmount / quantity`, not the raw unit prices from GET /flat
`DocumentReference.EntityMismatch`	Customer on the NC differs from the customer of the origin document	Use the same `entityKeyId` as the origin invoice
`Payment.InsufficientValue`	Sum of `payments[].amount` ≠ NC total	Recalculate total and adjust payment amounts

Validation also rejects incomplete reference pairs — originBodyGuid and relationType must both be present together or both omitted.

Usage Guide — Header/line fields, payments, and error handling
Invoices Guide — Issuing the original sales invoice
Receipts Guide — Refund and treasury flows

Last Updated: July 7, 2026

Overview​

Issuance rules (NC)​

Step-by-step workflow​

Step 1 — Get the original invoice​

Step 2 — Create the credit note​

Derived fields on referenced lines​

Full return (with line references)​

Partial return​

Value correction (no stock movement)​

Common errors​

Related guides​