> ## 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. # Edit Price Intervals > Adds, edits, or removes price intervals on the subscription. Use an add to override a plan price for a period. Use an edit to change unitPrice, baseQuantity, quantityTransitions, or endDate. Use a remove to delete an interval. To close a price, set endDate. To re-open it, set endDate to null. To send an interval from a GET response as an edit, remove kind from it. An edit with no changed field changes nothing. If you send an add again after a timeout, it fails with 409 because it overlaps the first add. Use GET to check the result. The request is rejected if it changes a billing period that already exists, leaves a gap or an overlap, or bills a one-off price more than once. ## OpenAPI ````yaml /openapi.json post /v0/subscriptions/{id}/intervals 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/subscriptions/{id}/intervals: post: tags: - Subscriptions summary: Edit Price Intervals description: >- Adds, edits, or removes price intervals on the subscription. Use an add to override a plan price for a period. Use an edit to change unitPrice, baseQuantity, quantityTransitions, or endDate. Use a remove to delete an interval. To close a price, set endDate. To re-open it, set endDate to null. To send an interval from a GET response as an edit, remove kind from it. An edit with no changed field changes nothing. If you send an add again after a timeout, it fails with 409 because it overlaps the first add. Use GET to check the result. The request is rejected if it changes a billing period that already exists, leaves a gap or an overlap, or bills a one-off price more than once. operationId: editSubscriptionIntervals parameters: - in: path name: id required: true schema: type: string description: The subscription ID requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/EditSubscriptionIntervalsRequest' example: edit: - id: spi_p9q0r1s2t3u4v5w6 unitPrice: '9.00' responses: '200': description: >- The price intervals after the changes. If the request changed nothing, unchanged is true. content: application/json: schema: $ref: '#/components/schemas/EditSubscriptionIntervalsResponse' example: intervals: - id: spi_p9q0r1s2t3u4v5w6 priceId: price_x7y8z9a0b1c2d3e4 priceKey: pk_m4n5o6p7q8r9s0t1 kind: plan_line planVersionId: pv_u2v3w4x5y6z7a8b9 unitPrice: '9.00' baseQuantity: '1' quantityTransitions: [] billingCadence: P1M billingMode: advance billDate: null startDate: '2024-02-01T14:45:30Z' endDate: null unchanged: false lineItems: created: 1 removed: 0 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '429': description: >- Another edit is in progress on this subscription. Retry after the time in the Retry-After header. content: application/json: schema: $ref: '#/components/schemas/Error' '500': $ref: '#/components/responses/InternalServerError' components: schemas: EditSubscriptionIntervalsRequest: type: object additionalProperties: false minProperties: 1 description: >- An add/edit/remove op set to apply to the subscription's price timeline. At least one operation is required. properties: add: type: array maxItems: 25 items: $ref: '#/components/schemas/SubscriptionIntervalAddOp' description: New override segments to add. edit: type: array maxItems: 25 items: $ref: '#/components/schemas/SubscriptionIntervalEditOp' description: Changes to existing intervals. remove: type: array maxItems: 25 items: $ref: '#/components/schemas/SubscriptionIntervalRemoveOp' description: Intervals to remove outright. EditSubscriptionIntervalsResponse: type: object properties: intervals: type: array description: >- The timeline's effective price intervals after applying the op set, ordered by start date. items: $ref: '#/components/schemas/SubscriptionInterval' unchanged: type: boolean description: True when the op set resolved to no change and nothing was written. lineItems: type: object properties: created: type: integer description: >- Number of distinct prices that gained a line item as this timeline edit was re-derived into billing. removed: type: integer description: >- Number of distinct prices whose future/uninvoiced line items were removed as this timeline edit was re-derived into billing. syncFailed: type: boolean description: >- True when the timeline edit was saved but the line-item re-derive failed. The edit is not rolled back, and the re-derive is retried automatically. Resubmitting the same request retries it sooner. required: - created - removed required: - intervals - unchanged - lineItems 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 SubscriptionIntervalAddOp: type: object additionalProperties: false description: >- Adds an interval. If the plan version has a line with this priceKey, the interval overrides that line. If not, send priceId. The interval then belongs to this subscription only and keeps the rate that you write. A plan version change does not carry it forward, so it stops billing at the version boundary. If a later plan version adds the same priceKey, the change is refused until the plan drops the key or the interval ends on or before the boundary. required: - priceKey - unitPrice - baseQuantity - billingCadence - billingMode - startDate properties: priceKey: type: string minLength: 1 description: >- The price line that this interval bills. Use a priceKey from the plan version. A new key must start with a lowercase letter or a digit, use only lowercase letters, digits, hyphens, and underscores, and have 64 characters or fewer. priceId: type: string description: >- The catalog price to bill. Required if priceKey is not on the plan version. If it is on the plan, omit this field or send the price of that line. The price must belong to your merchant account. planVersionId: type: string description: >- Optional. If the subscription is on a different plan version, the request fails with 409. unitPrice: type: string nullable: true description: >- Signed net unit price for each period, as a decimal string. Null bills the catalog price. For a subscription-only interval, null saves the current catalog price. baseQuantity: type: string description: Quantity at interval start, as a non-negative decimal string. quantityTransitions: type: array description: Step changes in quantity partway through the interval. items: type: object required: - effectiveDate - quantity properties: effectiveDate: type: string format: date-time quantity: type: string description: Non-negative decimal string. additionalProperties: false billingCadence: type: string description: ISO-8601 duration or 'one_off' billingMode: type: string enum: - advance - arrears billDate: type: string format: date-time nullable: true description: Required when billingCadence is 'one_off'; must be absent otherwise. startDate: type: string format: date-time endDate: type: string format: date-time nullable: true description: >- Null for an open-ended interval; when set, must be strictly after startDate. SubscriptionIntervalEditOp: type: object additionalProperties: false description: >- Edits an interval by id. You can change unitPrice, baseQuantity, quantityTransitions, and endDate. Other fields must match the current value if you send them. To bill a different priceId, remove the interval and add a new one. required: - id properties: id: type: string description: The interval being edited. unitPrice: type: string nullable: true description: >- Signed per-period net unit price as a decimal string. Set to null to revert to the catalog price. Omit to leave unchanged. baseQuantity: type: string description: >- Quantity at interval start, as a non-negative decimal string. Omit to leave unchanged. quantityTransitions: type: array description: >- Step changes in quantity partway through the interval. Omit to leave unchanged. items: type: object required: - effectiveDate - quantity properties: effectiveDate: type: string format: date-time quantity: type: string description: Non-negative decimal string. additionalProperties: false priceId: type: string description: Not editable. Must match the interval's current value if supplied. priceKey: type: string description: Not editable. Must match the interval's current value if supplied. planVersionId: type: string description: Not editable. Must match the interval's current value if supplied. billingCadence: type: string description: Not editable. Must match the interval's current value if supplied. billingMode: type: string enum: - advance - arrears description: Not editable. Must match the interval's current value if supplied. billDate: type: string format: date-time nullable: true description: Not editable. Must match the interval's current value if supplied. startDate: type: string format: date-time description: Not editable. Must match the interval's current value if supplied. endDate: type: string format: date-time nullable: true description: >- When the interval stops billing. Send a date on or inside one of the billing periods to close the price. Send null to re-open it. Omit to keep the current value. SubscriptionIntervalRemoveOp: type: object additionalProperties: false required: - id properties: id: type: string description: The interval being removed. SubscriptionInterval: type: object description: A price interval of the subscription. properties: id: type: string priceId: type: string description: The catalog price this interval bills. priceKey: type: string description: >- Identifies the price line. An override keeps the key of the plan price that it replaces. kind: type: string enum: - plan_line - subscription_owned description: >- plan_line if the plan version has a line with this priceKey. subscription_owned if it does not, so the interval belongs to this subscription only. After an add, check the kind. A mistyped priceKey creates a subscription_owned interval. planVersionId: type: string description: The plan version of this interval. unitPrice: type: string nullable: true description: >- Signed net unit price for each period, as a decimal string. Null means the interval bills the catalog price. baseQuantity: type: string description: Quantity at interval start, as a decimal string. quantityTransitions: type: array items: type: object required: - effectiveDate - quantity properties: effectiveDate: type: string format: date-time quantity: type: string billingCadence: type: string description: ISO-8601 duration or 'one_off' billingMode: type: string enum: - advance - arrears billDate: type: string format: date-time nullable: true description: >- The one-time date this interval bills on. Set iff billingCadence is 'one_off'; null for a recurring interval. startDate: type: string format: date-time endDate: type: string format: date-time nullable: true description: Null for an open-ended interval. required: - id - priceId - priceKey - kind - planVersionId - unitPrice - baseQuantity - quantityTransitions - billingCadence - billingMode - billDate - startDate - endDate 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' Conflict: description: Conflict - The request conflicts with the current state of the resource 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 ````