# Credit Notes

Credit notes let merchants document returns and refunds for previously issued receipts. A customer can submit an encrypted return request from the Cheqi app; the merchant validates it, handles the monetary refund, and issues a credit note linked to the original Cheqi receipt.

Refund responsibility
Cheqi delivers the credit note. Your payment system remains responsible for moving money.

The return-request flow is optional
You can handle returns entirely in your own system. For example, include a merchant-controlled barcode or QR code on the receipt or its product lines and use that identifier in your return process.

## Flow

1. The customer submits a return request from the Cheqi app.
2. Cheqi routes the encrypted request to the original receipt issuer by webhook or polling.
3. The merchant decrypts the request, validates eligibility and quantities, and chooses an outcome.
4. The merchant processes the monetary refund and issues the definitive credit-note payload.
5. Cheqi queues the encrypted payload for the customer's owner devices, which generate the requested CHEQI JSON and UBL CreditNote documents.


The merchant submission links the new document to its parent using `parentCheqiReceiptId`. That value is delivery metadata; it is not a property of the generated CHEQI JSON document.

## Customer return-request model

The decrypted `CreditNoteInitiationRequest` has these properties:

| Property | Type | Required | Description |
|  --- | --- | --- | --- |
| `cheqiReceiptId` | string | Yes | Cheqi identifier of the original receipt. |
| `receiptId` | string | Yes | Merchant-supplied identifier of the original receipt. |
| `customerNote` | string | No | Customer note, up to 1,000 characters. |
| `lineItems` | `ReturnLineItem[]` | Yes | At least one requested return line. |
| `refundPreference` | enum | Yes | `ORIGINAL_PAYMENT_METHOD`, `BANK_TRANSFER`, or `STORE_CREDIT`. |
| `refundBankAccount` | object | Conditional | Required only for `BANK_TRANSFER`; otherwise it must be absent. |


Each `ReturnLineItem` contains:

| Property | Type | Required | Description |
|  --- | --- | --- | --- |
| `productId` | string | Yes | The merchant-supplied `identifier` of the original receipt product. Maximum 255 characters. |
| `quantity` | number | Yes | Requested return quantity; must be greater than zero. |
| `reasonCode` | enum | Yes | `DEFECTIVE`, `DAMAGED`, `WRONG_ITEM`, `NOT_AS_DESCRIBED`, `UNWANTED`, `EXPIRED`, or `INCOMPLETE`. |
| `reasonDescription` | string | No | Optional explanation, up to 1,000 characters. |


`RefundBankAccount` contains required `iban` and `accountHolder` strings plus an optional `bic`.

See [Receiving Return Requests](/creditnote/receiving-returns) for the encrypted polling and webhook shapes.

## Merchant credit-note input

The encrypted issuance payload contains a `creditNoteTemplateRequest` and `taxesApplied`. Cheqi does not calculate these values; the merchant supplies the definitive amounts and tax data.

| Property | Type | Required | Description |
|  --- | --- | --- | --- |
| `documentNumber` | string | Yes | Merchant's unique credit-note number. |
| `originatorDocumentReference` | string | Yes | Merchant document number of the original receipt. |
| `identifiers` | object[] | No | Additional `{ type, value }` document identifiers. |
| `issueDate` | ISO 8601 date-time | Yes | Credit-note issue timestamp. |
| `currency` | string | Yes | ISO 4217 currency code. |
| `creditNoteSubtotal` | decimal | Yes | Sum of line amounts before document-level adjustments and tax. |
| `totalBeforeTax` | decimal | Yes | Total after document-level discounts and charges, excluding tax. |
| `totalTaxAmount` | decimal | Yes | Total tax amount. |
| `totalAmount` | decimal | Yes | Tax-inclusive credit amount. |
| `products` | product[] | Yes | At least one credited product; every product needs `name` and `identifier`. |
| `discounts` | discount[] | No | Document-level discounts. |
| `charges` | charge[] | No | Document-level charges. |
| `taxes` | tax[] | Conditional | Required when `taxesApplied` is `true`; may be empty otherwise. |
| `period` | object | No | Service or billing period. |
| `jurisdictionalData` | object | No | Country-specific fiscal and legal data. |


Use positive quantities and credit amounts. The document type communicates that these values are credits; do not negate the lines or totals.

The legacy `note` input is accepted for compatibility but is not used to generate the document note. The generated note comes from the issuer's configured company receipt text.

## Generated CHEQI JSON

Owner devices combine the merchant input with trusted company, store, recipient, and document context. The generated JSON contains:

| Property | Required | Source |
|  --- | --- | --- |
| `documentNumber` | Yes | Merchant input. |
| `originatorDocumentReference` | Yes | Merchant input. |
| `identifiers` | No | Merchant input; omitted when empty. |
| `issueDate` | Yes | Merchant input. |
| `currency` | Yes | Merchant input. |
| `creditNoteSubtotal` | Yes | Merchant input. |
| `totalBeforeTax` | Yes | Merchant input. |
| `totalTaxAmount` | Yes | Merchant input. |
| `totalAmount` | Yes | Merchant input. |
| `products` | Yes | Merchant input. |
| `discounts` | No | Merchant input; omitted when empty. |
| `charges` | No | Merchant input; omitted when empty. |
| `taxes` | Yes | Merchant input; can be an empty array when tax does not apply. |
| `period` | No | Merchant input. |
| `note` | No | Issuer's configured company receipt text. |
| `sellingParty` | Yes | Trusted issuer context. |
| `store` | No | Trusted store context. |
| `receivingParty` | No | Resolved customer context. |
| `jurisdictionalData` | No | Merchant input. |
| `receiptUuid` | Yes | Device-generation context; also written as the UBL `cbc:UUID`. |


`cheqiCreditNoteId`, `parentCheqiReceiptId`, and `supplierPartyId` are delivery or persistence metadata and are not properties of the generated CHEQI JSON document. `verificationNonce` is not part of the current model; use `receiptUuid` as the shared document identifier.

## Formats and verification

The generated formats are:

- CHEQI JSON, hashed after RFC 8785 canonicalization with SHA-256.
- UBL CreditNote XML, hashed after exclusive XML canonicalization with SHA-256.


See [UBL XML Credit Note Format](/creditnote/ubl-format) and [Receipt & Credit Note Verification](/verification/verification).

## Next steps

- [Receive and decrypt return requests](/creditnote/receiving-returns)
- [Build and issue a credit note](/creditnote/issuing-credit-notes)
- [Java SDK](/sdk/java)
- [JavaScript SDK](/sdk/javascript)
- [Request another SDK language](/sdk/overview)