> ## 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 an invoice item > Records a pending charge for a customer. It remains pending until an invoice for that customer is created, which drains it onto the invoice. ## OpenAPI ````yaml /openapi/invoices.yaml post /invoice_items openapi: 3.0.3 info: title: Ionic Invoices API version: '2026-05-30' description: | Invoices and invoice items. An invoice item is a pending charge recorded against a customer. When an invoice is created for that customer, every pending item in the invoice currency is drained onto the new draft as a line. A draft can be edited freely; finalizing it assigns a gapless, per-merchant/mode sequential number (for example `INV-000001`), applies tax, freezes the lines, and opens the invoice. Drafts carry no number, so an abandoned draft never consumes one and the finalized sequence is always contiguous. 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: invoices are `inv_…`, invoice items `ii_…`, and invoice lines `il_…`. Authentication uses a merchant secret key as a bearer token. Read endpoints require the `invoices:read` permission; write endpoints require `invoices:write`. The mode of the key (test or live) scopes which invoices and invoice items it can see, mutate, and drain. Live invoice numbers use `INV-000001` style labels; test invoice numbers use `TEST-INV-000001`. Mutating endpoints accept an optional `Idempotency-Key` header. Errors are returned as `{ "error": { "code": "...", "message": "..." } }`. A malformed path identifier returns 400. Concurrent updates are retried automatically; if they still conflict, the API returns 409 and the request can be retried. servers: - url: '{baseUrl}/v1' variables: baseUrl: default: https://api.ionicfi.com description: API base URL for your environment. security: - secretKey: [] tags: - name: Invoices description: Create, finalize, and manage invoices. - name: Invoice Items description: Pending charges that drain onto a customer's next invoice. paths: /invoice_items: post: tags: - Invoice Items summary: Create an invoice item description: >- Records a pending charge for a customer. It remains pending until an invoice for that customer is created, which drains it onto the invoice. operationId: invoices_items_create parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateInvoiceItemRequest' responses: '201': description: The created invoice item. content: application/json: schema: $ref: '#/components/schemas/InvoiceItem' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/CustomerNotFound' '422': $ref: '#/components/responses/CustomerDeleted' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' security: - secretKey: - invoices: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: CreateInvoiceItemRequest: type: object required: - customer - description - quantity - unit_amount - currency properties: customer: type: string description: Customer id (`cus_…`). description: type: string quantity: type: integer minimum: 1 unit_amount: type: integer description: Per-unit price in minor units. currency: type: string description: Three-letter ISO currency code. price: type: string nullable: true description: Optional price id (`price_…`) for catalog reference. metadata: type: object additionalProperties: type: string InvoiceItem: type: object required: - amount - created_at - currency - customer - description - id - invoice - metadata - object - pending - quantity - unit_amount - updated_at properties: id: type: string object: type: string enum: - invoice_item customer: type: string description: type: string quantity: type: integer unit_amount: type: integer amount: type: integer description: Total amount in minor units. currency: type: string invoice: type: string nullable: true description: The invoice this item was drained onto, or null while pending. price: type: string nullable: true pending: type: boolean metadata: type: object additionalProperties: type: string created_at: type: integer description: Unix epoch seconds. updated_at: type: integer 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: invalid currency 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' CustomerNotFound: description: No such customer for this merchant. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: CUSTOMER_NOT_FOUND message: customer not found CustomerDeleted: description: The customer has been deleted. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: CUSTOMER_ALREADY_DELETED message: customer is deleted 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 return a successful response. For a mutating request, retrieve the resource before retrying because the operation may have completed. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: secretKey: type: http scheme: bearer description: 'A merchant secret key (`sk_…`) sent as `Authorization: Bearer `.' ````