> ## Documentation Index > Fetch the complete documentation index at: https://docs.paygood.com/llms.txt > Use this file to discover all available pages before exploring further. # List invoices for a merchant > Returns invoices sorted by newest first using cursor pagination. Supports optional customer and created-at range filtering. ## OpenAPI ````yaml /openapi.json get /invoices openapi: 3.0.0 info: title: PayGood Merchant API description: Server-to-server integration surface for merchant API keys. version: '1.0' contact: {} servers: - url: https://api-sandbox.paygood.co description: Sandbox - url: https://api.paygood.co description: Production security: [] paths: /invoices: get: tags: - invoices summary: List invoices for a merchant description: >- Returns invoices sorted by newest first using cursor pagination. Supports optional customer and created-at range filtering. operationId: InvoicesController_list parameters: - name: end required: false in: query description: >- Inclusive ISO-8601 upper bound for invoice `createdAt`. Must be >= `start` when both are provided. schema: example: '2026-03-31T23:59:59.999Z' type: string - name: start required: false in: query description: Inclusive ISO-8601 lower bound for invoice `createdAt`. schema: example: '2026-03-01T00:00:00.000Z' type: string - name: cursor required: false in: query description: Opaque cursor from a previous `page.nextCursor`. schema: example: >- eyJ2IjoxLCJkYXRhIjp7ImNyZWF0ZWRBdCI6IjIwMjYtMDMtMDFUMTI6MDA6MDAuMDAwWiIsImlkIjoiaW52XzAxLi4uIn19 type: string - name: limit required: false in: query description: Number of items to return. Maximum 100. schema: example: 25 type: number - name: customerId required: false in: query description: Optional customer TypeID (`cust_...`) filter. schema: example: cust_01hxy8m1nqk9g3x3y3p0azq2zz type: string - name: merchantId required: true in: query description: Merchant TypeID (`mer_...`) to scope invoice listing. schema: example: mer_01hxy8m1nqk9g3x3y3p0azq2bg type: string responses: '200': description: >- Paginated list of invoices. Each item contains invoice number, status, and computed totals. content: application/json: schema: $ref: '#/components/schemas/ListInvoicesResponseDto' '400': description: Invalid query parameters or malformed cursor token. '401': description: Missing or invalid authentication credentials. '403': description: >- Authenticated principal lacks `invoices.view` capability or merchant scope. security: - bearer: [] components: schemas: ListInvoicesResponseDto: type: object properties: items: type: array items: type: object properties: invoiceId: type: string invoiceNumber: type: string minLength: 1 invoiceUrlSlug: type: string minLength: 1 description: >- Secret pay-link token. Anyone holding this value can view and pay the invoice anonymously, so treat it like a credential: safe to send to the customer, never safe to log or expose publicly. Unguessable and unrelated to `invoiceId`, so it can be rotated without changing the invoice. idempotencyKey: type: string minLength: 1 merchantId: type: string customerId: type: string currentRevisionNumber: type: integer exclusiveMinimum: true maximum: 9007199254740991 minimum: 0 status: type: string enum: - draft - issued - partially_paid - paid - void currency: description: Supported currency code (USD, CAD) type: string minLength: 3 maxLength: 3 lineItems: type: array items: oneOf: - type: object properties: kind: type: string enum: - product_charge productId: type: string priceId: type: string description: type: string minLength: 1 maxLength: 500 quantity: type: integer exclusiveMinimum: true maximum: 9007199254740991 minimum: 0 unitAmount: type: integer minimum: 0 maximum: 9007199254740991 lineTotal: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - kind - productId - description - quantity - unitAmount - lineTotal additionalProperties: false - type: object properties: kind: type: string enum: - manual_adjustment description: type: string minLength: 1 maxLength: 500 amount: type: integer minimum: -9007199254740991 maximum: 9007199254740991 quantity: type: integer exclusiveMinimum: true maximum: 9007199254740991 minimum: 0 lineTotal: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - kind - description - amount - quantity - lineTotal additionalProperties: false productTotal: type: object properties: amount: type: integer exclusiveMinimum: true maximum: 9007199254740991 minimum: 0 currency: description: Supported currency code (USD, CAD) type: string minLength: 3 maxLength: 3 required: - amount - currency total: type: object properties: amount: type: integer exclusiveMinimum: true maximum: 9007199254740991 minimum: 0 currency: description: Supported currency code (USD, CAD) type: string minLength: 3 maxLength: 3 required: - amount - currency amountPaid: type: object properties: amount: type: integer exclusiveMinimum: true maximum: 9007199254740991 minimum: 0 currency: description: Supported currency code (USD, CAD) type: string minLength: 3 maxLength: 3 required: - amount - currency description: >- Sum of applied payment allocations, both processed and out-of-band. amountRemaining: type: object properties: amount: type: integer exclusiveMinimum: true maximum: 9007199254740991 minimum: 0 currency: description: Supported currency code (USD, CAD) type: string minLength: 3 maxLength: 3 required: - amount - currency description: >- Computed as `total` minus `amountPaid`. Zero when the invoice is fully paid. dueDate: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ paidAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ notes: type: string metadata: type: object additionalProperties: {} createdAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ updatedAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ required: - invoiceId - invoiceNumber - invoiceUrlSlug - idempotencyKey - merchantId - customerId - currentRevisionNumber - status - currency - lineItems - productTotal - total - amountPaid - amountRemaining - createdAt - updatedAt page: type: object properties: hasMore: type: boolean nextCursor: type: string required: - hasMore required: - items - page securitySchemes: bearer: scheme: bearer bearerFormat: merchant__ type: http description: >- Merchant API key bearer token. Legacy wire prefixes `api_key_` and `api_` are also accepted. ````