> ## Documentation Index > Fetch the complete documentation index at: https://docs.paygentic.io/llms.txt > Use this file to discover all available pages before exploring further. # List > List invoices with optional filters. Platform users can use nextActionAt=ready to get invoices ready for processing. ## OpenAPI ````yaml /openapi.json get /v2/invoices openapi: 3.1.0 info: title: Paygentic API version: 0.1.0 description: > The Paygentic API provides a comprehensive platform for building and scaling monetization infrastructure. ## Authentication All API requests require authentication using an API key passed in the `Authorization` header: ``` Authorization: Bearer YOUR_API_KEY ``` ## Base URL All API requests should be made to: ``` https://api.paygentic.io/v0 ``` contact: name: Paygentic Support email: support@paygentic.io license: name: Proprietary servers: - url: https://api.paygentic.io description: Production API - url: https://api.sandbox.paygentic.io description: Sandbox API security: - BearerAuth: [] tags: - name: Customers description: >- A `Customer` is an entity connected to a `Merchant` via a `Subscription`. This represents the merchant-facing perspective of `Consumers` who purchase their `Products`. - name: Billable Metrics description: >- A `Billable Metric` defines a measurable quantity tied to a `Product`'s consumption. Each metric stores details including its label, an explanatory description, and measurement units. - name: Grants description: >- Grants credit a customer's metered entitlement balance. Merchants can create grants directly or void existing ones. Use `GET /v1/entitlements?customerId={id}` or `GET /v1/entitlements?subscriptionId={id}` to find the metered entitlement `id` needed for these endpoints. - name: Features description: >- A `Feature` represents a specific capability or functionality provided by a `Product`. Features can be metered (usage-based), static (fixed allocation), or boolean (enabled/disabled). - name: Fees description: >- A `Fee` defines a recurring or one-time charge tied to a `Product`. Fees are linked to prices, and cadence is defined on the Price. - name: Plans description: >- A `Plan` links a collection of `Prices` to a `Product`. It functions as a pricing structure document for a particular feature set or service offering. - name: Prices description: >- A `Price` determines the monetary value for a single unit of a `Billable Metric`. Prices are exclusively grouped within a `Plan`. - name: Products description: >- A `Product` is an offering sold by a `Merchant`. It includes product metadata like title, summary, and pricing details. `Plans`, `Prices`, and `Subscriptions` are all associated with products. - name: Sources description: >- A `Source` is an external data provider capable of automatically creating usage events. Configuration occurs at the plan level, enabling data retrieval from third-party platforms such as Stripe to produce billable events. - name: Subscriptions description: >- A `Subscription` is a customer's commitment to purchase a `Product` following the terms of a `Plan` and its linked `Prices`. - name: Users description: >- A `User` is an entity granted access to an Organization's resources. All operations are performed by users. - name: Invoices V2 description: >- Invoice V2 operations supporting billing cycles organized by time periods. Warning: v0 invoice endpoints are no longer supported. - name: Revenue description: Revenue data from invoices and payments - name: Profitability description: Per-customer profitability summaries - name: Test Clocks description: >- Test clocks provide programmable time control to simulate subscription and billing scenarios during testing. - name: Events description: Ingest raw metering events that are processed by the meters service. - name: Payments description: >- Create and manage one-off payments. A payment represents a single charge that a merchant wants to collect from a customer. - name: Payment Sessions description: >- Handle payment session lifecycle and processing across various entity types including invoices and subscriptions - name: Costs description: >- A Cost represents the operational or infrastructure expense of serving customers for a given product. Costs are metered (driven by event-based usage) and are tracked in parallel with billable metrics to give merchants visibility into both revenue and cost per customer. - name: ExternalReferences description: >- An `ExternalReference` links a Paygentic entity (e.g. an `Item`) to a record in an external system such as Salesforce or NetSuite. Multiple external records may map to the same Paygentic entity, but each external id is the *primary* reference of at most one entity per merchant. - name: Items description: >- An `Item` is the canonical "thing you sell" that external-system mappings point at. It is fully decoupled from the billing `Product` and holds no pricing/plan/metering, and it is CRM/ERP agnostic — which providers map to it lives entirely in its `ExternalReference` rows. - name: MerchantIntegrations description: >- A `MerchantIntegration` records a merchant's connection to an external provider. One connection per `(merchant, provider)` — re-connecting upserts in place. - name: Approvals description: Submit, decide, cancel, and read maker-checker approvals. - name: Orders description: Manage Orders, their line items, and billing schedules. - name: Billing Schedules description: >- Owner-polymorphic billing schedules with intervals and staged invoice projections. A BillingSchedule belongs to exactly one Order or one Subscription (XOR). Cadence lives on ScheduleIntervals (cadence-on-the-line). paths: /v2/invoices: get: tags: - Invoices V2 summary: List description: >- List invoices with optional filters. Platform users can use nextActionAt=ready to get invoices ready for processing. operationId: listInvoices parameters: - in: query name: limit schema: type: integer minimum: 1 maximum: 100 default: 10 description: Maximum number of invoices to return - in: query name: offset schema: type: integer default: 0 minimum: 0 maximum: 10000 description: Number of invoices to skip for pagination - in: query name: nextActionAt schema: type: string enum: - ready description: Filter for invoices ready for processing (platform only) - in: query name: status schema: type: string enum: - ACTIVE - CLOSING - CLOSED - CALCULATING - DRAFT - ISSUED - PAYMENT_FAILED - PAID - CANCELLED - WRITTEN_OFF - FAILED description: Filter invoices by status - in: query name: subscriptionId schema: $ref: '#/components/schemas/SubscriptionId' description: Filter invoices by subscription ID - in: query name: customerId schema: $ref: '#/components/schemas/CustomerId' description: >- Filter invoices by customer ID. Authorizes against the customer's merchant; takes precedence as the merchant source when combined with other filters. - in: query name: merchantId schema: $ref: '#/components/schemas/OrganizationId' description: Filter invoices by merchant ID responses: '200': description: List of invoices content: application/json: schema: type: object properties: object: type: string enum: - list data: type: array items: $ref: '#/components/schemas/Invoice' pagination: $ref: '#/components/schemas/OffsetPagination' required: - object - data - pagination example: object: list data: - id: inv_b5c6d7e8f9g0h1i2 autoApprove: true billingAnchor: '2024-03-01T00:00:00Z' billingCadence: P1M gracePeriodEnd: '2024-04-01T23:59:59Z' grandTotal: '0.00' invoiceNumber: null itemCount: 0 lineItems: null nextActionAt: null paidAmount: '0.00' paymentUrl: null pdfUrl: null pdfSource: null documentWithheldReason: null periodEnd: '2024-03-31T23:59:59Z' periodStart: '2024-03-01T00:00:00Z' permalink: null sequenceNumber: 1 status: ACTIVE subscriptionId: sub_j3k4l5m6n7o8p9q0 subtotal: '0.00' tax: null totalTax: '0.00' unpaidAmount: '0.00' pagination: limit: 10 offset: 0 total: 1 '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/InternalServerError' components: schemas: SubscriptionId: type: string pattern: ^sub_[a-zA-Z0-9]+$ description: Unique identifier for a subscription CustomerId: type: string pattern: ^cus_[a-zA-Z0-9]+$ description: Unique identifier for a customer OrganizationId: type: string pattern: ^org_[a-zA-Z0-9]+$ description: Unique identifier for an organization Invoice: type: object properties: id: type: string description: The invoice ID object: type: string enum: - invoice description: The object type autoApprove: type: boolean description: Whether this invoice auto-approves after calculation billingAnchor: type: string format: date-time description: The billing anchor date used for period calculations billingCadence: type: string description: ISO 8601 duration string for billing frequency createdAt: type: string format: date-time description: When the invoice was created currency: type: string description: ISO 4217 currency code (e.g., USD, EUR) failureReason: type: string description: >- Machine-readable reason code for the most recent failure (e.g. CALCULATION_FAILED). Present only when status is FAILED or PAYMENT_FAILED. paymentInFlight: type: boolean description: >- Whether a payment for this invoice is currently being processed (the payment session is in the 'processing' state). Clients should not offer manual 'mark as paid' while true. Only populated by GET /invoices/{id}. gracePeriodEnd: type: string format: date-time description: The end of the grace period for accepting usage events grandTotal: type: string description: >- Grand total (subtotal + tax) in decimal dollars (real-time for ACTIVE/CLOSING/CLOSED, cached otherwise) invoiceNumber: type: string nullable: true description: The invoice number itemCount: type: integer description: >- Number of billing items (real-time for ACTIVE/CLOSING/CLOSED, cached otherwise) lineItems: type: object nullable: true description: >- Line items (only present if expand=lineItems query parameter is provided, or if expand=items is, which implies it) properties: invoiceId: type: string description: The invoice ID lineItems: type: array description: Array of line items for this page items: $ref: '#/components/schemas/InvoiceLineItem' items: type: array description: >- Items the returned lines were tagged with, each appearing once, ordered by id. Only present when expand=items is requested. Scoped to the lines in THIS response, not the whole invoice — combine the collections across pages for an invoice-wide set. Join a line to its entry via the line's itemId. A line whose itemId has no entry here is a data-integrity fault — the tag points at an item that no longer resolves for this merchant. It is not the same as an untagged line and must not be counted as unmapped; report it. items: $ref: '#/components/schemas/ResolvedItem' nextPageToken: type: string nullable: true description: Token for fetching the next page, null if no more pages totalCount: type: integer description: Total number of line items across all pages required: - invoiceId - lineItems - totalCount merchantId: type: string description: The merchant organization ID metadata: type: object additionalProperties: true description: Additional metadata including transition history nextActionAt: type: string format: date-time nullable: true description: When the next scheduled action should occur paidAmount: type: string description: >- Amount already paid via wallet (account_type='main') in decimal dollars paidAt: type: string format: date-time nullable: true description: When the invoice was paid (null if not yet paid) dueAt: type: string format: date-time nullable: true description: >- Payment due date snapshotted at invoice-create time as the issue date + subscription.paymentTermDays, anchored to midnight UTC. Null only for invoices created before this feature shipped (no backfill). paymentUrl: type: string format: uri nullable: true description: >- Payment URL for completing payment (only present when status is ISSUED and unpaidAmount > 0) pdfUrl: type: string format: uri nullable: true description: >- Link to the invoice document, or null when there is none. For Paygentic-rendered documents this is GET /v2/invoices/{id}/pdf, which requires authentication; for documents supplied by the tax provider it is the provider's own direct link. The URL is stable and does not expire. Branch on pdfSource rather than on the shape of this URL. pdfSource: type: string enum: - paygentic - tax_provider - null nullable: true description: >- Who produced the document at pdfUrl, or null when there is none. `paygentic` means pdfUrl is this API's download endpoint and the request must carry your API key; `tax_provider` means it is the provider's own link, which opens directly in a browser. documentWithheldReason: type: string enum: - tax_unreconciled - issuer_identity_incomplete - tax_component_unpriceable - ledger_mismatch - tax_provider_disagrees - null nullable: true x-speakeasy-unknown-values: allow description: >- Why no Paygentic-rendered document exists for this invoice, or null when none was withheld. A tax-registered merchant's document is a compliance artefact, so it is withheld unless the recorded tax reconciles with the provider exactly and the registered issuer identity is complete. Non-null therefore always accompanies pdfSource `tax_provider` or null, and never `paygentic`. Use it to tell a withheld document apart from an invoice the tax provider serves by design — both report pdfSource `tax_provider`, but only a withheld one can be repaired by POST /v2/invoices/{id}/generate-pdf. `tax_unreconciled`: the provider's tax figure was never recorded against this invoice. `issuer_identity_incomplete`: the registered legal name, tax ID or address could not be read. `tax_component_unpriceable`: a recorded tax component carried no presentable amount. `ledger_mismatch`: the recorded tax figures and the invoice's own totals disagree. `tax_provider_disagrees`: the provider re-read its filing and reported a different tax to the one this invoice was charged — terminal, because correcting an issued invoice is a credit note's job, so retrying the repair cannot clear it. New values may be added, so treat an unrecognised one as withheld rather than failing. periodEnd: type: string format: date-time description: The end of the billing period periodStart: type: string format: date-time description: The start of the billing period permalink: type: string format: uri nullable: true description: Public URL to view tax invoice sequenceNumber: type: integer description: The sequence number of this invoice period status: type: string enum: - ACTIVE - CLOSING - CLOSED - CALCULATING - DRAFT - ISSUED - PAYMENT_FAILED - PAID - CANCELLED - WRITTEN_OFF - FAILED description: The current status of the invoice subscriptionId: type: string description: The subscription ID this invoice belongs to customerId: type: string description: The customer ID that owns this invoice subtotal: type: string description: >- Subtotal in decimal dollars (real-time for ACTIVE/CLOSING/CLOSED, cached otherwise) tax: type: object nullable: true description: Tax reconciliation metadata (only present when plan has taxEnabled) properties: actualTax: type: string description: Actual tax calculated (in atomic units) adjustmentApplied: type: boolean description: Whether wallet adjustment was applied during tax reconciliation adjustmentNeeded: type: boolean description: Whether wallet adjustment is needed (difference >= $0.01) difference: type: string description: Difference between actual and estimated (in atomic units) estimatedTax: type: string description: Tax estimated from subscription rate (in atomic units) reconciled: type: boolean description: Whether reconciliation was performed reconciledAt: type: string format: date-time description: When reconciliation occurred totalTax: type: string description: >- Total tax in decimal dollars (real-time for ACTIVE/CLOSING/CLOSED, cached otherwise) unpaidAmount: type: string description: >- Amount accrued as liability (account_type='usage') in decimal dollars updatedAt: type: string format: date-time description: When the invoice was last updated required: - id - merchantId - object - subscriptionId - customerId - sequenceNumber - status - currency - periodStart - periodEnd - gracePeriodEnd - billingAnchor - billingCadence - autoApprove - itemCount - subtotal - totalTax - grandTotal - paidAmount - unpaidAmount - createdAt - updatedAt OffsetPagination: type: object description: Offset-based pagination response. properties: limit: type: integer description: Requested page size. offset: type: integer description: Number of items skipped. total: type: integer description: Total number of items available. required: - limit - offset - total InvoiceLineItem: type: object required: - eventType - eventId - eventSourceId - billableMetricId - quantity - unitPrice - totalPrice - taxRate - totalTax - totalAmount - meterEventId - metricName - metricDescription - metricUnit - invoiceDisplayName - lineItemType properties: eventType: type: string enum: - usage - fee - discount description: >- Type of event: 'usage' for billable metric events, 'fee' for fee events, 'discount' for grant discount line items (subtotal/total are negative, representing a credit) eventId: type: string description: The event ID (usage_event_id or fee_event_id) eventSourceId: type: string description: >- Source ID: billable_metric_id for usage events, fee_id for fee events billableMetricId: type: string description: 'HOTFIX: Mirrors eventSourceId for backward compatibility' itemId: type: string nullable: true description: >- Item the line's charge was tagged with, recorded when the line was generated and not re-resolved on read. A discount line carries the same item as the charge it offsets. `null` means the charge carried no tag at that moment, the line predates item stamping, or the line has no originating charge (a grant-credit purchase) — it is an expected value, not an error. Use `priceId` to tell those cases apart. priceId: type: string nullable: true description: >- The price this line was generated from, or `null` when the line has no originating charge. With `itemId` it says whether a missing tag is fixable: `priceId` set and `itemId` null means the charge was simply untagged, which tagging it and restamping resolves; both null means the line records a grant-credit purchase, which is deferred revenue and is never tagged. Any measure of outstanding mapping work must exclude the latter or it can never reach zero. periodStart: type: string format: date-time description: >- Start of the billed window this line covers, inclusive. Distinct from the invoice's own period, which is the union of its lines' windows (earliest start to latest end) and so covers time no single line bills on a mixed-timing invoice. periodEnd: type: string format: date-time description: >- End of the billed window this line covers, exclusive — the instant at `periodEnd` belongs to the next window. Equal to `periodStart` on a one-off charge, which bills at an instant and has no period grid. paymentTerm: type: string enum: - in_advance - in_arrears - null nullable: true description: >- When this line falls due relative to the window it covers: `in_advance` at the window's start, `in_arrears` at its end. A metered line is stamped `in_arrears`, because usage is only known once the window closes — but metered rows written before that rule carry `null` and were never backfilled, so do not read a metered line's term as guaranteed. `null` also means the line is not billed on a term of its own: manual, grant-discount and adjustment lines carry no term, and an adjustment instead falls due with the charge it reduces. Treat `null` as an expected value on any line type, not an error. invoiceDisplayName: type: string description: Display name for this line item on invoices lineItemType: type: string enum: - charge - refund description: >- Type of line item: 'charge' for regular billing, 'refund' for refunded items (amounts are negated) meterEventId: type: string description: The meter event ID (usage events only) metricDescription: type: string description: Description of what this metric or fee measures metricName: type: string description: Human-readable name of the billable metric or fee metricUnit: type: string description: >- Measurement unit label. Sample values: 'calls' for API calls, 'GB' for storage, 'hours' for compute time, 'tokens' for LLM tokens, 'charge' for fees quantity: type: number description: Quantity of usage. Negative for refunds. taxRate: type: number description: Tax rate as decimal (0.10 = 10%) totalAmount: type: string description: >- Total amount (totalPrice + totalTax) in decimal dollars. Negative for refunds. totalPrice: type: string description: >- Total price (tax-exclusive) in decimal dollars. Negative for refunds. totalTax: type: string description: Total tax in decimal dollars. Negative for refunds. unitPrice: type: string description: Unit price in decimal dollars ResolvedItem: type: object description: >- An item a line was tagged with, together with its external accounting/tax codes. Deliberately narrower than the /v0/items Item resource: it carries what is needed to translate a line into a GL/SKU code, not the full record. required: - id - name - catalogId - archivedAt - externalReferences properties: id: $ref: '#/components/schemas/ItemId' name: type: string description: Human-readable item name catalogId: type: string nullable: true description: The product this item belongs to, for grouping lines by product archivedAt: type: string format: date-time nullable: true description: >- When this item was retired from the catalog. Archived items still resolve here — invoices that already reference them have to keep resolving — but cannot be tagged onto new pricing. Null while active. externalReferences: type: array description: >- The item's external codes, narrowed to the requested provider when one is given. An empty list means the item is not yet mapped for that provider — an actionable state, not an error. More than one may be returned for a single provider, and more than one of those may carry `isPrimary: true`: the uniqueness constraint runs the other way round (an external id is the primary reference of at most one item per merchant), so it does not reduce an item's references to one per provider. Entries are ordered newest first, tie-broken by id, so the order is stable across reads — but a consumer that needs exactly one code must choose deliberately rather than assume there is only one. items: $ref: '#/components/schemas/ExternalReference' Error: type: object required: - message properties: error: type: string description: >- Coarse HTTP error category (e.g. 'bad_request', 'forbidden'). Maps to the HTTP status code. message: type: string description: >- Human-readable error message. Clients must not parse this field programmatically. code: type: string examples: - TAX_NOT_ENABLED - PAYMENT_SESSION_EXPIRED description: >- Optional semantic business error code for machine-readable discrimination (e.g. 'TAX_NOT_ENABLED'). UPPER_SNAKE_CASE. Clients should check this field, not message. details: type: object description: Additional error details additionalProperties: true example: message: The requested resource was not found error: not_found ItemId: type: string pattern: ^itm_[a-zA-Z0-9]+$ description: Unique identifier for an item ExternalReference: type: object description: >- Links a Paygentic entity to a record in an external system such as Salesforce or NetSuite. required: - id - object - merchantId - entityType - entityId - provider - externalId - metadata - isPrimary - isDefault - createdAt - updatedAt properties: id: $ref: '#/components/schemas/ExternalReferenceId' object: type: string enum: - externalReference default: externalReference merchantId: $ref: '#/components/schemas/OrganizationId' entityType: $ref: '#/components/schemas/EntityType' entityId: type: string provider: $ref: '#/components/schemas/Provider' externalId: $ref: '#/components/schemas/ExternalId' externalLabel: type: string nullable: true metadata: type: object additionalProperties: true isPrimary: type: boolean isDefault: type: boolean createdAt: type: string format: date-time updatedAt: type: string format: date-time ExternalReferenceId: type: string pattern: ^xrf_[a-zA-Z0-9]+$ description: Unique identifier for an external reference EntityType: type: string enum: - item - customer description: The type of Paygentic entity this external reference points at Provider: type: string pattern: ^[a-z][a-z0-9_]*$ maxLength: 64 description: Lowercase snake_case provider identifier (e.g. `salesforce`, `netsuite`) ExternalId: type: string pattern: ^[a-zA-Z0-9_-]+$ maxLength: 255 description: >- Optional external identifier for cross-referencing with external systems. Alphanumeric characters, hyphens, and underscores only. responses: Forbidden: description: Forbidden - Request is understood but refused content: application/json: schema: $ref: '#/components/schemas/Error' InternalServerError: description: Internal Server Error - Something went wrong on the server side content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: BearerAuth: type: http scheme: bearer description: API key authentication ````