> ## 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 ## OpenAPI ````yaml /openapi.json get /v0/prices 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: /v0/prices: get: tags: - Prices summary: List operationId: listPrices parameters: - name: billableMetricId in: query required: false schema: $ref: '#/components/schemas/BillableMetricId' description: Filter prices by billable metric ID - name: merchantId in: query required: false schema: $ref: '#/components/schemas/OrganizationId' description: >- Filter prices by merchant organization ID. Matches prices reached via either a billable metric or a fee belonging to that merchant. Unlike the unfiltered listing, this includes prices whose billable metric or fee has been deleted — deleting a parent does not delete its prices, and they can still bill. Returns 404 if the merchant does not exist. - name: limit in: query schema: type: integer minimum: 1 maximum: 100 default: 10 description: Number of prices to return - name: offset in: query schema: type: integer minimum: 0 default: 0 description: Number of prices to skip responses: '200': description: List of prices content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/schemas-Price' pagination: type: object properties: limit: type: integer offset: type: integer total: type: integer example: data: - id: price_l5m6n7o8p9q0r1s2 object: price billableMetricId: bm_t3u4v5w6x7y8z9a0 createdAt: '2024-01-18T11:20:00Z' currency: USD description: Per-token pricing for Claude API invoiceDisplayName: Claude Token Consumption model: standard paymentTerm: in_arrears properties: unitPrice: '0.00002' unitAmount: '20000000' updatedAt: '2024-01-18T11:20:00Z' - id: price_b1c2d3e4f5g6h7i8 object: price billableMetricId: bm_j9k0l1m2n3o4p5q6 createdAt: '2024-02-10T13:45:00Z' currency: USD description: Volume pricing for storage capacity invoiceDisplayName: Storage Usage (GB) model: volume paymentTerm: in_arrears properties: tiers: - unitPrice: '5' upTo: '100' - unitPrice: '4' upTo: '500' - unitPrice: '3' upTo: null unitAmount: '50000000000' updatedAt: '2024-02-25T09:30:00Z' pagination: limit: 10 offset: 0 total: 2 '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: BillableMetricId: type: string pattern: ^bm_[a-zA-Z0-9]+$ description: Unique identifier for a billable metric OrganizationId: type: string pattern: ^org_[a-zA-Z0-9]+$ description: Unique identifier for an organization schemas-Price: type: object required: - id - object - merchantId - invoiceDisplayName - paymentTerm - properties - createdAt - updatedAt - quantity - tax properties: id: $ref: '#/components/schemas/PriceId' object: type: string enum: - price default: price billableMetricId: $ref: '#/components/schemas/BillableMetricId' feeId: type: string pattern: ^fee_[a-zA-Z0-9]+$ description: >- The unique identifier for the fee referred to by this price. Present when price is linked to a fee. pricingUnitId: $ref: '#/components/schemas/PricingUnitId' description: >- The pricing unit this price is denominated in (credits). Present when the price draws down a credit pool instead of charging real currency. merchantId: $ref: '#/components/schemas/OrganizationId' description: >- The merchant organization that owns this price, derived from the associated fee or billable metric. Present on single-price reads. billingCadence: type: string description: >- ISO 8601 duration. 'P0D' for one-time, 'P1M' for monthly, 'P1Y' for yearly. Required for fees, optional for billable metrics. Defaults to plan's billingCadence if not specified. nullable: true createdAt: type: string format: date-time invoiceDisplayName: type: string invoiceDisplayGroup: type: string description: >- Presentation only. Prices sharing this value, within one billing period, print as a single row on the rendered invoice PDF and are described by this string. Every member still bills its own line item on the ledger, this API and the compliance document. The combined row's rate is derived from the members' own rates. Requires the 'standard' pricing model. Sample values: 'Cross Border Fees', 'FX Fees' nullable: true model: $ref: '#/components/schemas/PriceModel' paymentTerm: type: string enum: - in_arrears - in_advance properties: $ref: '#/components/schemas/PriceProperties' updatedAt: type: string format: date-time features: type: array items: $ref: '#/components/schemas/PriceFeature' description: Features associated with this price grantDiscountEnabled: type: boolean default: false description: >- When true, grants applied to a subscription will discount usage charged by this price. Only supported for standard metered prices. isObligation: type: boolean default: false description: >- A fixed amount owed whole rather than a per-period rate. An obligation is not prorated over a partial first period: when a subscription starts before its billing anchor, no truncated stub is billed and the first charge is the full amount at the next anchor. An obligation also refuses an interval boundary that falls strictly inside one of its own billing periods, since part of an amount owed whole is not a thing to bill. Defaults to false, which is a rate and is today's behaviour for every price. Not supported on a metered price, whose amount resolves from usage at close. rateType: $ref: '#/components/schemas/RateType' default: amount tax: $ref: '#/components/schemas/PriceTax' quantity: $ref: '#/components/schemas/PriceQuantity' PriceId: type: string pattern: ^price_[a-zA-Z0-9]+$ description: Unique identifier for a price PricingUnitId: type: string pattern: ^pu_[a-zA-Z0-9]+$ description: Unique identifier for a pricing unit PriceModel: type: string enum: - standard - dynamic - volume - percentage x-speakeasy-unknown-values: allow description: >- Pricing model of a price as returned by the API. Includes the legacy models ('dynamic', 'percentage') retained for existing prices; 'standard' and 'volume' can be created (see PriceModelInput). PriceProperties: type: object oneOf: - title: StandardPriceProperties type: object description: Standard pricing model properties: unitPrice: type: string description: >- Per-unit cost in decimal format for fixed-rate pricing. Sample values: '0.00002' represents $0.00002 per token, '0.15' represents $0.15 per gigabyte stored, '0.05' represents $0.05 per API call. Per unit. Total per period = quantity × unitPrice; see the `quantity` field. A negative value defines a usage-scaled rebate: the line's subtotal is negative and reduces the invoice. A rebate never drives an invoice total below zero, so set rebate rates below the charges they offset. A negative unitPrice is only valid on a metered price (a billableMetricId is required — there is no usage to scale on a fee price) and cannot be combined with grantDiscountEnabled, a hard-limit feature, or a pricingUnitId. When a rebate and a charge price share a billable metric but attach to different features, they compute against different quantity bases: a price attached to a feature bills the overage against its allowance, while a featureless price bills the raw metered usage. That is a permitted configuration, not an error. Attach both to the same feature to bill them against one basis. required: - unitPrice - title: DynamicPriceProperties type: object description: Dynamic pricing model properties: maxPrice: type: string description: >- Upper limit of the price range for dynamic pricing. Sample values: '0.10' means $0.10 per token for large volumes at peak times minPrice: type: string description: >- Lower limit of the price range for dynamic pricing. Sample values: '0.01' means $0.01 per token for low volumes during off-peak hours required: - maxPrice - minPrice - title: VolumePriceProperties type: object description: Volume pricing model properties: tiers: type: array minItems: 1 description: >- Ordered ladder of bands. The band is selected by the period's total metered usage, and its rate applies to every billed unit. A band matches when the quantity is less than or equal to its `upTo`, and the first matching band wins; the previous band's `upTo` is the exclusive lower bound, and the first band's floor is 0. items: title: VolumeTier type: object required: - upTo - unitPrice properties: upTo: type: - string - 'null' description: >- Inclusive upper bound of the band, as a decimal string. Null on the last band only, which carries the remainder. Sample values: '100' bounds the band at 100 units, null leaves the top open. unitPrice: type: string description: >- Per-unit cost inside this band, as a decimal string, capped at 6 decimal places. Sample values: '5' represents $5 per unit, '0.004' represents $0.004 per unit. required: - tiers - title: PercentagePriceProperties type: object description: Percentage pricing model properties: maxCharge: type: string description: >- Ceiling amount limiting total charge regardless of percentage calculation. Sample values: '500.00' caps fees at $500 maximum, '2000.00' limits charges to $2000 per period minCharge: type: string description: >- Floor amount charged regardless of percentage calculation. Sample values: '5.00' ensures minimum $5 fee, '25.00' guarantees at least $25 per billing event percentage: type: string pattern: ^([0-9](\.[0-9]{1,4})?|10(\.0{1,4})?)$ description: >- Rate expressed as decimal between 0 and 10, supporting up to 4 decimal precision. Sample values: '0.03' represents 3%, '0.075' represents 7.5%, '1.10' represents 110% required: - percentage - minCharge - maxCharge PriceFeature: type: object required: - id - featureId - entitlementTemplate properties: id: type: string featureId: type: string entitlementTemplate: type: object additionalProperties: true description: >- The allowance this price declares for the feature. An empty object where the price attaches the feature without declaring one. feature: type: object properties: key: type: string name: type: string type: type: string enum: - metered - static - boolean RateType: type: string enum: - amount - proportion description: >- What properties.unitPrice is denominated in. 'amount' (the default) is an amount of the invoice currency for each unit metered, so the quantity is the multiplier. 'proportion' is the reverse: a dimensionless share of a currency-denominated quantity, so '0.02' is 2% and the invoice prints '2.00%'. Presentation only. Requires a standard metered price in real currency. PriceTax: type: object description: >- A price's tax declaration. Optional on write — a price that declares nothing is `IN_SCOPE`, and is billed and taxed exactly as it was before this object existed. Always present on read. Replaced as a whole on update: send the object to change it, omit it to leave it alone. required: - supplyScope properties: supplyScope: type: string enum: - IN_SCOPE - OUTSIDE_SCOPE description: >- Whether this price's money is consideration for a supply — the one tax fact only you can state, because it is settled when you agree the deal rather than derived from what was sold. `IN_SCOPE` (the default) is consideration: it enters the taxable amount, positive as a charge or negative as a reduction in the price of the supply it applies to. `OUTSIDE_SCOPE` money is not consideration for anything, so it does not change the taxable amount, carries no tax, does not appear on the tax document, and nets into the amount payable after tax. This means "not consideration for a supply" — it does NOT mean "a supply outside this jurisdiction": exports and place-of-supply answers are worked out from the addresses on the sale by the tax provider, and are never declared on a price. How a supply is then classified — standard, zero-rated, exempt — is the tax provider's determination and is not set here either. Omit the whole `tax` object to leave a price in scope; there is deliberately no schema default on this property, so that a misspelt key is refused rather than silently defaulted. outsideScopeLabel: type: string enum: - CASHBACK - null nullable: true description: >- What an `OUTSIDE_SCOPE` amount is called in the invoice totals, so the wording follows the declaration rather than being retyped per price. Required when `supplyScope` is `OUTSIDE_SCOPE`, and rejected otherwise. `CASHBACK` is the only value today, and a price declaring it must use the `standard` model and must not carry a positive `unitPrice` — a cashback is money paid back, not charged. PriceQuantity: type: integer minimum: 0 description: >- Quantity for invoice line items. Total per period = quantity × unitPrice. Only supported for fee prices; metered prices derive quantity from usage. Defaults to 1. 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 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 ````