> ## 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. # Update ## OpenAPI ````yaml /openapi.json patch /v0/plans/{id} openapi: 3.1.0 info: title: Paygentic API version: 0.1.0 description: > The Paygentic API provides a comprehensive platform for building and scaling monetization infrastructure. ## Authentication All API requests require authentication using an API key passed in the `Authorization` header: ``` Authorization: Bearer YOUR_API_KEY ``` ## Base URL All API requests should be made to: ``` https://api.paygentic.io/v0 ``` contact: name: Paygentic Support email: support@paygentic.io license: name: Proprietary servers: - url: https://api.paygentic.io description: Production API - url: https://api.sandbox.paygentic.io description: Sandbox API security: - BearerAuth: [] tags: - name: Customers description: >- A `Customer` is an entity connected to a `Merchant` via a `Subscription`. This represents the merchant-facing perspective of `Consumers` who purchase their `Products`. - name: Billable Metrics description: >- A `Billable Metric` defines a measurable quantity tied to a `Product`'s consumption. Each metric stores details including its label, an explanatory description, and measurement units. - name: Grants description: >- Grants credit a customer's metered entitlement balance. Merchants can create grants directly or void existing ones. Use `GET /v1/entitlements?customerId={id}` or `GET /v1/entitlements?subscriptionId={id}` to find the metered entitlement `id` needed for these endpoints. - name: Features description: >- A `Feature` represents a specific capability or functionality provided by a `Product`. Features can be metered (usage-based), static (fixed allocation), or boolean (enabled/disabled). - name: Fees description: >- A `Fee` defines a recurring or one-time charge tied to a `Product`. Fees are linked to prices, and cadence is defined on the Price. - name: Plans description: >- A `Plan` links a collection of `Prices` to a `Product`. It functions as a pricing structure document for a particular feature set or service offering. - name: Prices description: >- A `Price` determines the monetary value for a single unit of a `Billable Metric`. Prices are exclusively grouped within a `Plan`. - name: Products description: >- A `Product` is an offering sold by a `Merchant`. It includes product metadata like title, summary, and pricing details. `Plans`, `Prices`, and `Subscriptions` are all associated with products. - name: Sources description: >- A `Source` is an external data provider capable of automatically creating usage events. Configuration occurs at the plan level, enabling data retrieval from third-party platforms such as Stripe to produce billable events. - name: Subscriptions description: >- A `Subscription` is a customer's commitment to purchase a `Product` following the terms of a `Plan` and its linked `Prices`. - name: Users description: >- A `User` is an entity granted access to an Organization's resources. All operations are performed by users. - name: Invoices V2 description: >- Invoice V2 operations supporting billing cycles organized by time periods. Warning: v0 invoice endpoints are no longer supported. - name: Revenue description: Revenue data from invoices and payments - name: Profitability description: Per-customer profitability summaries - name: Test Clocks description: >- Test clocks provide programmable time control to simulate subscription and billing scenarios during testing. - name: Events description: Ingest raw metering events that are processed by the meters service. - name: Payments description: >- Create and manage one-off payments. A payment represents a single charge that a merchant wants to collect from a customer. - name: Payment Sessions description: >- Handle payment session lifecycle and processing across various entity types including invoices and subscriptions - name: Costs description: >- A Cost represents the operational or infrastructure expense of serving customers for a given product. Costs are metered (driven by event-based usage) and are tracked in parallel with billable metrics to give merchants visibility into both revenue and cost per customer. - name: ExternalReferences description: >- An `ExternalReference` links a Paygentic entity (e.g. an `Item`) to a record in an external system such as Salesforce or NetSuite. Multiple external records may map to the same Paygentic entity, but each external id is the *primary* reference of at most one entity per merchant. - name: Items description: >- An `Item` is the canonical "thing you sell" that external-system mappings point at. It is fully decoupled from the billing `Product` and holds no pricing/plan/metering, and it is CRM/ERP agnostic — which providers map to it lives entirely in its `ExternalReference` rows. - name: MerchantIntegrations description: >- A `MerchantIntegration` records a merchant's connection to an external provider. One connection per `(merchant, provider)` — re-connecting upserts in place. - name: Approvals description: Submit, decide, cancel, and read maker-checker approvals. - name: Orders description: Manage Orders, their line items, and billing schedules. - name: Billing Schedules description: >- Owner-polymorphic billing schedules with intervals and staged invoice projections. A BillingSchedule belongs to exactly one Order or one Subscription (XOR). Cadence lives on ScheduleIntervals (cadence-on-the-line). paths: /v0/plans/{id}: parameters: - name: id in: path required: true description: The unique identifier of the plan schema: $ref: '#/components/schemas/PlanId' patch: tags: - Plans summary: Update operationId: updatePlan requestBody: required: true content: application/json: schema: type: object properties: billingCadence: type: string enum: - P1M - P3M - P1Y description: >- ISO 8601 duration for the billing period. Takes precedence over billingInterval when both are provided. billingInterval: type: string enum: - monthly - quarterly - yearly - annual description: >- Recurring billing period frequency. Sample values: 'monthly' for monthly billing, 'quarterly' for quarterly billing, 'yearly' for annual billing defaultTaxCode: type: string description: >- Default tax code for plan line items. Common values: 'eservice' (electronically supplied services), 'saas' (software as a service), 'consulting', 'ebook', 'standard', 'reduced', 'exempt'. Full list available via GET /tax/codes endpoint. defaultTaxRate: type: number description: >- Fallback tax rate (as percentage) if automatic tax calculation is unavailable description: type: string description: >- Plan details explaining included features and limits. Sample values: 'Claude API access with 500K tokens monthly allowance', 'Unlimited cloud storage plus real-time analytics tools', 'Complete machine learning infrastructure with GPU access', 'Flexible usage-based pricing with no monthly commitment' invoiceDisplayName: type: string description: >- Plan name shown on billing statements. Sample values: 'LLM API Basic Plan', 'Data Warehouse Business', 'ML Platform Enterprise', 'Pay-Per-Use Model' name: type: string description: >- Plan identifier visible to customers. Sample values: 'Basic Tier', 'Business Package', 'Enterprise Solution', 'Metered Billing', 'Free Tier', 'Premium Access' prices: type: array items: $ref: '#/components/schemas/schemas-PriceId' description: Array of price IDs to associate with this plan taxBehavior: type: string enum: - exclusive - inclusive description: >- Whether tax is added on top of the price (exclusive) or included in the price (inclusive) renewalReminderEnabled: type: boolean description: >- Whether to send renewal reminder emails to customers before their subscription renews renewalReminderDays: type: integer description: Number of days before renewal to send the reminder email minimum: 1 maximum: 30 billingAnchor: type: string format: date-time nullable: true description: >- ISO 8601 datetime reference point for billing period alignment. Must be in the past or present. Set to null to clear the anchor and revert to start-time-based anchoring. creditAllocations: type: array items: $ref: '#/components/schemas/PlanCreditAllocation' description: >- Credit-pool funding declarations for this plan. Each entry funds a distinct pricing unit's credit pool when a subscription to this plan activates: the allocated amount is minted as a credit grant on the customer's pool for that pricing unit, once at activation, or on a recurring basis only when that allocation explicitly sets recurrencePeriod. A plan may declare zero or more allocations; no two allocations on the same plan may target the same pricingUnitId. responses: '200': description: Plan updated successfully content: application/json: schema: $ref: '#/components/schemas/Plan' example: id: plan_f3g4h5i6j7k8l9m0 object: plan billingCadence: P1Y billingInterval: yearly createdAt: '2024-01-20T09:00:00Z' currency: USD defaultTaxCode: eservice defaultTaxRate: 8.5 description: Complete machine learning infrastructure with GPU access invoiceDisplayName: ML Platform Enterprise merchantId: org_n1o2p3q4r5s6t7u8 name: Enterprise Solution prices: - price_d7e8f9g0h1i2j3k4 productId: prod_v9w0x1y2z3a4b5c6 taxBehavior: exclusive updatedAt: '2024-03-01T15:30: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: PlanId: type: string pattern: ^plan_[a-zA-Z0-9]+$ description: Unique identifier for a plan schemas-PriceId: type: string pattern: ^price_[a-zA-Z0-9]+$ description: Unique identifier for a price PlanCreditAllocation: type: object required: - pricingUnitId - amount properties: pricingUnitId: $ref: '#/components/schemas/PricingUnitId' description: >- The pricing unit whose credit pool this allocation funds. Must belong to the plan's own merchant. amount: type: number exclusiveMinimum: 0 description: >- Number of credits minted into the customer's pool for this pricing unit each time the allocation is provisioned. Must be a positive number. recurrencePeriod: type: string description: >- ISO 8601 duration (e.g. 'P1M') controlling how often the allocation's credits are re-minted on the customer's pool. Recurrence is opt-in: when omitted, the allocation is minted once at subscription activation and never refills — even on a recurring plan. Set this field explicitly for credits that should replenish each period. Plan: type: object required: - id - object - name - billingCadence - billingInterval - currency - merchantId - productId - createdAt - updatedAt properties: id: $ref: '#/components/schemas/schemas-PlanId' object: type: string enum: - plan billingCadence: type: string enum: - P1M - P3M - P1Y description: ISO 8601 duration for the billing period. default: P1M billingInterval: type: string deprecated: true x-speakeasy-deprecation-message: 'Use billingCadence (ISO 8601 duration: P1M, P3M, P1Y) instead.' description: >- Deprecated. Human-readable billing period derived from billingCadence. Use billingCadence instead. createdAt: type: string format: date-time currency: type: string defaultTaxCode: type: string description: >- Default tax code for plan line items. Common values: 'eservice' (electronically supplied services), 'saas' (software as a service), 'consulting', 'ebook', 'standard', 'reduced', 'exempt'. Full list available via GET /tax/codes endpoint. defaultTaxRate: type: number description: >- Fallback tax rate (as percentage) if automatic tax calculation is unavailable deletedAt: type: string format: date-time description: type: string invoiceDisplayName: type: string merchantId: $ref: '#/components/schemas/OrganizationId' description: The merchant organization that owns this plan name: type: string paymentTerm: type: object properties: in_arrears: type: boolean instant: type: boolean prices: type: array items: $ref: '#/components/schemas/Price' productId: $ref: '#/components/schemas/ProductId' description: The product this plan belongs to taxBehavior: type: string enum: - exclusive - inclusive description: >- Whether tax is added on top of the price (exclusive) or included in the price (inclusive) updatedAt: type: string format: date-time walletNamespaceId: $ref: '#/components/schemas/WalletNamespaceId' renewalReminderEnabled: type: boolean description: >- Whether renewal reminder emails are enabled for subscriptions using this plan renewalReminderDays: type: integer description: Number of days before renewal to send the reminder email billingVersion: type: integer description: Billing engine version. Managed by Paygentic support. billingAnchor: type: string format: date-time nullable: true description: >- ISO 8601 datetime reference point for billing period alignment. Must be in the past or present at the time of creation or update. When set, all subscriptions created under this plan align their first billing period to the next recurrence of this anchor. Null means each subscription uses its own start time (hour-rounded) as the anchor. creditAllocations: type: array items: $ref: '#/components/schemas/PlanCreditAllocation' description: >- Credit-pool funding declarations for this plan. Each entry funds a distinct pricing unit's credit pool when a subscription to this plan activates: the allocated amount is minted as a credit grant on the customer's pool for that pricing unit, once at activation, or on a recurring basis only when that allocation explicitly sets recurrencePeriod. A plan may declare zero or more allocations; no two allocations on the same plan target the same pricingUnitId. PricingUnitId: type: string pattern: ^pu_[a-zA-Z0-9]+$ description: Unique identifier for a pricing unit schemas-PlanId: type: string pattern: ^plan_[a-zA-Z0-9]+$ description: Unique identifier for a plan OrganizationId: type: string pattern: ^org_[a-zA-Z0-9]+$ description: Unique identifier for an organization Price: type: object required: - id - object - merchantId - model - paymentTerm - invoiceDisplayName - properties - createdAt - updatedAt - quantity properties: id: $ref: '#/components/schemas/schemas-PriceId' object: type: string enum: - price default: price merchantId: $ref: '#/components/schemas/OrganizationId' description: >- The merchant organization that owns this price, derived from the associated fee or billable metric. billableMetricId: type: string feeId: type: string pattern: ^fee_[a-zA-Z0-9]+$ description: The unique identifier for the fee referred to by this price billingCadence: type: string nullable: true description: ISO 8601 duration for billing frequency (e.g., P1M for monthly) createdAt: type: string format: date-time currency: type: string description: type: string invoiceDisplayName: type: string model: type: string enum: - standard - dynamic - volume - percentage paymentTerm: type: string enum: - instant - in_arrears - in_advance properties: type: object additionalProperties: true unitAmount: type: string 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: type: integer minimum: 1 maximum: 1000000 default: 1 description: >- Quantity used when generating invoice line items for this price. Total per period = quantity × unitPrice. Only supported for fee prices; metered prices derive quantity from usage. Defaults to 1. ProductId: type: string pattern: ^prod_[a-zA-Z0-9]+$ description: Unique identifier for a product WalletNamespaceId: type: string description: Unique identifier for a wallet namespace 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 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 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 ````