> ## 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 projected

> Returns the invoices that approving this pending subscription proposal now would raise, as a list of `Invoice` in the envelope `GET /v2/invoices/projected` answers. It is not that endpoint: it takes no `from` or `to`, and it prices an elapsed metered period as described below. Today `data` holds the first invoice only, with the lines and amounts approve would bill at the moment of this read, and it is empty when approving now would raise no invoice. `pagination.total` says whether anything is owed: 1 when it is and 0 when it is not, whatever the offset. Nothing is stored, and the content is as of this read: the clock, the plan, its prices and the customer can change it before approval. The tax and the total are estimates from stored tax rates, not the tax provider's calculation. Grant discounts are not applied. A metered period that has already elapsed shows at zero usage, or at a minimum quantity in force for that period. `subscriptionId` holds the proposal id, because no subscription exists yet, so `GET /v0/subscriptions/{id}` answers 404 for it. The invoice has status `PROJECTED` and an id that is the same on every read, but `GET /v2/invoices/{id}` answers 404 for it. Needs the `subscriptionProposals:read` permission. The preview refuses what approve would refuse, with approve's answer. A plan, plan version or customer that no longer exists answers 404. A pending proposal blocks deleting its plan and its customer, so this happens only when a delete runs at the same time. A proposal of another merchant answers 404, as an unknown one does. 409 carries a `code`: `SUBSCRIPTION_PROPOSAL_NOT_PENDING` for a proposal that is not `pending`; `SUBSCRIPTION_PROPOSAL_INVALID` when the proposal fails a check subscription create makes, with `details.code` the failed check's own code and `details.details` its details, each only when the check has one; `SUBSCRIPTION_PROPOSAL_DUPLICATE` when the customer already has a live subscription for the plan's product, with its id in `details.subscriptionId`.



## OpenAPI

````yaml /openapi.json get /v0/subscriptionProposals/{id}/projected
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: Subscription Proposals
    description: >-
      A `SubscriptionProposal` holds the values of a subscription until a person
      on your team approves or rejects it. Nothing is billed while it waits.
  - 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: Merchant Data
    description: Reset a merchant's data outside production
  - 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).
  - name: Webhooks
    description: >-
      Endpoints for setting up webhook integrations and administering webhook
      settings
  - name: Me
    description: 'The caller: who it is in its active organization and what it can do'
paths:
  /v0/subscriptionProposals/{id}/projected:
    get:
      tags:
        - Subscription Proposals
      summary: List projected
      description: >-
        Returns the invoices that approving this pending subscription proposal
        now would raise, as a list of `Invoice` in the envelope `GET
        /v2/invoices/projected` answers. It is not that endpoint: it takes no
        `from` or `to`, and it prices an elapsed metered period as described
        below. Today `data` holds the first invoice only, with the lines and
        amounts approve would bill at the moment of this read, and it is empty
        when approving now would raise no invoice. `pagination.total` says
        whether anything is owed: 1 when it is and 0 when it is not, whatever
        the offset. Nothing is stored, and the content is as of this read: the
        clock, the plan, its prices and the customer can change it before
        approval. The tax and the total are estimates from stored tax rates, not
        the tax provider's calculation. Grant discounts are not applied. A
        metered period that has already elapsed shows at zero usage, or at a
        minimum quantity in force for that period. `subscriptionId` holds the
        proposal id, because no subscription exists yet, so `GET
        /v0/subscriptions/{id}` answers 404 for it. The invoice has status
        `PROJECTED` and an id that is the same on every read, but `GET
        /v2/invoices/{id}` answers 404 for it. Needs the
        `subscriptionProposals:read` permission. The preview refuses what
        approve would refuse, with approve's answer. A plan, plan version or
        customer that no longer exists answers 404. A pending proposal blocks
        deleting its plan and its customer, so this happens only when a delete
        runs at the same time. A proposal of another merchant answers 404, as an
        unknown one does. 409 carries a `code`:
        `SUBSCRIPTION_PROPOSAL_NOT_PENDING` for a proposal that is not
        `pending`; `SUBSCRIPTION_PROPOSAL_INVALID` when the proposal fails a
        check subscription create makes, with `details.code` the failed check's
        own code and `details.details` its details, each only when the check has
        one; `SUBSCRIPTION_PROPOSAL_DUPLICATE` when the customer already has a
        live subscription for the plan's product, with its id in
        `details.subscriptionId`.
      operationId: listSubscriptionProposalProjectedInvoices
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The subscription proposal ID
        - 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
      responses:
        '200':
          description: The invoices approving the proposal now would raise, earliest first
          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
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: >-
            Approve would refuse: `SUBSCRIPTION_PROPOSAL_NOT_PENDING`,
            `SUBSCRIPTION_PROPOSAL_INVALID` or `SUBSCRIPTION_PROPOSAL_DUPLICATE`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionProposalConflict'
        '429':
          description: >-
            Too many requests. The allowance of the merchant for this operation
            is spent. Wait for the number of seconds in the retry-after header.
            Then send the request again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '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, 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)
        issuedAt:
          type: string
          format: date-time
          nullable: true
          description: >-
            When the invoice was issued, in the subscription's effective time
            (test-clock time on a test clock). Revenue and profitability windows
            count the invoice by this instant. Null until the invoice is issued.
        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 `null`, and never `paygentic`: an invoice whose document
            is withheld is not served the provider's in its place, because
            recording that link would mark the invoice as already served and
            stop a later repair rendering ours. Use it to tell a withheld
            invoice apart from one that simply has no document yet — both report
            pdfSource `null`, and only a withheld one names why. An invoice
            issued before Paygentic rendered every document can report pdfSource
            `tax_provider` with no reason, and needs no repair. Both an invoice
            with no document and 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
            - PROJECTED
          description: >-
            The current status of the invoice. PROJECTED is returned only by GET
            /v2/invoices/projected and is never the status of a stored 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
    SubscriptionProposalConflict:
      type: object
      required:
        - error
        - message
      description: A 409 of a proposal route. Branch on `code`, never on `message`.
      properties:
        requestId:
          $ref: '#/components/schemas/RequestId'
        error:
          title: SubscriptionProposalConflictErrorType
          type: string
          enum:
            - conflict
        message:
          type: string
        code:
          $ref: '#/components/schemas/SubscriptionProposalConflictCode'
        details:
          $ref: '#/components/schemas/SubscriptionProposalConflictDetails'
    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
        reason:
          $ref: '#/components/schemas/AuthorizationDenialReason'
        requiredPermissions:
          type: array
          items:
            type: string
          description: >-
            Present on a 403 from the authorization check. The permissions the
            caller needs for this request.
        requestId:
          $ref: '#/components/schemas/RequestId'
      example:
        message: The requested resource was not found
        error: not_found
    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
        provenance:
          $ref: '#/components/schemas/LineProvenance'
    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'
    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
        requestId:
          $ref: '#/components/schemas/RequestId'
      example:
        message: Validation failed
        error: validation_error
        errors:
          - field: email
            message: Invalid email format
            code: invalid_format
    RequestId:
      type: string
      description: >-
        Identifies this request in our logs. Include it when you contact
        support. Also sent in the `request-id` response header.
      examples:
        - 105445aa7843bc8bf206b12000100000
    SubscriptionProposalConflictCode:
      type: string
      enum:
        - SUBSCRIPTION_PROPOSAL_RESYNC_CONFLICT
        - SUBSCRIPTION_PROPOSAL_ALREADY_APPROVED
        - SUBSCRIPTION_PROPOSAL_NOT_PENDING
        - SUBSCRIPTION_PROPOSAL_CHANGED
        - SUBSCRIPTION_PROPOSAL_DUPLICATE
        - SUBSCRIPTION_PROPOSAL_INVALID
      x-speakeasy-unknown-values: allow
      description: >-
        Why a proposal route answered 409. `RESYNC_CONFLICT`: a re-sync changed
        a field a person amended; stop, a person rejects and the CRM sends
        again. `ALREADY_APPROVED`: the proposal is approved; stop.
        `NOT_PENDING`: the proposal is decided; stop. `CHANGED`: the proposal
        changed since it was read; read it again and retry. `DUPLICATE`: the
        customer already has a live subscription for the product; reject the
        proposal. `INVALID`: the proposal now fails a check of subscription
        create; amend or reject it. Open set: approve can pass on a conflict of
        subscription create with that conflict's own code, so treat any other
        code as an unhandled conflict.
    SubscriptionProposalConflictDetails:
      type: object
      additionalProperties: true
      description: What the conflict names. Which fields are set depends on `code`.
      properties:
        code:
          type: string
          description: >-
            On `SUBSCRIPTION_PROPOSAL_INVALID`, the failed check's own code,
            when it has one. On the other codes, the conflict's `code` again.
        details:
          type: object
          additionalProperties: true
          description: >-
            On `SUBSCRIPTION_PROPOSAL_INVALID`, the failed check's own details,
            when it has them.
        fields:
          type: array
          items:
            type: string
          description: >-
            On `SUBSCRIPTION_PROPOSAL_RESYNC_CONFLICT`, the fields that conflict
            with an amendment.
        subscriptionId:
          type: string
          description: >-
            On `SUBSCRIPTION_PROPOSAL_ALREADY_APPROVED`, the subscription the
            proposal created. On `SUBSCRIPTION_PROPOSAL_DUPLICATE`, the
            customer's live subscription for the product.
        status:
          type: string
          description: On `SUBSCRIPTION_PROPOSAL_NOT_PENDING`, the proposal's status.
        field:
          type: string
          description: >-
            On `SUBSCRIPTION_PROPOSAL_CHANGED` from approve's compare-and-set,
            `lockVersion`, the compared field.
        expected:
          type:
            - integer
            - 'null'
          description: >-
            On `SUBSCRIPTION_PROPOSAL_CHANGED` from approve's compare-and-set,
            the `lockVersion` the proposal holds.
        actual:
          type: integer
          description: >-
            On `SUBSCRIPTION_PROPOSAL_CHANGED` from approve's compare-and-set,
            the `lockVersion` approve read.
        entityType:
          type: string
        entityId:
          type: string
    AuthorizationDenialReason:
      type: string
      enum:
        - no_permission
        - insufficient_scope
        - not_member
      description: >-
        Present on a 403 from the authorization check. Says why access was
        refused: the caller has no role that grants the permission, the OAuth
        token lacks the scope, or the caller is not a member of the
        organization.
    LineProvenance:
      type: object
      description: >-
        How the line's amount before tax was calculated: a trace of one
        evaluation, saved when the invoice was calculated and fixed once it is
        issued. Returned only with `expand=lineProvenance`. Every field but
        `status` is present when `status` is `recorded`. Every number is a plain
        decimal string.
      required:
        - status
      properties:
        status:
          $ref: '#/components/schemas/LineProvenanceStatus'
        version:
          type: integer
          description: >-
            The format version. It changes only when a field is removed or
            renamed, or a field changes meaning. A new op, source type, price
            model, reason or label is not a new version.
        currency:
          type: string
          description: The currency of every amount in the trace.
        precision:
          $ref: '#/components/schemas/LineCalculationPrecision'
        period:
          $ref: '#/components/schemas/LineCalculationPeriod'
        calculatedAt:
          type: string
          format: date-time
          description: When the calculation ran.
        subscriptionId:
          type: string
          description: The subscription the line belongs to.
        inputs:
          $ref: '#/components/schemas/LineCalculationInputs'
        sources:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/LineCalculationSource'
          description: Every source a step or an input names, by key.
        steps:
          type: array
          items:
            $ref: '#/components/schemas/LineCalculationStep'
          description: >-
            The steps in the order they were applied. Each starts where the last
            step on the same value ended.
        notApplied:
          type: array
          items:
            $ref: '#/components/schemas/LineCalculationNotApplied'
          description: Rules in force for the line that did not change it, and why.
        result:
          $ref: '#/components/schemas/LineCalculationResult'
    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
    LineProvenanceStatus:
      type: string
      description: >-
        `recorded`: the trace is present. `notRecorded`: the line was calculated
        but has no saved trace, for example a line calculated before traces were
        saved (show "Calculation not recorded"). `pending`: the line's invoice
        has not been calculated yet. An open set, so it is a string rather than
        an enum: known values are `recorded`, `notRecorded`, `pending`, and new
        values may be added.
    LineCalculationPrecision:
      type: object
      required:
        - significantDigits
        - rounding
      properties:
        significantDigits:
          type: integer
        rounding:
          type: string
      description: >-
        The default arithmetic of every step. Any other rounding is an explicit
        `round` step.
    LineCalculationPeriod:
      type: object
      required:
        - start
        - end
      properties:
        start:
          type: string
          format: date-time
        end:
          type: string
          format: date-time
      description: The period the line bills.
    LineCalculationInputs:
      type: object
      required:
        - kind
      description: The values the evaluation started from.
      properties:
        kind:
          $ref: '#/components/schemas/LineCalculationInputsKind'
        quantity:
          $ref: '#/components/schemas/LineCalculationGiven'
        selector:
          $ref: '#/components/schemas/LineCalculationGiven'
        price:
          $ref: '#/components/schemas/LineCalculationInputPrice'
        amount:
          $ref: '#/components/schemas/LineCalculationGiven'
    LineCalculationSource:
      type: object
      required:
        - type
      description: >-
        Where a value came from: `ref`, a link that can break after the invoice
        is issued, and `asUsed`, the values the calculation read, which never
        change.
      properties:
        type:
          $ref: '#/components/schemas/LineCalculationSourceType'
        ref:
          type: object
          additionalProperties: true
          description: The ids that link to the resource.
        asUsed:
          type: object
          additionalProperties: true
          description: >-
            The values the calculation read from the resource. A `line` source
            has `amount`, and `unitPrice` where a step read the line's rate.
        reason:
          $ref: '#/components/schemas/LineCalculationStoredRowReason'
    LineCalculationStep:
      type: object
      required:
        - op
        - 'on'
        - in
        - out
        - params
        - source
      description: >-
        One step: the value it changed (`on`), the value before (`in`) and after
        (`out`), the rule's parameters, and the source of the rule. A reader
        that does not know an op shows it as "in → out, because source".
      properties:
        op:
          $ref: '#/components/schemas/LineCalculationOp'
        'on':
          type: string
          description: >-
            The value the step changes. `quantity`, `selector` (the quantity a
            volume band is chosen on), `price` and `amount` are reserved; other
            names may be added.
        in:
          anyOf:
            - $ref: '#/components/schemas/LineCalculationValue'
            - type: 'null'
          description: The value before the step. Null only on `evaluate`.
        out:
          $ref: '#/components/schemas/LineCalculationValue'
        params:
          type: object
          additionalProperties: true
          description: The parameters of the op. See `op`.
        source:
          type: string
          description: The key of the source in `sources` whose rule this is.
        inputsFrom:
          type: array
          items:
            $ref: '#/components/schemas/LineCalculationContribution'
          description: >-
            The other lines a group rule read, with each one's value and period
            share.
        trace:
          type: array
          items:
            type: object
            additionalProperties: true
          description: >-
            Reserved for an `evaluate` of a custom pricing function: the steps
            inside it, each of the same shape as a step. Free-form here so the
            schema does not refer to itself. Nothing produces it yet.
    LineCalculationNotApplied:
      type: object
      required:
        - source
        - reason
      properties:
        source:
          type: string
          description: The key of the rule's source in `sources`.
        reason:
          type: string
          description: >-
            Why the rule did not change the line, for example `within` or
            `notBinding`.
      description: A rule in force for the line that did not change it.
    LineCalculationResult:
      type: object
      required:
        - amount
        - quantity
        - unitPrice
      properties:
        amount:
          type: string
          description: The line's amount before tax.
        quantity:
          type:
            - string
            - 'null'
          description: The line's quantity.
        unitPrice:
          type:
            - string
            - 'null'
          description: >-
            The line's unit price. It can be rounded, so quantity times unit
            price can differ from the amount.
      description: Equal to the line's stored amount, quantity and unit price.
    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
        - subscriptionProposal
        - subscription
      x-speakeasy-unknown-values: allow
      description: >-
        The type of Paygentic entity this external reference points at.
        `subscriptionProposal` and `subscription` references link a subscription
        proposal, and the subscription its approval creates, to the CRM record
        they come from. They are read-only through these endpoints.
    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.
    LineCalculationInputsKind:
      type: string
      description: >-
        `priced`: a charge from a price, with `quantity`, `selector` and
        `price`. `fromLine`: a line whose base is another line's amount, with
        `amount`. `given`: an amount nobody priced on this run, with `amount`.
        An open set, so it is a string rather than an enum: known values are
        `priced`, `fromLine`, `given`, and new values may be added.
    LineCalculationGiven:
      type: object
      required:
        - value
        - source
      properties:
        value:
          type: string
          description: The value.
        source:
          type: string
          description: The key of the source in `sources` that stated it.
      description: A value the evaluation started from, and its source.
    LineCalculationInputPrice:
      type: object
      required:
        - fn
        - source
      properties:
        fn:
          $ref: '#/components/schemas/LineCalculationPriceFn'
        source:
          type: string
          description: The key of the source in `sources` that stated the price.
      description: '`priced` only: the price as a function, and its source.'
    LineCalculationSourceType:
      type: string
      description: >-
        `interval`: a subscription price interval. `price`: a catalog price.
        `meter`: a billable metric read directly. `entitlement`: the grant
        engine's reading of an entitlement. `grant`: a grant. `adjustment`: a
        subscription adjustment. `line`: another line on the invoice.
        `storedRow`: a figure the line already stored, with `reason`.
        `merchant`: an amount a merchant entered. `input` is reserved for a
        value from a system that is not a meter, with `ref` `name` and `eventId`
        and `asUsed` `value` and `unit`; nothing produces it yet. An open set,
        so it is a string rather than an enum: known values are `interval`,
        `price`, `meter`, `entitlement`, `grant`, `adjustment`, `line`,
        `storedRow`, `merchant`, and new values may be added.
    LineCalculationStoredRowReason:
      type: string
      description: >-
        `storedRow` only: why the stored figure stands. An open set, so it is a
        string rather than an enum: known values are `precedes_timeline`,
        `no_timeline`, `not_derived`, `no_covering_charge`, and new values may
        be added.
    LineCalculationOp:
      type: string
      description: >-
        `allow`: units a grant covered (`covered`). `clamp`: `min` and `max`,
        null when open. `scaleToBound`: a minimum or maximum applied to a group
        of lines by uniform scaling (`bound`, `side`, `measured`, `factor`).
        `setToBound`: a minimum applied to a group that measured zero (`bound`,
        `sumOfShares`). `prorate`: `fraction` of the period, with the `billed`
        and full (`of`) windows and the `basis`. `evaluate`: the one join of
        quantity and price into an amount (`quantity`, `selector`, `fn`,
        `applied`); its `in` is null. `cap`: `max` and `scope`; on an `invoice`
        cap also `total`, what the cap started at, and `usedBefore`, what
        earlier credits took from it. `replace`: a value set by a rule, with
        `reason`. `subtract`: `units`. `scale`: ordered `terms`, each `by`,
        `value` and `label`. A `subtract`, `clamp` or `scale` that did not use
        the envelope's precision says so in `arithmetic`: `float64` or
        `decimal120`. `round`: `scale` and `mode`. An open set, so it is a
        string rather than an enum: known values are `allow`, `clamp`,
        `scaleToBound`, `setToBound`, `prorate`, `evaluate`, `cap`, `replace`,
        `subtract`, `scale`, `round`, and new values may be added.
    LineCalculationValue:
      anyOf:
        - type: string
        - $ref: '#/components/schemas/LineCalculationPriceFn'
      description: A decimal string, or a price function.
    LineCalculationContribution:
      type: object
      required:
        - lineItemId
        - value
        - share
      properties:
        lineItemId:
          type: string
        value:
          type: string
        share:
          type:
            - string
            - 'null'
    LineCalculationPriceFn:
      type: object
      required:
        - model
      description: >-
        A price as a function from quantity to money. A new model may carry
        fields not listed here.
      properties:
        model:
          $ref: '#/components/schemas/LineCalculationPriceModel'
        rate:
          type: string
          description: '`unit`, `percentage`: the rate.'
        bands:
          type: array
          items:
            $ref: '#/components/schemas/LineCalculationPriceBand'
          description: '`volume` only: the bands in ascending order.'
        min:
          type:
            - string
            - 'null'
          description: '`percentage` only: the minimum charge, or null.'
        max:
          type:
            - string
            - 'null'
          description: '`percentage` only: the maximum charge, or null.'
        amount:
          type: string
          description: '`flat` only: the amount for the period.'
      additionalProperties: true
    LineCalculationPriceModel:
      type: string
      description: >-
        `unit`: `rate` per unit. `volume`: `bands`, each with `upTo` (null for
        the open band) and `rate`; one band prices every unit. `percentage`:
        `rate` as a fraction, with `min` and `max` charge or null. `flat`: one
        `amount`. `dynamic`: the quantity is already money. An open set, so it
        is a string rather than an enum: known values are `unit`, `volume`,
        `percentage`, `flat`, `dynamic`, and new values may be added.
    LineCalculationPriceBand:
      type: object
      required:
        - upTo
        - rate
      properties:
        upTo:
          type:
            - string
            - 'null'
        rate:
          type: string
  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

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.