Correcting Documents with Credit Notes#

Once an invoice is finalized (status: 1), it is locked and cannot be edited or deleted. To correct or reverse a finalized invoice you have two options depending on the situation:

Option 1: Voiding an invoice with Nullify#

If the invoice has not been settled by a receipt and you need to cancel it outright, use invoiceNullify. This marks the invoice as voided (nullified: 1) while keeping it in the system for audit purposes. Stock, commissions, and payment ledger entries are all reverted.

mutation {
  invoiceNullify(
    companyId: 1
    documentId: 1234
    nullifiedReason: "Issued in error, duplicate order"
  ) {
    errors { field msg }
    data {
      documentId
      nullified
      status
      documentAT {
        nullifiedReason
      }
    }
  }
}

{ "field": "nullifiedReason", "msg": "Nullified reason is required" }

{ "field": "*", "msg": "Document is in use as a payment in other document" }

The same pattern applies to other document types: receiptNullify, creditNoteNullify, etc. The mutation name is always {apiCode}Nullify.

Option 2: Issuing a credit note#

A credit note partially or fully offsets a finalized invoice. You create it with creditNoteCreate, linking it to the original invoice via the relatedWith field. relatedWith is required: a credit note without an original document reference is not valid.

Prerequisites#

You need:

1. The original invoice's documentId: returned when the invoice was created
2. The documentProductId of each invoice line you are crediting: query the invoice first to fetch these
3. A document set configured for credit notes (documentTypeId 3): use documentSetsForDocument to find one

To get the invoice product IDs:

query {
  invoice(companyId: 1, documentId: 1234) {
    errors { field msg }
    data {
      documentId
      products {
        documentProductId
        productId
        qty
        price
      }
    }
  }
}

To find a document set for credit notes:

query {
  documentSetsForDocument(companyId: 1, documentTypeId: 3) {
    errors { field msg }
    data {
      documentSetId
      name
      isDefault
    }
  }
}

Full credit (reversing the entire invoice)#

To fully offset an invoice, create a credit note whose relatedWith value matches the invoice's total:

mutation {
  creditNoteCreate(
    companyId: 1
    data: {
      documentSetId: 5
      customerId: 42
      date: "2025-04-01T10:00:00.000Z"
      notes: "Incorrect invoice, full reversal"
      relatedWith: [
        {
          relatedDocumentId: 1234
          value: 99.98
        }
      ]
      products: [
        {
          relatedDocumentId: 1234
          relatedDocumentProductId: 501
          productId: 88
          qty: 2
          ordering: 1
        }
      ]
      status: 1
    }
  ) {
    errors { field msg }
    data {
      documentId
      number
      totalValue
      nullified
    }
  }
}

The products array mirrors the lines from the original invoice that are being credited. Each product item must include relatedDocumentId (the original invoice's documentId) and relatedDocumentProductId (the documentProductId from the original invoice's product line). The quantities should reflect what you are reversing.

Partial credit#

To credit only part of an invoice (for example, one line or a quantity adjustment), set relatedWith[].value to the amount being credited and include only the relevant product lines:

mutation {
  creditNoteCreate(
    companyId: 1
    data: {
      documentSetId: 5
      customerId: 42
      date: "2025-04-01T10:00:00.000Z"
      notes: "Return of 1 unit, quantity error"
      relatedWith: [
        {
          relatedDocumentId: 1234
          value: 49.99
        }
      ]
      products: [
        {
          relatedDocumentId: 1234
          relatedDocumentProductId: 501
          productId: 88
          qty: 1
          ordering: 1
        }
      ]
      status: 1
    }
  ) {
    errors { field msg }
    data {
      documentId
      number
      totalValue
    }
  }
}

The value in relatedWith should equal the totalValue of the credit note. The original invoice remains open for the remaining balance.

Eligible source documents#

A credit note can reference the following source document types:

See Document Types for the full list of IDs and API codes.

Querying credit notes#

Use the creditNote (single) and creditNotes (list) queries, which follow the same pattern as all other document type queries:

query {
  creditNotes(companyId: 1, options: {
    pagination: { page: 1, qty: 20 }
    order: { field: date, sort: DESC }
  }) {
    data {
      documentId
      number
      date
      totalValue
      status
      nullified
      entityName
      relatedWith {
        relatedDocumentId
        value
      }
    }
    options {
      pagination { page qty count }
    }
  }
}

Voiding a credit note#

If a finalized credit note needs to be cancelled (for example, it was issued incorrectly), use creditNoteNullify:

mutation {
  creditNoteNullify(
    companyId: 1
    documentId: 9876
    nullifiedReason: "Credit note issued against wrong invoice"
  ) {
    errors { field msg }
    data {
      documentId
      nullified
      documentAT {
        nullifiedReason
      }
    }
  }
}

The nullifiedReason is required for Portuguese companies on credit notes, for the same reason as invoices.

Decision flowchart#

Next steps#

• Document Types: Find the credit note document type ID and API codes
• Creating an Invoice: The invoice being corrected
• Paying an Invoice: Understand how receipts relate to invoices before nullifying
• Downloading a Document PDF: Download the credit note PDF with creditNoteGetPDF / creditNoteGetPDFToken
• See creditNoteCreate and CreditNoteInsert for all fields