> ## Documentation Index > Fetch the complete documentation index at: https://docs.useaira.com/llms.txt > Use this file to discover all available pages before exploring further. # Update plan instance > Overrides the pricing and charges of a plan instance by creating a new plan instance version. ## OpenAPI ````yaml /api-reference/openapi.yaml put /v1/plan-instances/{id} openapi: 3.1.0 info: title: API Reference version: '1.0' description: Aira API Reference x-logo: url: https://static.useaira.com/images/airalogo.svg backgroundColor: '#FFFFFF' altText: Aira Logo servers: - url: https://api.useaira.com description: API base URL security: - ApiKey: [] paths: /v1/plan-instances/{id}: put: tags: - Plan Instances summary: Update plan instance description: >- Overrides the pricing and charges of a plan instance by creating a new plan instance version. parameters: - schema: type: string format: uuid in: path name: id required: true description: The unique identifier of the plan instance in our system. requestBody: content: application/json: schema: type: object properties: planCharges: type: array description: >- The full set of charges the plan instance will bill from now on, keyed by category. Replaces the existing charges entirely. items: type: object discriminator: propertyName: category oneOf: - type: object description: 'A fixed charge: bills a flat amount every cycle.' properties: category: description: 'Discriminator: fixed charge.' enum: - fixed name: type: string minLength: 1 description: >- Display name of the charge as it appears on invoices. Required when isCustomNameEnabled is true; otherwise the name follows the catalog item name. isCustomNameEnabled: type: boolean description: >- Whether name is customized for this charge. When false, the name follows the catalog item name. itemId: type: string format: uuid description: >- The unique identifier of the catalog item this charge bills. pricingModel: type: string description: >- Fixed and minimum_commitment charges always use fixed pricing. enum: - fixed pricing: type: object description: >- Fixed pricing: a flat amount billed every cycle. The only pricing available for fixed and minimum_commitment charges. properties: model: description: 'Discriminator: fixed pricing.' enum: - fixed amount: type: integer minimum: 0 description: >- The flat amount billed every cycle, in cents. For minimum_commitment charges, the minimum the plan is topped up to. required: - model - amount additionalProperties: false required: - category - itemId - isCustomNameEnabled - pricingModel - pricing additionalProperties: false allOf: - if: properties: isCustomNameEnabled: enum: - true then: required: - name - type: object description: >- A minimum commitment charge: tops the plan up to the configured amount when the cycle's consumption stays below it. A plan can have at most one. properties: category: description: 'Discriminator: minimum commitment charge.' enum: - minimum_commitment name: type: string minLength: 1 description: >- Display name of the charge as it appears on invoices. Required when isCustomNameEnabled is true; otherwise the name follows the catalog item name. isCustomNameEnabled: type: boolean description: >- Whether name is customized for this charge. When false, the name follows the catalog item name. itemId: type: string format: uuid description: >- The unique identifier of the catalog item this charge bills. pricingModel: type: string description: >- Fixed and minimum_commitment charges always use fixed pricing. enum: - fixed pricing: type: object description: >- Fixed pricing: a flat amount billed every cycle. The only pricing available for fixed and minimum_commitment charges. properties: model: description: 'Discriminator: fixed pricing.' enum: - fixed amount: type: integer minimum: 0 description: >- The flat amount billed every cycle, in cents. For minimum_commitment charges, the minimum the plan is topped up to. required: - model - amount additionalProperties: false required: - category - itemId - isCustomNameEnabled - pricingModel - pricing additionalProperties: false allOf: - if: properties: isCustomNameEnabled: enum: - true then: required: - name - type: object description: >- A usage-based charge: prices the consumption of a metered resource according to pricingModel. properties: category: description: 'Discriminator: usage-based charge.' enum: - usage_based name: type: string minLength: 1 description: >- Display name of the charge as it appears on invoices. Required when isCustomNameEnabled is true; otherwise the name follows the catalog item name. isCustomNameEnabled: type: boolean description: >- Whether name is customized for this charge. When false, the name follows the catalog item name. resourceId: type: string format: uuid description: >- The unique identifier of the metered resource whose usage the charge prices. pricingModel: type: string enum: - per_unit - per_package - percentage - tiered_per_unit - tiered_percentage - tiered_fixed - advanced description: >- How the charge is priced: per_unit (price per unit with optional included quantity), per_package (price per started package of units), percentage (basis points over a monetary base amount), tiered_per_unit / tiered_percentage / tiered_fixed (tier ladder where every tier uses that pricing type), or advanced (tier ladder mixing tier pricing types). Percentage-based models require a Currency-type resource. Always matches pricing.model. pricing: type: object description: >- Pricing configuration of a usage-based charge, keyed by model. Must match the charge's pricingModel. discriminator: propertyName: model oneOf: - type: object description: >- Per-unit pricing: every billable unit costs unitPrice, after deducting the included quantity. properties: model: description: 'Discriminator: per-unit pricing.' enum: - per_unit includedQuantity: type: integer minimum: 0 description: >- Optional number of units included at no charge before billing starts. unitPrice: type: string pattern: ^\d+(\.\d{1,6})?$ description: >- Price per unit, as a decimal currency-unit string (up to 6 decimal places). fixedAmount: type: integer minimum: 0 description: >- Optional flat amount billed every cycle alongside the usage, in cents. Rendered as a fixed-price sub-line item when greater than zero. minimumAmount: type: integer minimum: 0 description: >- Optional floor for the charge, in cents. When the cycle amount stays below it, a minimum-amount sub-line item tops the charge up to this value. required: - model - unitPrice additionalProperties: false - type: object description: >- Per-package pricing: billable units are charged per started package of packageSize units, after deducting the included quantity. properties: model: description: 'Discriminator: per-package pricing.' enum: - per_package includedQuantity: type: integer minimum: 0 description: >- Optional number of units included at no charge before billing starts. packageSize: type: integer minimum: 1 description: Number of resource units per package. packagePrice: type: string pattern: ^\d+(\.\d{1,6})?$ description: >- Price per package, as a decimal currency-unit string (up to 6 decimal places). fixedAmount: type: integer minimum: 0 description: >- Optional flat amount billed every cycle alongside the usage, in cents. Rendered as a fixed-price sub-line item when greater than zero. minimumAmount: type: integer minimum: 0 description: >- Optional floor for the charge, in cents. When the cycle amount stays below it, a minimum-amount sub-line item tops the charge up to this value. required: - model - packageSize - packagePrice additionalProperties: false - type: object description: >- Percentage pricing: a percentage taken over the monetary base amount consumed. Only valid for charges on Currency-type resources. properties: model: description: 'Discriminator: percentage pricing.' enum: - percentage percentageBps: type: integer minimum: 0 maximum: 10000 description: >- Percentage applied to the base amount, in basis points (1 basis point = 0.01%; 10000 = 100%). fixedAmount: type: integer minimum: 0 description: >- Optional flat amount billed every cycle alongside the usage, in cents. Rendered as a fixed-price sub-line item when greater than zero. minimumAmount: type: integer minimum: 0 description: >- Optional floor for the charge, in cents. When the cycle amount stays below it, a minimum-amount sub-line item tops the charge up to this value. required: - model - percentageBps additionalProperties: false - type: object description: >- Tiered per-unit pricing: units are priced by the tier ladder defined in the charge's tiers, every tier priced per unit. properties: model: description: 'Discriminator: tiered per-unit pricing.' enum: - tiered_per_unit tierMode: enum: - progressive - volume description: >- How the ladder applies: progressive prices each tier's band separately (graduated); volume prices all usage at the single tier containing the total. fixedAmount: type: integer minimum: 0 description: >- Optional flat amount billed every cycle alongside the usage, in cents. Rendered as a fixed-price sub-line item when greater than zero. minimumAmount: type: integer minimum: 0 description: >- Optional floor for the charge, in cents. When the cycle amount stays below it, a minimum-amount sub-line item tops the charge up to this value. required: - model - tierMode additionalProperties: false - type: object description: >- Tiered percentage pricing: the monetary base amount is priced by the tier ladder defined in the charge's tiers, every tier priced in basis points. Only valid for charges on Currency-type resources. properties: model: description: 'Discriminator: tiered percentage pricing.' enum: - tiered_percentage tierMode: enum: - progressive - volume description: >- How the ladder applies: progressive prices each tier's band separately (graduated); volume prices all usage at the single tier containing the total. fixedAmount: type: integer minimum: 0 description: >- Optional flat amount billed every cycle alongside the usage, in cents. Rendered as a fixed-price sub-line item when greater than zero. minimumAmount: type: integer minimum: 0 description: >- Optional floor for the charge, in cents. When the cycle amount stays below it, a minimum-amount sub-line item tops the charge up to this value. required: - model - tierMode additionalProperties: false - type: object description: >- Tiered fixed pricing: the tier containing the total usage bills its flat amount. Always volume mode. Usage beyond the last tier can be billed through unitOverage or percentageOverage (mutually exclusive); configuring one requires a bounded final tier. properties: model: description: 'Discriminator: tiered fixed pricing.' enum: - tiered_fixed tierMode: enum: - progressive - volume description: >- Must be volume for tiered fixed pricing: the single tier containing the total usage bills its flat amount. unitOverage: type: object description: >- Optional overage price for units beyond the last tier, for charges on Unit-type resources. Mutually exclusive with percentageOverage. properties: excessUnitPrice: type: string pattern: ^\d+(\.\d{1,6})?$ description: >- Price per unit beyond the last tier, as a decimal currency-unit string (up to 6 decimal places). required: - excessUnitPrice additionalProperties: false percentageOverage: type: object description: >- Optional overage percentage for the base amount beyond the last tier, for charges on Currency-type resources. Mutually exclusive with unitOverage. properties: excessPercentageBps: type: integer minimum: 0 maximum: 10000 description: >- Percentage applied to the base amount beyond the last tier, in basis points (1 basis point = 0.01%; 10000 = 100%). required: - excessPercentageBps additionalProperties: false fixedAmount: type: integer minimum: 0 description: >- Optional flat amount billed every cycle alongside the usage, in cents. Rendered as a fixed-price sub-line item when greater than zero. minimumAmount: type: integer minimum: 0 description: >- Optional floor for the charge, in cents. When the cycle amount stays below it, a minimum-amount sub-line item tops the charge up to this value. required: - model - tierMode not: required: - unitOverage - percentageOverage additionalProperties: false - type: object description: >- Advanced pricing: a tier ladder mixing tier pricing types (per unit, percentage, per package, flat). Also used for charges priced before single pricing models existed. properties: model: description: >- Discriminator: advanced (mixed-tier) pricing. enum: - advanced tierMode: enum: - progressive - volume description: >- How the ladder applies: progressive prices each tier's band separately (graduated); volume prices all usage at the single tier containing the total. fixedAmount: type: integer minimum: 0 description: >- Optional flat amount billed every cycle alongside the usage, in cents. Rendered as a fixed-price sub-line item when greater than zero. minimumAmount: type: integer minimum: 0 description: >- Optional floor for the charge, in cents. When the cycle amount stays below it, a minimum-amount sub-line item tops the charge up to this value. required: - model - tierMode additionalProperties: false tiers: type: array items: type: object description: >- Schema representing one tier of a tiered plan charge. Tiers form a contiguous ladder over the charge's usage; each tier prices the band between from and to. properties: from: type: integer minimum: 0 description: >- Lower bound of the tier band (inclusive), in resource units — or cents of the monetary base amount for percentage-priced tiers. The first tier starts at 0 or 1; each subsequent tier starts at the previous tier's to + 1. to: type: integer minimum: 0 nullable: true description: >- Upper bound of the tier band (inclusive), in the same unit as from. Null makes the final tier unbounded; a finite final bound is only allowed on tiered_fixed charges with an overage price configured. pricing: type: object description: >- How usage falling in this tier is priced, keyed by type: per_unit (price per unit), percentage (basis points over the base amount), per_package (price per started package), or flat (fixed amount for the band). discriminator: propertyName: type oneOf: - type: object description: >- Per-unit tier pricing: every unit in the tier band costs unitPrice. properties: type: description: 'Discriminator: per-unit tier pricing.' enum: - per_unit unitPrice: type: string pattern: ^\d+(\.\d{1,6})?$ description: >- Price per unit within the tier, as a decimal currency-unit string (up to 6 decimal places). fixedPrice: type: string pattern: ^\d+(\.\d{1,6})?$ nullable: true description: >- Optional flat fee billed on top when the tier applies, as a decimal currency-unit string. Null when the tier has no flat fee. required: - type - unitPrice - fixedPrice additionalProperties: false - type: object description: >- Percentage tier pricing: the base amount in the tier band is billed at a percentage in basis points. Only valid for charges on Currency-type resources. properties: type: description: 'Discriminator: percentage tier pricing.' enum: - percentage percentageBps: type: integer minimum: 0 maximum: 10000 description: >- Percentage applied to the base amount within the tier, in basis points (1 basis point = 0.01%; 10000 = 100%). fixedPrice: type: string pattern: ^\d+(\.\d{1,6})?$ nullable: true description: >- Optional flat fee billed on top when the tier applies, as a decimal currency-unit string. Null when the tier has no flat fee. required: - type - percentageBps - fixedPrice additionalProperties: false - type: object description: >- Per-package tier pricing: units in the tier band are charged per started package of packageSize units. properties: type: description: 'Discriminator: per-package tier pricing.' enum: - per_package packageSize: type: integer minimum: 1 description: Number of resource units per package. packagePrice: type: string pattern: ^\d+(\.\d{1,6})?$ description: >- Price per package, as a decimal currency-unit string (up to 6 decimal places). fixedPrice: type: string pattern: ^\d+(\.\d{1,6})?$ nullable: true description: >- Optional flat fee billed on top when the tier applies, as a decimal currency-unit string. Null when the tier has no flat fee. required: - type - packageSize - packagePrice - fixedPrice additionalProperties: false - type: object description: >- Flat tier pricing: usage falling in the tier band is billed a flat amount, regardless of the exact quantity. properties: type: description: 'Discriminator: flat tier pricing.' enum: - flat amount: type: string pattern: ^\d+(\.\d{1,6})?$ description: >- The flat amount billed for the tier, as a decimal currency-unit string (up to 6 decimal places). required: - type - amount additionalProperties: false required: - from - to - pricing additionalProperties: false description: >- The tier ladder of the charge, ordered from the lowest band to the highest. Required non-empty for tier-based pricing models (tiered_per_unit, tiered_percentage, tiered_fixed, advanced); must be empty otherwise. currencyUnitCode: type: string description: >- Code of the currency unit the charge's usage is denominated in, for tenants using the credits module. Defaults to BRL when omitted. examples: - BRL required: - category - resourceId - isCustomNameEnabled - pricingModel - pricing - tiers additionalProperties: false allOf: - if: properties: isCustomNameEnabled: enum: - true then: required: - name required: - planCharges additionalProperties: false required: true description: >- Schema for overriding the pricing of a plan instance. The provided charges replace the instance's full charge set and a new plan instance version is created. responses: '200': description: >- Schema representing a plan instance: a plan sold on a contract. The instance keeps its own versioned copy of the plan's charges, so its pricing can be overridden without affecting the plan or other contracts. content: application/json: schema: type: object properties: id: type: string format: uuid description: The unique identifier of the plan instance in our system. contractId: type: string format: uuid description: >- The unique identifier of the contract the plan instance belongs to. planId: type: string format: uuid description: >- The unique identifier of the plan this instance was created from. activePlanInstanceVersionId: type: string format: uuid description: >- The unique identifier of the plan instance version currently used for billing. activePlanVersionId: type: string format: uuid description: >- The unique identifier of the plan version the active plan instance version derives from. activePlanInstanceVersionReason: type: string enum: - created_from_plan_version - duplicated_from_contract - manual_override - readjustment - rollback description: >- Why the active plan instance version exists: created_from_plan_version (instantiated from the plan's version), duplicated_from_contract (copied when the contract was duplicated), manual_override (pricing overridden manually or through the API), readjustment (a percentage rate adjustment was applied), or rollback (rolled back to a previous version). status: type: string enum: - active - canceled - completed description: >- Current status of the plan instance: active (billed on the contract's cycles), canceled (interrupted before its end; no longer billed), or completed (ran through its end). plan: type: object description: >- Base properties of the plan this instance was created from. properties: id: type: string format: uuid description: The unique identifier for this plan. name: type: string minLength: 1 description: The name of the plan. description: type: string nullable: true description: Optional description of the plan. productId: type: string format: uuid description: The ID of the product this plan is associated with. required: - id - name - description - productId additionalProperties: false activePlanInstanceVersion: type: object description: >- The plan instance version currently used for billing, including its plan charges. properties: id: type: string format: uuid description: >- The unique identifier of the plan instance version in our system. planInstanceId: type: string format: uuid description: >- The unique identifier of the plan instance this version belongs to. planVersionId: type: string format: uuid description: >- The unique identifier of the plan version this instance version derives from. versionNumber: type: number minimum: 1 description: >- Sequential version number of the plan instance, starting at 1 and incremented on every pricing change. isActive: type: boolean description: >- Whether this is the version currently used for billing. Only one version of a plan instance is active at a time. planInstanceVersionReason: type: string enum: - created_from_plan_version - duplicated_from_contract - manual_override - readjustment - rollback description: >- Why this version was created: created_from_plan_version (instantiated from the plan's version), duplicated_from_contract (copied when the contract was duplicated), manual_override (pricing overridden manually or through the API), readjustment (a percentage rate adjustment was applied), or rollback (rolled back to a previous version). metadata: anyOf: - type: object description: >- Details of a version instantiated from a plan version. properties: reason: type: string enum: - created_from_plan_version description: >- Discriminator: version instantiated from a plan version. sourcePlanVersionId: type: string format: uuid description: >- The unique identifier of the plan version the instance version was instantiated from. required: - reason - sourcePlanVersionId additionalProperties: false - type: object description: >- Details of a version copied from another contract when the contract was duplicated. properties: reason: type: string enum: - duplicated_from_contract description: >- Discriminator: version copied during a contract duplication. sourceContractId: type: string format: uuid description: >- The unique identifier of the contract the plan instance was duplicated from. sourcePlanInstanceId: type: string format: uuid description: >- The unique identifier of the plan instance the version was duplicated from. required: - reason - sourceContractId - sourcePlanInstanceId additionalProperties: false - type: object description: >- Details of a version created by manually overriding the instance pricing (including updates through the API). properties: reason: type: string enum: - manual_override description: >- Discriminator: version created by a manual pricing override. previousPlanInstanceVersionId: type: string format: uuid description: >- The unique identifier of the plan instance version that was active before the override. required: - reason - previousPlanInstanceVersionId additionalProperties: false - type: object description: >- Details of a version created by a percentage rate adjustment. properties: reason: type: string enum: - readjustment description: >- Discriminator: version created by a rate adjustment. previousPlanInstanceVersionId: type: string format: uuid description: >- The unique identifier of the plan instance version that was active before the adjustment. percentage: type: string description: >- The percentage applied to the instance prices by the adjustment, as a decimal string (e.g. "5" raises prices by 5%). required: - reason - previousPlanInstanceVersionId - percentage additionalProperties: false - type: object description: >- Details of a version created by rolling the instance back to a previous version. properties: reason: type: string enum: - rollback description: 'Discriminator: version created by a rollback.' rolledBackFromPlanInstanceVersionId: type: string format: uuid description: >- The unique identifier of the plan instance version that was active before the rollback. required: - reason - rolledBackFromPlanInstanceVersionId additionalProperties: false - type: 'null' description: >- No creation details were recorded for this version. description: >- Details about how the version was created, keyed by reason (e.g. the source plan version, the previous version, or the readjustment percentage). Null when no details were recorded. planCharges: type: array items: type: object description: >- Schema representing a plan charge: one billable component of a plan, keyed by category. Fixed and minimum_commitment charges bill a flat amount per cycle; usage_based charges price the consumption of a metered resource. discriminator: propertyName: category oneOf: - type: object description: 'A fixed charge: bills a flat amount every cycle.' properties: category: type: string description: 'Discriminator: fixed charge.' enum: - fixed id: type: string format: uuid description: >- The unique identifier of the plan charge in our system. position: type: integer minimum: 0 description: >- Zero-based display position of the charge within the plan. itemId: type: string format: uuid description: >- The unique identifier of the catalog item this charge bills. Line items generated from the charge reference this item. productId: type: string format: uuid description: >- The unique identifier of the product the charge belongs to. name: type: string minLength: 1 description: >- Display name of the charge as it appears on invoices. isCustomNameEnabled: type: boolean description: >- Whether name was customized for this charge. When false, the name follows the resource or catalog item name. pricingModel: type: string description: >- Fixed and minimum_commitment charges always use fixed pricing. enum: - fixed pricing: type: object description: >- Fixed pricing: a flat amount billed every cycle. The only pricing available for fixed and minimum_commitment charges. properties: model: description: 'Discriminator: fixed pricing.' enum: - fixed amount: type: integer minimum: 0 description: >- The flat amount billed every cycle, in cents. For minimum_commitment charges, the minimum the plan is topped up to. required: - model - amount additionalProperties: false required: - id - position - itemId - productId - name - isCustomNameEnabled - category - pricingModel - pricing additionalProperties: false - type: object description: >- A minimum commitment charge: tops the plan up to the configured amount when the cycle's consumption stays below it. A plan can have at most one. properties: category: type: string description: 'Discriminator: minimum commitment charge.' enum: - minimum_commitment id: type: string format: uuid description: >- The unique identifier of the plan charge in our system. position: type: integer minimum: 0 description: >- Zero-based display position of the charge within the plan. itemId: type: string format: uuid description: >- The unique identifier of the catalog item this charge bills. Line items generated from the charge reference this item. productId: type: string format: uuid description: >- The unique identifier of the product the charge belongs to. name: type: string minLength: 1 description: >- Display name of the charge as it appears on invoices. isCustomNameEnabled: type: boolean description: >- Whether name was customized for this charge. When false, the name follows the resource or catalog item name. pricingModel: type: string description: >- Fixed and minimum_commitment charges always use fixed pricing. enum: - fixed pricing: type: object description: >- Fixed pricing: a flat amount billed every cycle. The only pricing available for fixed and minimum_commitment charges. properties: model: description: 'Discriminator: fixed pricing.' enum: - fixed amount: type: integer minimum: 0 description: >- The flat amount billed every cycle, in cents. For minimum_commitment charges, the minimum the plan is topped up to. required: - model - amount additionalProperties: false required: - id - position - itemId - productId - name - isCustomNameEnabled - category - pricingModel - pricing additionalProperties: false - type: object description: >- A usage-based charge: prices the consumption of a metered resource according to pricingModel. properties: category: type: string description: 'Discriminator: usage-based charge.' enum: - usage_based id: type: string format: uuid description: >- The unique identifier of the plan charge in our system. position: type: integer minimum: 0 description: >- Zero-based display position of the charge within the plan. itemId: type: string format: uuid description: >- The unique identifier of the catalog item this charge bills. Line items generated from the charge reference this item. productId: type: string format: uuid description: >- The unique identifier of the product the charge belongs to. name: type: string minLength: 1 description: >- Display name of the charge as it appears on invoices. isCustomNameEnabled: type: boolean description: >- Whether name was customized for this charge. When false, the name follows the resource or catalog item name. pricingModel: type: string enum: - per_unit - per_package - percentage - tiered_per_unit - tiered_percentage - tiered_fixed - advanced description: >- How the charge is priced: per_unit (price per unit with optional included quantity), per_package (price per started package of units), percentage (basis points over a monetary base amount), tiered_per_unit / tiered_percentage / tiered_fixed (tier ladder where every tier uses that pricing type), or advanced (tier ladder mixing tier pricing types). Percentage-based models require a Currency-type resource. Always matches pricing.model. pricing: type: object description: >- Pricing configuration of a usage-based charge, keyed by model. Must match the charge's pricingModel. discriminator: propertyName: model oneOf: - type: object description: >- Per-unit pricing: every billable unit costs unitPrice, after deducting the included quantity. properties: model: description: 'Discriminator: per-unit pricing.' enum: - per_unit includedQuantity: type: integer minimum: 0 description: >- Optional number of units included at no charge before billing starts. unitPrice: type: string pattern: ^\d+(\.\d{1,6})?$ description: >- Price per unit, as a decimal currency-unit string (up to 6 decimal places). fixedAmount: type: integer minimum: 0 description: >- Optional flat amount billed every cycle alongside the usage, in cents. Rendered as a fixed-price sub-line item when greater than zero. minimumAmount: type: integer minimum: 0 description: >- Optional floor for the charge, in cents. When the cycle amount stays below it, a minimum-amount sub-line item tops the charge up to this value. required: - model - unitPrice additionalProperties: false - type: object description: >- Per-package pricing: billable units are charged per started package of packageSize units, after deducting the included quantity. properties: model: description: 'Discriminator: per-package pricing.' enum: - per_package includedQuantity: type: integer minimum: 0 description: >- Optional number of units included at no charge before billing starts. packageSize: type: integer minimum: 1 description: Number of resource units per package. packagePrice: type: string pattern: ^\d+(\.\d{1,6})?$ description: >- Price per package, as a decimal currency-unit string (up to 6 decimal places). fixedAmount: type: integer minimum: 0 description: >- Optional flat amount billed every cycle alongside the usage, in cents. Rendered as a fixed-price sub-line item when greater than zero. minimumAmount: type: integer minimum: 0 description: >- Optional floor for the charge, in cents. When the cycle amount stays below it, a minimum-amount sub-line item tops the charge up to this value. required: - model - packageSize - packagePrice additionalProperties: false - type: object description: >- Percentage pricing: a percentage taken over the monetary base amount consumed. Only valid for charges on Currency-type resources. properties: model: description: 'Discriminator: percentage pricing.' enum: - percentage percentageBps: type: integer minimum: 0 maximum: 10000 description: >- Percentage applied to the base amount, in basis points (1 basis point = 0.01%; 10000 = 100%). fixedAmount: type: integer minimum: 0 description: >- Optional flat amount billed every cycle alongside the usage, in cents. Rendered as a fixed-price sub-line item when greater than zero. minimumAmount: type: integer minimum: 0 description: >- Optional floor for the charge, in cents. When the cycle amount stays below it, a minimum-amount sub-line item tops the charge up to this value. required: - model - percentageBps additionalProperties: false - type: object description: >- Tiered per-unit pricing: units are priced by the tier ladder defined in the charge's tiers, every tier priced per unit. properties: model: description: 'Discriminator: tiered per-unit pricing.' enum: - tiered_per_unit tierMode: enum: - progressive - volume description: >- How the ladder applies: progressive prices each tier's band separately (graduated); volume prices all usage at the single tier containing the total. fixedAmount: type: integer minimum: 0 description: >- Optional flat amount billed every cycle alongside the usage, in cents. Rendered as a fixed-price sub-line item when greater than zero. minimumAmount: type: integer minimum: 0 description: >- Optional floor for the charge, in cents. When the cycle amount stays below it, a minimum-amount sub-line item tops the charge up to this value. required: - model - tierMode additionalProperties: false - type: object description: >- Tiered percentage pricing: the monetary base amount is priced by the tier ladder defined in the charge's tiers, every tier priced in basis points. Only valid for charges on Currency-type resources. properties: model: description: >- Discriminator: tiered percentage pricing. enum: - tiered_percentage tierMode: enum: - progressive - volume description: >- How the ladder applies: progressive prices each tier's band separately (graduated); volume prices all usage at the single tier containing the total. fixedAmount: type: integer minimum: 0 description: >- Optional flat amount billed every cycle alongside the usage, in cents. Rendered as a fixed-price sub-line item when greater than zero. minimumAmount: type: integer minimum: 0 description: >- Optional floor for the charge, in cents. When the cycle amount stays below it, a minimum-amount sub-line item tops the charge up to this value. required: - model - tierMode additionalProperties: false - type: object description: >- Tiered fixed pricing: the tier containing the total usage bills its flat amount. Always volume mode. Usage beyond the last tier can be billed through unitOverage or percentageOverage (mutually exclusive); configuring one requires a bounded final tier. properties: model: description: 'Discriminator: tiered fixed pricing.' enum: - tiered_fixed tierMode: enum: - progressive - volume description: >- Must be volume for tiered fixed pricing: the single tier containing the total usage bills its flat amount. unitOverage: type: object description: >- Optional overage price for units beyond the last tier, for charges on Unit-type resources. Mutually exclusive with percentageOverage. properties: excessUnitPrice: type: string pattern: ^\d+(\.\d{1,6})?$ description: >- Price per unit beyond the last tier, as a decimal currency-unit string (up to 6 decimal places). required: - excessUnitPrice additionalProperties: false percentageOverage: type: object description: >- Optional overage percentage for the base amount beyond the last tier, for charges on Currency-type resources. Mutually exclusive with unitOverage. properties: excessPercentageBps: type: integer minimum: 0 maximum: 10000 description: >- Percentage applied to the base amount beyond the last tier, in basis points (1 basis point = 0.01%; 10000 = 100%). required: - excessPercentageBps additionalProperties: false fixedAmount: type: integer minimum: 0 description: >- Optional flat amount billed every cycle alongside the usage, in cents. Rendered as a fixed-price sub-line item when greater than zero. minimumAmount: type: integer minimum: 0 description: >- Optional floor for the charge, in cents. When the cycle amount stays below it, a minimum-amount sub-line item tops the charge up to this value. required: - model - tierMode not: required: - unitOverage - percentageOverage additionalProperties: false - type: object description: >- Advanced pricing: a tier ladder mixing tier pricing types (per unit, percentage, per package, flat). Also used for charges priced before single pricing models existed. properties: model: description: >- Discriminator: advanced (mixed-tier) pricing. enum: - advanced tierMode: enum: - progressive - volume description: >- How the ladder applies: progressive prices each tier's band separately (graduated); volume prices all usage at the single tier containing the total. fixedAmount: type: integer minimum: 0 description: >- Optional flat amount billed every cycle alongside the usage, in cents. Rendered as a fixed-price sub-line item when greater than zero. minimumAmount: type: integer minimum: 0 description: >- Optional floor for the charge, in cents. When the cycle amount stays below it, a minimum-amount sub-line item tops the charge up to this value. required: - model - tierMode additionalProperties: false resourceId: type: string format: uuid description: >- The unique identifier of the metered resource whose usage the charge prices. currencyUnit: type: object description: >- The currency unit the charge's usage is denominated in, for tenants using the credits module. Null when the charge does not consume credits. properties: id: type: string format: uuid description: >- The unique identifier of the currency unit in our system. name: type: string description: Display name of the currency unit. code: type: string description: >- Short code of the currency unit (e.g. BRL). examples: - BRL required: - id - name - code additionalProperties: false nullable: true tiers: type: array items: type: object description: >- Schema representing one tier of a tiered plan charge. Tiers form a contiguous ladder over the charge's usage; each tier prices the band between from and to. properties: id: type: string format: uuid description: >- The unique identifier of the tier in our system. position: type: integer minimum: 0 description: >- Zero-based position of the tier in the ladder, ordered from the lowest band to the highest. from: type: integer minimum: 0 description: >- Lower bound of the tier band (inclusive), in resource units — or cents of the monetary base amount for percentage-priced tiers. The first tier starts at 0 or 1; each subsequent tier starts at the previous tier's to + 1. to: type: integer minimum: 0 nullable: true description: >- Upper bound of the tier band (inclusive), in the same unit as from. Null makes the final tier unbounded; a finite final bound is only allowed on tiered_fixed charges with an overage price configured. pricing: type: object description: >- How usage falling in this tier is priced, keyed by type: per_unit (price per unit), percentage (basis points over the base amount), per_package (price per started package), or flat (fixed amount for the band). discriminator: propertyName: type oneOf: - type: object description: >- Per-unit tier pricing: every unit in the tier band costs unitPrice. properties: type: description: 'Discriminator: per-unit tier pricing.' enum: - per_unit unitPrice: type: string pattern: ^\d+(\.\d{1,6})?$ description: >- Price per unit within the tier, as a decimal currency-unit string (up to 6 decimal places). fixedPrice: type: string pattern: ^\d+(\.\d{1,6})?$ nullable: true description: >- Optional flat fee billed on top when the tier applies, as a decimal currency-unit string. Null when the tier has no flat fee. required: - type - unitPrice - fixedPrice additionalProperties: false - type: object description: >- Percentage tier pricing: the base amount in the tier band is billed at a percentage in basis points. Only valid for charges on Currency-type resources. properties: type: description: 'Discriminator: percentage tier pricing.' enum: - percentage percentageBps: type: integer minimum: 0 maximum: 10000 description: >- Percentage applied to the base amount within the tier, in basis points (1 basis point = 0.01%; 10000 = 100%). fixedPrice: type: string pattern: ^\d+(\.\d{1,6})?$ nullable: true description: >- Optional flat fee billed on top when the tier applies, as a decimal currency-unit string. Null when the tier has no flat fee. required: - type - percentageBps - fixedPrice additionalProperties: false - type: object description: >- Per-package tier pricing: units in the tier band are charged per started package of packageSize units. properties: type: description: 'Discriminator: per-package tier pricing.' enum: - per_package packageSize: type: integer minimum: 1 description: Number of resource units per package. packagePrice: type: string pattern: ^\d+(\.\d{1,6})?$ description: >- Price per package, as a decimal currency-unit string (up to 6 decimal places). fixedPrice: type: string pattern: ^\d+(\.\d{1,6})?$ nullable: true description: >- Optional flat fee billed on top when the tier applies, as a decimal currency-unit string. Null when the tier has no flat fee. required: - type - packageSize - packagePrice - fixedPrice additionalProperties: false - type: object description: >- Flat tier pricing: usage falling in the tier band is billed a flat amount, regardless of the exact quantity. properties: type: description: 'Discriminator: flat tier pricing.' enum: - flat amount: type: string pattern: ^\d+(\.\d{1,6})?$ description: >- The flat amount billed for the tier, as a decimal currency-unit string (up to 6 decimal places). required: - type - amount additionalProperties: false required: - id - position - from - to - pricing additionalProperties: false description: >- The tier ladder of the charge, ordered from the lowest band to the highest. Populated only for tier-based pricing models (tiered_per_unit, tiered_percentage, tiered_fixed, advanced); empty otherwise. required: - id - position - itemId - productId - name - isCustomNameEnabled - category - pricingModel - pricing - resourceId - currencyUnit - tiers additionalProperties: false description: The plan charges billed by this version. required: - id - planInstanceId - planVersionId - versionNumber - isActive - planInstanceVersionReason - metadata - planCharges additionalProperties: false required: - id - contractId - planId - activePlanInstanceVersionId - activePlanVersionId - activePlanInstanceVersionReason - status - plan - activePlanInstanceVersion additionalProperties: false '400': description: Error object returned to the client. content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error code: type: string description: A unique identifier for the type of error details: oneOf: - type: object additionalProperties: true - type: array description: >- Additional context about the error, such as invalid fields or constraints. Each endpoint may include specific error details in their documentation causations: type: array description: >- Optional array of error objects following the same structure as the parent error. Only present when there's a meaningful chain of related errors to expose items: type: object properties: message: type: string description: >- A human-readable description of the underlying error cause code: type: string description: A unique identifier for the type of underlying error details: type: object additionalProperties: true description: Additional context about the underlying error required: - message - code additionalProperties: false required: - code - message additionalProperties: false '404': description: Error object returned to the client when a resource is not found. content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error components: securitySchemes: ApiKey: type: apiKey description: API Key Authentication. name: X-API-KEY in: header ````