> ## 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. # Create ## OpenAPI ````yaml /openapi.json post /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: post: tags: - Prices summary: Create operationId: createPrice requestBody: required: true content: application/json: schema: type: object required: - invoiceDisplayName - paymentTerm - properties properties: billableMetricId: $ref: '#/components/schemas/BillableMetricId' description: >- The unique identifier for the billable metric referred to by this price. Either billableMetricId or feeId must be provided. feeId: type: string pattern: ^fee_[a-zA-Z0-9]+$ description: >- The unique identifier for the fee referred to by this price. Either billableMetricId or feeId must be provided. pricingUnitId: $ref: '#/components/schemas/PricingUnitId' description: >- Denominate this metered price in a pricing unit (credits) instead of real currency. When set, the price draws down the customer's credit pool for that unit. Only valid on metered prices that carry a metered feature. Omit for a normal currency price. model: allOf: - $ref: '#/components/schemas/PriceModelInput' description: >- Pricing calculation model. Required for billable metrics, optional for fees (defaults to 'standard'). Only 'standard' is accepted; for percentage/revenue-share use 'standard' with a unit-price multiplier. Legacy prices using 'dynamic'/'volume'/'percentage' stay readable and billable but cannot be created. invoiceDisplayName: type: string description: >- Line item label shown on customer invoices. Sample values: 'Claude Token Consumption', 'Storage Usage (GB)', 'Inference API Calls', 'Image Generation Count', 'Training Compute Hours', 'Data Transfer (TB)' paymentTerm: type: string enum: - instant - in_arrears - in_advance description: >- Billing timing preference. For billable metrics: 'instant' (charges immediately) or 'in_arrears' (charges at period end). For fees: 'in_advance' (charges upfront) or 'in_arrears' (charges at period end). billingCadence: type: string description: >- ISO 8601 duration for recurring charges (e.g., 'P1M' for monthly, 'P1Y' for yearly) or 'P0D' for one-time charges. Required for fees, optional for billable metrics. Sample values: 'P0D' for one-time, 'P1M' for monthly recurring, 'P1Y' for yearly recurring nullable: true properties: $ref: '#/components/schemas/PriceProperties' feature: $ref: '#/components/schemas/PriceFeatureInput' description: Optional feature to associate 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. quantity: $ref: '#/components/schemas/PriceQuantity' default: 1 responses: '201': description: Price created successfully content: application/json: schema: $ref: '#/components/schemas/schemas-Price' example: 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: instant properties: unitPrice: '0.00002' unitAmount: '20000000' updatedAt: '2024-01-18T11:20:00Z' '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 PricingUnitId: type: string pattern: ^pu_[a-zA-Z0-9]+$ description: Unique identifier for a pricing unit PriceModelInput: type: string enum: - standard description: >- Pricing model accepted when creating or updating a price. Only 'standard' is creatable. Percentage-style and revenue-share pricing are expressed with 'standard' plus a unit-price multiplier (e.g. 10% ⇒ unitPrice '0.1'). The legacy 'dynamic', 'volume', and 'percentage' models remain billable and readable on existing prices but can no longer be created. PriceProperties: type: object oneOf: - 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. required: - unitPrice - 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 - type: object description: Volume pricing model properties: default: type: string description: Default value for volume pricing parameters: type: object additionalProperties: false required: - function - gradient - min - max properties: function: type: string enum: - linear description: Function used for volume pricing calculations gradient: type: string description: Gradient for volume pricing calculations max: type: string description: Maximum value for volume pricing min: type: string description: Minimum value for volume pricing required: - parameters - default - 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 PriceFeatureInput: type: object required: - featureId properties: featureId: type: string pattern: ^feat_[a-zA-Z0-9]+$ description: The feature to associate with this price entitlementTemplate: type: object additionalProperties: true description: Template for entitlement values when this feature is provisioned 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. schemas-Price: type: object required: - id - object - merchantId - invoiceDisplayName - paymentTerm - properties - createdAt - updatedAt - quantity 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 model: $ref: '#/components/schemas/PriceModel' paymentTerm: type: string enum: - instant - 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. quantity: $ref: '#/components/schemas/PriceQuantity' PriceId: type: string pattern: ^price_[a-zA-Z0-9]+$ description: Unique identifier for a price OrganizationId: type: string pattern: ^org_[a-zA-Z0-9]+$ description: Unique identifier for an organization 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 legacy models ('dynamic', 'volume', 'percentage') retained for existing prices; only 'standard' can be created (see PriceModelInput). PriceFeature: type: object required: - id - featureId - entitlementTemplate properties: id: type: string featureId: type: string entitlementTemplate: type: object additionalProperties: true feature: type: object properties: key: type: string name: type: string type: type: string enum: - metered - static - boolean 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 ````