> ## 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 Line Items > List pending and invoiced line items for a subscription from the billing database. Returns exact fee amounts and estimated metered charges. ## OpenAPI ````yaml /openapi.json get /v2/invoices/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/lineItems: get: tags: - Invoices V2 summary: List Line Items description: >- List pending and invoiced line items for a subscription from the billing database. Returns exact fee amounts and estimated metered charges. operationId: listLineItems parameters: - in: query name: subscriptionId required: false schema: $ref: '#/components/schemas/SubscriptionId' description: >- Filter by subscription ID. At least one of subscriptionId or invoiceId must be provided. - in: query name: status schema: type: string enum: - pending - invoiced description: >- Filter by line item status. 'pending' returns items not yet on an invoice, 'invoiced' returns items already assigned to an invoice. Omit to return both. Cannot be combined with invoiceId — when filtering by invoice ID all statuses are returned. - in: query name: invoiceId schema: type: string pattern: ^inv_[a-zA-Z0-9]+$ description: >- Filter by invoice ID. When provided without subscriptionId, returns all line items for that invoice. At least one of subscriptionId or invoiceId must be provided. - 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. - in: query name: limit schema: type: integer default: 100 minimum: 1 maximum: 1000 description: Maximum number of line items to return - in: query name: offset schema: type: integer default: 0 minimum: 0 maximum: 10000 description: Number of line items to skip for pagination responses: '200': description: Paginated list of line items with summary content: application/json: schema: $ref: '#/components/schemas/LineItemsResponse' example: object: list data: - id: li_abc123 subscriptionId: sub_xyz789 priceId: price_fee_001 invoiceId: null type: fee status: pending displayName: Monthly Platform Fee description: null currency: USD periodStart: '2024-01-01T00:00:00.000Z' periodEnd: '2024-02-01T00:00:00.000Z' invoiceAt: '2024-01-01T00:00:00.000Z' calculatedAt: null quantity: '1' unitPrice: '29.99' meteredQuantity: null paymentTerm: in_advance subtotal: '29.99' total: '29.99' createdAt: '2024-01-01T00:00:00.000Z' updatedAt: '2024-01-01T00:00:00.000Z' totalCount: 1 summary: feeSubtotal: '29.99' meteredEstimatedSubtotal: '0.00' currency: USD '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' components: schemas: SubscriptionId: type: string pattern: ^sub_[a-zA-Z0-9]+$ description: Unique identifier for a subscription Provider: type: string pattern: ^[a-z][a-z0-9_]*$ maxLength: 64 description: Lowercase snake_case provider identifier (e.g. `salesforce`, `netsuite`) LineItemsResponse: type: object required: - object - data - totalCount - summary properties: object: type: string enum: - list description: The object type data: type: array description: Array of line items items: $ref: '#/components/schemas/LineItem' 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 to any invoice as a whole — combine the collections across pages for a complete 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' totalCount: type: integer description: Total number of matching line items summary: $ref: '#/components/schemas/LineItemsSummary' description: Aggregate summary of line item amounts LineItem: type: object required: - id - subscriptionId - customerId - type - status - displayName - currency - periodStart - periodEnd - invoiceAt - unitPrice - createdAt - updatedAt properties: id: type: string description: The line item ID subscriptionId: type: string description: The subscription this line item belongs to customerId: type: string description: The customer ID that owns this line item 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. 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. `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. invoiceId: type: string nullable: true description: The invoice ID if this item has been invoiced type: type: string enum: - fee - metered - manual - discount - adjustment description: >- The type of line item. 'discount' and 'adjustment' line items have negative subtotal/total amounts: 'discount' is a grant discount, 'adjustment' is a discount agreed on the subscription. status: type: string enum: - pending - invoiced description: Whether this item is pending or already on an invoice displayName: type: string description: Human-readable label shown on the invoice description: type: string nullable: true description: Optional longer description currency: type: string description: ISO 4217 currency code (e.g., USD) periodStart: type: string format: date-time description: Start of the billing period (inclusive) periodEnd: type: string format: date-time description: End of the billing period (exclusive) invoiceAt: type: string format: date-time description: When this line item should be collected into an invoice calculatedAt: type: string format: date-time nullable: true description: When metered quantity was last computed quantity: type: string nullable: true description: Units sold. Null for metered lines until invoice close unitPrice: type: string description: Price per unit in invoice currency meteredQuantity: type: string nullable: true description: Raw metered usage. Null for fee/manual lines usageDiscountIds: type: array items: type: string description: >- The subscription adjustments of type `usageDiscount` that reduced this line's billable `quantity`. Empty for every other line. Where this is non-empty, `quantity` is below `meteredQuantity` because an operator waived units, rather than because a grant covered them. paymentTerm: type: string enum: - in_advance - in_arrears - null nullable: true description: >- When the line falls due relative to the window it covers. A fee line carries its price's term; a metered line is stamped `in_arrears`, though metered rows predating that rule carry `null`. Manual, grant-discount and adjustment lines are billed on no term of their own and are `null`. `null` is listed in the enum as well as via `nullable` because OpenAPI 3.0 validators check the enum independently — `nullable: true` alone does not admit it, and createLineItem (which always returns null here) was emitting a schema-violating body. subtotal: type: string description: >- quantity × unitPrice, before discounts and taxes. For prorated lines, may differ from `quantity × unitPrice` by display precision; subtotal is the authoritative billed amount. Defaults to '0.00' when not yet calculated. taxesTotal: type: string nullable: true description: >- Total tax amount for this line item in decimal format. Null until invoice calculation is complete total: type: string description: >- Final total after discounts and taxes. Defaults to '0.00' when not yet calculated createdAt: type: string format: date-time description: When the line item was created updatedAt: type: string format: date-time description: When the line item was last updated estimatedMeteredQuantity: type: string nullable: true description: >- Real-time estimated metered usage quantity. Only present for type=metered items during an active billing period. Null for fee/manual items or when estimation is unavailable. estimatedSubtotal: type: string nullable: true description: >- Real-time estimated subtotal based on current metered usage. Only present for type=metered items during an active billing period. Null for fee/manual items or when estimation is unavailable. 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' LineItemsSummary: type: object required: - feeSubtotal - meteredEstimatedSubtotal - currency properties: feeSubtotal: type: string description: Sum of fee items with known subtotals in decimal format meteredEstimatedSubtotal: type: string description: Sum of estimated metered amounts in decimal format currency: type: string description: ISO 4217 currency code 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' Unauthorized: description: Unauthorized - Authentication failed or user does not have permissions content: application/json: schema: $ref: '#/components/schemas/Error' 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 ````