> ## 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. # List credit notes ## OpenAPI ````yaml /openapi/credit_notes.yaml get /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: get: tags: - Credit Notes summary: List credit notes operationId: credit_notes_list parameters: - name: invoice in: query description: Filter to credit notes for a specific invoice (`inv_…`). schema: type: string - name: customer in: query description: Filter to credit notes for a specific customer (`cus_…`). schema: type: string - name: status in: query description: Filter by status. schema: type: string enum: - issued - void - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Offset' - name: starting_after in: query description: >- Cursor: a credit note id (typically the previous response's `next_cursor`). Returns results strictly after it, newest first. Cannot be combined with `offset`. schema: type: string responses: '200': description: A paginated list of credit notes, newest first. content: application/json: schema: $ref: '#/components/schemas/CreditNoteList' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' security: - secretKey: - credit_notes:read components: parameters: Limit: name: limit in: query description: Page size (default 20, max 100). schema: type: integer minimum: 1 maximum: 100 default: 20 Offset: name: offset in: query description: Number of records to skip. schema: type: integer minimum: 0 default: 0 schemas: CreditNoteList: type: object required: - data - has_more - object properties: object: type: string enum: - list data: type: array items: $ref: '#/components/schemas/CreditNote' has_more: type: boolean description: True when more records exist beyond this page. next_cursor: type: string description: >- Present when `has_more` is true: the last returned credit note's id. Pass it as `starting_after` on the next request. 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 Error: type: object properties: error: type: object properties: code: type: string description: A stable, machine-readable error code. message: type: string 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 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' 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 `.' ````