> ## Documentation Index > Fetch the complete documentation index at: https://docs.ionicfi.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a credit note > Issues a credit note against a paid invoice. The invoice must be in `paid` status; creating against a draft, open, void, or uncollectible invoice returns `422`. Supply either `lines` (one or more explicit credit lines) or `amount` (a shorthand that creates a single custom-line credit for the whole amount). Supplying both returns `400`. Settlement must be accounted for: `amount_refunded` (linked to an already-created refund `rf_…` via `refund`) plus `out_of_band_amount` must equal the credit total. The sum of all credit notes against an invoice cannot exceed the invoice total; exceeding it returns `422` with `CREDIT_NOTE_OVER_CREDIT`. Send an `Idempotency-Key` header so a retried request replays the first credit note rather than issuing a duplicate. ## OpenAPI ````yaml /openapi/credit_notes.yaml post /credit_notes openapi: 3.0.3 info: title: Ionic Credit Notes API version: '2026-05-01' description: > Credit notes — accounting documents that offset paid invoices. A credit note (`cn_…`) is an immutable document issued against a paid invoice. It reduces the invoice's effective balance by the credited amount. Every credit note carries a sequential, per-merchant/mode number (for example `CN-000001`; test-mode notes use `TEST-CN-000001`). Once issued, a credit note cannot be edited — it can only be voided, which creates an equal and opposite accounting entry. All monetary amounts are integers in the currency's minor unit (for example cents for USD). Timestamps are Unix epoch seconds. Identifiers are opaque, prefixed strings: credit notes are `cn_…`, credit note lines `cnl_…`. Authentication uses a merchant secret key (`sk_…`) as a bearer token. Read endpoints require the `credit_notes:read` permission; write endpoints require `credit_notes:write`. The mode of the key (test or live) scopes which resources it can see and mutate, reflected by each resource's `livemode` field. Send an `Idempotency-Key` header on create and void so a retried request never issues a duplicate credit or voids an already-voided note. Errors are returned as `{ "error": { "code": "...", "message": "..." } }`. servers: - url: '{baseUrl}/v1' variables: baseUrl: default: https://api.ionicfi.com description: API base URL for your environment. security: - secretKey: [] tags: - name: Credit Notes description: >- Issue, retrieve, list, void, and download credit notes against paid invoices. paths: /credit_notes: post: tags: - Credit Notes summary: Create a credit note description: | Issues a credit note against a paid invoice. The invoice must be in `paid` status; creating against a draft, open, void, or uncollectible invoice returns `422`. Supply either `lines` (one or more explicit credit lines) or `amount` (a shorthand that creates a single custom-line credit for the whole amount). Supplying both returns `400`. Settlement must be accounted for: `amount_refunded` (linked to an already-created refund `rf_…` via `refund`) plus `out_of_band_amount` must equal the credit total. The sum of all credit notes against an invoice cannot exceed the invoice total; exceeding it returns `422` with `CREDIT_NOTE_OVER_CREDIT`. Send an `Idempotency-Key` header so a retried request replays the first credit note rather than issuing a duplicate. operationId: credit_notes_create parameters: - $ref: '#/components/parameters/IdempotencyKeyRequired' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateCreditNoteRequest' responses: '201': description: The created credit note. content: application/json: schema: $ref: '#/components/schemas/CreditNote' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/InvoiceNotFound' '409': $ref: '#/components/responses/RefundAlreadyCredited' '422': $ref: '#/components/responses/InvalidCreditNoteState' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' security: - secretKey: - credit_notes:write components: parameters: IdempotencyKeyRequired: name: Idempotency-Key in: header required: true description: >- Required. A unique key that makes retries safe: the same key with the same request body returns the original response instead of repeating the operation. schema: type: string maxLength: 255 schemas: CreateCreditNoteRequest: type: object required: - invoice description: | Provide either `lines` or `amount` (not both). Settlement fields `amount_refunded` and `out_of_band_amount` must sum to the credit total. properties: invoice: type: string description: The paid invoice to credit (`inv_…`). Must be in `paid` status. lines: type: array description: Explicit credit lines. Mutually exclusive with `amount`. items: $ref: '#/components/schemas/CreditLineRequest' amount: type: integer nullable: true description: >- Shorthand for a single custom-line credit of this amount in minor units. Mutually exclusive with `lines`. amount_refunded: type: integer description: >- Portion of the credit already returned via an existing refund, in minor units. Requires `refund`. default: 0 out_of_band_amount: type: integer description: >- Portion of the credit settled outside the payment platform (for example, a check), in minor units. default: 0 refund: type: string nullable: true description: >- An already-created refund to link (`rf_…`). Required when `amount_refunded` is non-zero. reason: type: string nullable: true enum: - duplicate - fraudulent - order_change - product_unsatisfactory - adjustment description: Why the credit is being issued. Omit if no reason applies. memo: type: string nullable: true description: Free-text note printed on the credit note PDF. effective_at: type: integer nullable: true description: >- Unix epoch seconds to backdate the credit note. Defaults to the time of the request. metadata: type: object additionalProperties: type: string CreditNote: type: object required: - amount_refunded - created - currency - customer - effective_at - id - invoice - lines - livemode - memo - metadata - number - object - out_of_band_amount - reason - refund - status - subtotal - tax - total - type - voided_at properties: id: type: string description: Credit note id (`cn_…`). object: type: string enum: - credit_note number: type: string description: >- The gapless per-merchant number assigned at creation (for example `CN-000001`). invoice: type: string description: The invoice this credit note offsets (`inv_…`). customer: type: string description: The customer the invoice was issued to (`cus_…`). currency: type: string description: Three-letter ISO currency code. status: type: string enum: - issued - void description: >- `issued` is the normal state after creation; `void` means the credit note has been reversed. type: type: string enum: - post_payment description: Always `post_payment` in v1. reason: type: string nullable: true enum: - duplicate - fraudulent - order_change - product_unsatisfactory - adjustment description: The reason given at creation, or null if none was provided. subtotal: type: integer description: Sum of line amounts before tax, in minor units. tax: type: integer description: Total tax credited, in minor units. total: type: integer description: Total credit amount (subtotal + tax), in minor units. amount_refunded: type: integer description: Portion returned via the linked refund, in minor units. out_of_band_amount: type: integer description: Portion settled outside the platform, in minor units. refund: type: string nullable: true description: >- The linked refund (`rf_…`), or null when settlement was out-of-band only. lines: type: array items: $ref: '#/components/schemas/CreditNoteLine' memo: type: string nullable: true description: Free-text note printed on the PDF, or null if none was provided. hosted_url: type: string nullable: true description: >- Buyer-facing permalink for the hosted credit note view, when the hosted surface is enabled. Omitted otherwise. livemode: type: boolean created: type: integer description: Unix epoch seconds. effective_at: type: integer description: Unix epoch seconds the credit is dated to. voided_at: type: integer nullable: true description: >- Unix epoch seconds when the note was voided, or null while still `issued`. metadata: type: object additionalProperties: type: string CreditLineRequest: type: object required: - type - description - amount properties: type: type: string enum: - invoice_line_item - custom_line_item description: >- `invoice_line_item` credits a specific invoice line; `custom_line_item` adds a free-form credit. invoice_line_item: type: string nullable: true description: >- The invoice line to credit (`il_…`). Required when `type` is `invoice_line_item`. description: type: string description: Description of the credit line. quantity: type: integer nullable: true description: Number of units credited. Used together with `unit_amount`. unit_amount: type: integer nullable: true description: >- Per-unit credit amount in minor units. Used together with `quantity`. amount: type: integer description: Total credit amount for this line, in minor units. tax: type: integer description: Tax portion of this line's credit, in minor units. default: 0 CreditNoteLine: type: object required: - amount - description - id - invoice_line_item - livemode - object - quantity - tax - type - unit_amount properties: id: type: string description: Credit note line id (`cnl_…`). object: type: string enum: - credit_note_line_item type: type: string enum: - invoice_line_item - custom_line_item invoice_line_item: type: string nullable: true description: The source invoice line (`il_…`), or null for custom lines. description: type: string quantity: type: integer nullable: true unit_amount: type: integer nullable: true description: Per-unit amount in minor units, or null when not expressed per-unit. amount: type: integer description: Total line credit in minor units. tax: type: integer description: Tax portion in minor units. livemode: type: boolean Error: type: object properties: error: type: object properties: code: type: string description: A stable, machine-readable error code. message: type: string responses: BadRequest: description: The request was malformed or failed validation. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INVALID_DATA message: provide either lines or a single amount, not both Unauthorized: description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: The key lacks the required permission, or the merchant is not active. content: application/json: schema: $ref: '#/components/schemas/Error' InvoiceNotFound: description: No invoice with that id is visible to this key. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INVOICE_NOT_FOUND message: invoice not found RefundAlreadyCredited: description: >- The linked refund (`rf_…`) is already referenced by another credit note. This is a permanent conflict — do not retry with the same refund. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: CREDIT_NOTE_REFUND_ALREADY_CREDITED message: a credit note already credits this refund InvalidCreditNoteState: description: > The operation is not allowed in the current state. On create and preview, this means the target invoice is not paid (`INVALID_INVOICE_STATE`) or the credit total exceeds the invoice's creditable remaining (`CREDIT_NOTE_OVER_CREDIT`). On void, this means the credit note is already void (`INVALID_CREDIT_NOTE_STATE`). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INVALID_CREDIT_NOTE_STATE message: invalid credit note state for this operation RateLimited: description: Too many requests. Honour the `Retry-After` header before retrying. content: application/json: schema: $ref: '#/components/schemas/Error' InternalError: description: >- The API could not complete the request. For the PDF endpoint, the document could not be rendered. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: PDF_RENDER_FAILED message: failed to render credit note PDF securitySchemes: secretKey: type: http scheme: bearer description: 'A merchant secret key (`sk_…`) sent as `Authorization: Bearer `.' ````