Skip to main content
Download OpenAPI

Credit Notes

Credit notes follow the same rules as invoices under the French e-invoicing mandate: the same 5-corner model, the same AFNOR lifecycle statuses, and the same transmission logic over the Peppol network. If you've already integrated invoice sending and receiving, this module will feel familiar, the differences are limited to the resource name (/credit-notes instead of /invoices) and a couple of endpoint-level details called out below.

Sending a credit note (outbound)​

To send a credit note, forward the structured file content to A-Cube. The platform validates the payload synchronously and responds immediately with a unique identifier (uuid), which you should store to retrieve the document's layout, details, and processing state going forward.

  • Submit an Outbound Credit Note: POST /credit-notes
  • Fetch Credit Note Details: GET /credit-notes/{uuid}

A-Cube accepts UBL or CII XML documents; the syntax is detected automatically from the payload. Support for Factur-X will be added in the near future.

If the credit note relates to an invoice you previously sent through A-Cube, pass the X-Referenced-Invoice-Uuid header with the invoice's uuid to link the two documents.

POST /credit-notes
X-Referenced-Invoice-Uuid: 019ea760-dad8-70b9-9b23-f60ff4004509

Sample Submission Response (201 Created)​

{
  "uuid": "{uuid of the credit note}",
  "direction": "OUTBOUND",
  "status": "SUBMITTED",
  "invoiceTypeCode": "381",
  "invoiceNumber": "A202500001",
  "invoiceDate": "2025-02-01",
  "party": {
    "name": "LE VENDEUR",
    "siren": "324730001",
    "siret": null,
    "identifierScheme": "0225",
    "identifierValue": "324730001"
  },
  "counterparty": {
    "name": "LE CLIENT",
    "siren": "931536429",
    "siret": null,
    "identifierScheme": "0225",
    "identifierValue": "931536429"
  },
  "createdAt": "2026-06-17T07:40:15+00:00",
  "updatedAt": "2026-06-17T07:40:15+00:00"
}

Validation​

The same validation logic applies when submitting a credit note: A-Cube checks the payload against the XML schema and the applicable Schematron rules before accepting it. If the document fails either check, the submission response includes the validation errors immediately, so you can fix and resend the credit note without waiting for downstream processing.

Sample Lifecycle Webhook Payload​

Outbound processing-stage and AFNOR status updates for credit notes are delivered under dedicated event types, credit_note.outbound and credit_note.status, so that they never get mixed up with invoice events on the same webhook endpoint.

{
  "eventId": "019ea765-da8a-70af-a037-b068ad1ff1ce",
  "eventType": "credit_note.status",
  "status": "205",
  "invoiceUuid": "019ea760-dad8-70b9-9b23-f60ff4004509",
  "direction": "OUTBOUND",
  "statusLabel": "{description of the new status}"
}

Configure your webhook handlers to catch these states automatically, exactly as you would for invoices, so your UI can reflect approval, dispute, or settlement without polling the API.

Receiving a credit note (inbound)​

When a supplier issues a credit note to one of your onboarded companies, A-Cube, acting as the certified receiving platform (PA-R), intercepts, validates, and stores it automatically. Your system doesn't need to poll for new documents.

  • Inbound Arrival Notification: Webhook event credit_note.inbound
  • Inbound Credit Note Details: GET /credit-notes/{uuid}

Sample Arrival Webhook Payload​

{
  "eventId": "019ea765-da8a-70af-a037-b068ad1ff1ce",
  "eventType": "credit_note.inbound",
  "status": "205",
  "invoiceUuid": "019ea760-dad8-70b9-9b23-f60ff4004509",
  "direction": "INBOUND"
}

Submitting Lifecycle States​

Just as with invoices, receiving a credit note requires the buyer to actively report its processing status back to A-Cube, which relays it to the supplier and the tax authority.

  • Submit an Inbound Status Update: PUT /credit-notes/{uuid}/lifecycle

Note the verb: credit note status updates use PUT, while the equivalent invoice endpoint uses POST /invoices/{uuid}/lifecycle. The request body shape and the status codes themselves are identical.

{
  "afnorStatusCode": "APPROVED"
}

Returns 202 on success, 422 if the status code is not a recognized value.

  • Get Current Status: GET /credit-notes/{uuid}/current-status
  • Get Full Status History: GET /credit-notes/{uuid}/lifecycle

Statuses​

Credit notes use the exact same AFNOR status codes, labels, and rejection reasons as invoices, there is no separate status table to learn. See the full list, including payment-info statuses (211/212) and rejection reason codes, on the Invoice lifecycle page.

Downloading a credit note​

  • Download a human-readable PDF: GET /credit-notes/{uuid}/print
  • Download the original payload (UBL / CII XML as submitted): GET /credit-notes/{uuid}/source

Listing your credit notes​

  • List Credit Notes: GET /credit-notes

Returns the flat list of your credit notes (both directions), sorted by most recent first.

Last updated on