> ## 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 > Retrieve a single invoice with real-time aggregates (for ACTIVE/CLOSING/CLOSED) or cached aggregates (for finalized invoices). Optionally include line items with expand=lineItems. ## OpenAPI ````yaml /openapi.json get /v2/invoices/{id} 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}: parameters: - name: id in: path required: true description: The unique identifier of the invoice schema: type: string get: tags: - Invoices V2 summary: Get description: >- Retrieve a single invoice with real-time aggregates (for ACTIVE/CLOSING/CLOSED) or cached aggregates (for finalized invoices). Optionally include line items with expand=lineItems. operationId: getInvoice parameters: - in: path name: id required: true schema: type: string description: The invoice ID - in: query name: expand schema: type: string description: >- Comma-separated list of fields to expand. Currently supports: lineItems - in: query name: lineItemsLimit schema: type: integer default: 100 minimum: 1 maximum: 1000 description: Page size for line items when expand=lineItems - in: query name: lineItemsPageToken schema: type: string description: Pagination token for line items when expand=lineItems responses: '200': description: Invoice details content: application/json: schema: $ref: '#/components/schemas/Invoice' example: id: inv_r1s2t3u4v5w6x7y8 autoApprove: true billingAnchor: '2024-02-01T00:00:00Z' billingCadence: P1M gracePeriodEnd: '2024-03-01T23:59:59Z' grandTotal: '1345.61' invoiceNumber: INV-2024-02-001 itemCount: 15 lineItems: null nextActionAt: null paidAmount: '0.00' paymentUrl: https://checkout.paygentic.com/invoice/inv_r1s2t3u4v5w6x7y8 pdfUrl: https://quaderno.io/invoices/12345.pdf periodEnd: '2024-02-29T23:59:59Z' periodStart: '2024-02-01T00:00:00Z' permalink: https://quaderno.io/invoices/12345 sequenceNumber: 2 status: ISSUED subscriptionId: sub_z9a0b1c2d3e4f5g6 subtotal: '1234.50' tax: actualTax: '111110000000' adjustmentNeeded: true difference: '1110000000' estimatedTax: '110000000000' reconciled: true reconciledAt: '2024-03-01T10:00:00Z' totalTax: '111.11' unpaidAmount: '1345.61' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' components: schemas: 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) properties: invoiceId: type: string description: The invoice ID lineItems: type: array description: Array of line items for this page items: $ref: '#/components/schemas/InvoiceLineItem' 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: Direct PDF download link for tax invoice 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 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' 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 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 responses: 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 ````