> ## 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. # Preview a credit note > Computes the credit note totals, settlement breakdown, and the invoice's creditable-remaining context without persisting anything or minting a number. Useful for rendering a confirmation screen ("you will credit $X; $Y remains creditable"). No `Idempotency-Key` is required because nothing is created. ## OpenAPI ````yaml /openapi/credit_notes.yaml post /credit_notes/preview 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/preview: post: tags: - Credit Notes summary: Preview a credit note description: | Computes the credit note totals, settlement breakdown, and the invoice's creditable-remaining context without persisting anything or minting a number. Useful for rendering a confirmation screen ("you will credit $X; $Y remains creditable"). No `Idempotency-Key` is required because nothing is created. operationId: credit_notes_preview parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateCreditNoteRequest' responses: '200': description: The computed credit note preview. content: application/json: schema: $ref: '#/components/schemas/CreditNotePreview' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/InvoiceNotFound' '422': $ref: '#/components/responses/InvalidCreditNoteState' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' security: - secretKey: - credit_notes:write components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: false description: >- 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 CreditNotePreview: type: object description: >- A computed credit note preview — no id, number, or lines, because nothing is persisted. required: - already_credited - amount_refunded - creditable_remaining - currency - invoice_total - object - out_of_band_amount - subtotal - tax - total - type - would_exceed properties: object: type: string enum: - credit_note_preview currency: type: string description: Three-letter ISO currency code. type: type: string enum: - post_payment subtotal: type: integer description: Sum of line amounts before tax, in minor units. tax: type: integer description: Tax credited, in minor units. total: type: integer description: Total credit (subtotal + tax), in minor units. amount_refunded: type: integer description: Portion to be settled via the linked refund, in minor units. out_of_band_amount: type: integer description: Portion settled outside the platform, in minor units. invoice_total: type: integer description: The invoice's original total, in minor units. already_credited: type: integer description: Amount already credited by prior credit notes, in minor units. creditable_remaining: type: integer description: >- How much more can be credited before hitting the cap, in minor units. would_exceed: type: boolean description: >- True when this credit would exceed the invoice's creditable remaining. A subsequent create call will be rejected with `CREDIT_NOTE_OVER_CREDIT`. 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 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 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 `.' ````