> ## 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. # Get Line Items > Get paginated line items for an invoice ## OpenAPI ````yaml /openapi.json get /v2/invoices/{id}/lineItems 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/{id}/lineItems: get: tags: - Invoices V2 summary: Get Line Items description: Get paginated line items for an invoice operationId: getInvoiceLineItems parameters: - in: path name: id required: true schema: type: string description: The invoice ID - in: query name: limit schema: type: integer default: 100 minimum: 1 maximum: 1000 description: Maximum number of line items to return - in: query name: pageToken schema: type: string description: >- Opaque pagination token to fetch the next page of results, taken from a previous response's nextPageToken. Do not construct or parse this value. - in: query name: expand schema: type: string description: >- Comma-separated list of fields to expand. Supports: items — resolves each returned line's item and that item's external accounting codes into an `items` collection, so a line can be translated to a GL/SKU code without a second call. - in: query name: provider schema: $ref: '#/components/schemas/Provider' description: >- Narrows which external references are returned per item when expand=items. Matched exactly against the provider stored on the reference (e.g. accountsiq); there is no allowlist of known providers, but the value must satisfy the same format every stored provider does, so a malformed one is rejected rather than answered with an empty result that reads as "nothing is mapped". It never removes lines or items: an item with no reference for this provider comes back with an empty list, so unmapped SKUs stay visible. Ignored when the items expansion is not requested. responses: '200': description: Paginated list of invoice line items content: application/json: schema: $ref: '#/components/schemas/InvoiceLineItemsResponse' example: invoiceId: inv_r1s2t3u4v5w6x7y8 lineItems: - eventType: usage eventId: usg_a1b2c3d4e5f6g7h8 eventSourceId: bm_l5m6n7o8p9q0r1s2 invoiceDisplayName: Claude Token Consumption lineItemType: charge meterEventId: me_x9y0z1a2b3c4d5e6 metricDescription: Language model token consumption metricName: Token Usage metricUnit: tokens quantity: 2500 taxRate: 0.085 totalAmount: '0.05425' totalPrice: '0.05' totalTax: '0.00425' unitPrice: '0.00002' - eventType: fee eventId: fee_b2c3d4e5f6g7h8i9 eventSourceId: fee_h3i4j5k6l7m8n9o0 invoiceDisplayName: Platform Fee meterEventId: '' metricDescription: Monthly platform fee metricName: Platform Fee metricUnit: charge quantity: 1 taxRate: 0.1 totalAmount: '5.50' totalPrice: '5.00' totalTax: '0.50' unitPrice: '5.00' nextPageToken: null totalCount: 3 '400': $ref: '#/components/responses/BadRequest' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' components: schemas: Provider: type: string pattern: ^[a-z][a-z0-9_]*$ maxLength: 64 description: Lowercase snake_case provider identifier (e.g. `salesforce`, `netsuite`) InvoiceLineItemsResponse: type: object required: - invoiceId - lineItems - totalCount 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 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 ValidationError: type: object required: - message - errors properties: error: type: string enum: - validation_error default: validation_error description: Error type indicating validation failure message: type: string description: Human-readable error message errors: type: array items: type: object properties: field: type: string description: The field that failed validation message: type: string description: Validation error message for this field code: type: string description: Validation error code required: - field - message description: Array of field-specific validation errors example: message: Validation failed error: validation_error errors: - field: email message: Invalid email format code: invalid_format 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 OrganizationId: type: string pattern: ^org_[a-zA-Z0-9]+$ description: Unique identifier for an organization EntityType: type: string enum: - item - customer description: The type of Paygentic entity this external reference points at 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: BadRequest: description: >- Bad Request - The request could not be understood or was missing required parameters content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/ValidationError' Forbidden: description: Forbidden - Request is understood but refused content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: Not Found - The requested resource could not be found 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 ````