> ## Documentation Index > Fetch the complete documentation index at: https://docs.stablepayfi.ai/llms.txt > Use this file to discover all available pages before exploring further. # List invoices > List invoices with optional filtering by subscription, customer, or status. ## OpenAPI ````yaml /en/api/invoice-openapi.json get /api/v1/invoices openapi: 3.1.0 info: title: StablePay Invoice API version: '2026-04-20' description: >- Standalone invoice query APIs for retrieving invoice details by ID or listing invoices. Invoice APIs are maintained separately from Subscription APIs. servers: - url: https://api.stablepay.co description: Production security: - bearerAuth: [] stablepayTimestamp: [] stablepayNonce: [] stablepaySignature: [] tags: - name: Invoices description: Retrieve and list subscription invoices. paths: /api/v1/invoices: get: tags: - Invoices summary: List invoices description: >- List invoices with optional filtering by subscription, customer, or status. operationId: listInvoices parameters: - name: subscription_id in: query description: Filter by subscription ID. schema: type: string - name: customer in: query description: Filter by customer ID. schema: type: string - name: status in: query description: >- Filter by invoice status. Only `open`, `paid`, and `void` are supported. schema: $ref: '#/components/schemas/InvoiceStatus' - name: limit in: query description: Number of records to return. Defaults to 10, maximum 100. schema: type: integer default: 10 minimum: 1 maximum: 100 - name: starting_after in: query description: >- Forward pagination cursor. The current implementation queries `invoice_id > starting_after`. schema: type: string - $ref: '#/components/parameters/XStablePayTimestamp' - $ref: '#/components/parameters/XStablePayNonce' - $ref: '#/components/parameters/XStablePaySignature' responses: '200': description: Listed successfully. content: application/json: schema: $ref: '#/components/schemas/InvoiceList' '400': description: Invalid request parameters. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Authentication failed. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: InvoiceStatus: type: string enum: - open - paid - void description: >- Invoice status. Query values must be lowercase: `open`, `paid`, or `void`. InvoiceList: type: object properties: object: type: string example: list data: type: array items: $ref: '#/components/schemas/Invoice' has_more: type: boolean description: >- Whether more data may exist. The current implementation checks whether the returned count equals limit. url: type: string description: Current request URL. ErrorResponse: type: object description: Error response. properties: error: type: object properties: type: type: string description: Error type. code: type: string description: Error code. message: type: string description: Error message. param: type: string description: Related parameter. doc_url: type: string description: Error documentation URL. decline_code: type: string description: Decline code. request_log_url: type: string description: Request log URL. charge: type: string description: Related payment ID. request_id: type: string description: Request ID. timestamp: type: integer format: int64 description: Error timestamp in Unix seconds. Invoice: type: object required: - id - object - subscription_id - customer - amount_due - amount_paid - amount_remaining - currency - status - payment_status - billing_reason - period_start - period_end - created properties: id: type: string description: Invoice ID. object: type: string example: invoice subscription_id: type: string description: Related subscription ID. customer: type: string description: Customer ID. amount_due: type: integer format: int64 description: Amount due in minor units. amount_paid: type: integer format: int64 description: Amount paid in minor units. amount_remaining: type: integer format: int64 description: Amount remaining in minor units. currency: type: string description: Currency. status: $ref: '#/components/schemas/InvoiceStatus' payment_status: type: string enum: - pending - processing - completed - failed - canceled - expired description: Invoice payment status. billing_reason: type: string description: >- Billing reason, for example `subscription_create` or `subscription_cycle`. frequency: type: string description: Human-readable billing frequency, for example `Monthly`. recurring_interval: type: string enum: - day - week - month - year description: Recurring interval. recurring_interval_count: type: integer format: int32 description: Recurring interval count. period_start: type: integer format: int64 description: Billing period start, Unix seconds. period_end: type: integer format: int64 description: Billing period end, Unix seconds. payment_id: type: string description: >- Related payment session ID. The API prefers payment_session_id and falls back to trade_order_id. paid_at: type: integer format: int64 description: Payment completion time, Unix seconds. due_date: type: integer format: int64 description: Due date, Unix seconds. created: type: integer format: int64 description: Creation time, Unix seconds. parameters: XStablePayTimestamp: name: X-StablePay-Timestamp in: header required: true description: Unix timestamp in seconds. Must be within 5 minutes of server time. schema: type: string example: '1735689600' XStablePayNonce: name: X-StablePay-Nonce in: header required: true description: Replay-protection nonce, 16-64 characters. Use a fresh UUID per request. schema: type: string minLength: 16 maxLength: 64 example: 550e8400-e29b-41d4-a716-446655440000 XStablePaySignature: name: X-StablePay-Signature in: header required: true description: >- Lowercase hex HMAC-SHA256 of `{timestamp}.{nonce}.{requestBody}` signed with the merchant API Secret. For GET requests, `requestBody` is an empty string. schema: type: string example: a1b2c3d4e5f6... securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API Key description: Bearer API Key, for example `Bearer sk_live_xxx`. stablepayTimestamp: type: apiKey in: header name: X-StablePay-Timestamp description: Unix timestamp in seconds. Must be within 5 minutes of server time. stablepayNonce: type: apiKey in: header name: X-StablePay-Nonce description: Replay-protection nonce, 16-64 characters. Use a fresh UUID per request. stablepaySignature: type: apiKey in: header name: X-StablePay-Signature description: >- Lowercase hex HMAC-SHA256 of `{timestamp}.{nonce}.{requestBody}` signed with the merchant API Secret. For GET requests, `requestBody` is an empty string. ````