> ## Documentation Index > Fetch the complete documentation index at: https://docs.paypal.ai/llms.txt > Use this file to discover all available pages before exploring further. # Update a plan by Code ## OpenAPI ````yaml /api-reference/ubb_openapi_inline.json put /plans/{plan_code} openapi: 3.0.1 info: title: Usage Based Billing API version: 1.0.0 description: An Orchestrator for Usage Based Billing and Payments servers: - url: https://api-m.sandbox.paypal.com/v1/commerce/billing security: - BearerAuth: - read - write tags: - name: Alerts description: API endpoints for managing subscription alerts - name: Events description: API endpoints for managing events - name: Metrics description: API endpoints for metrics and usage data - name: Merchant Activation description: API endpoint for merchant activation - name: Credit Notes description: API endpoints for credit notes management - name: Customers description: API endpoints for customer management - name: Invoices description: API endpoints for invoice management - name: Plans description: API endpoints for subscription plans - name: Subscriptions description: API endpoints for subscriptions - name: Wallets description: API endpoints for wallet management - name: Taxes description: API endpoints for tax management - name: Billing Entities description: API endpoints for billing entities - name: Features description: API endpoints for managing features and privileges - name: Entitlements description: API endpoints for managing plan and subscription entitlements paths: /plans/{plan_code}: put: tags: - Plans summary: Update a plan by Code operationId: UpdatePlanByCode parameters: - $ref: '#/components/parameters/plan_code' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PlanUpdateRequest' responses: '200': description: A plan object content: application/json: schema: $ref: '#/components/schemas/PlanUpdateResponse' example: status: 200 OK headers: Content-Type: application/json body: name: UBB Plan - Pro code: ubb_plan_1753837176 billing_cycle: WEEKLY description: Pro plan for pro UBB customers amount: value: 170 currency_code: USD trial_period: 0 pay_in_advance: true cascading_updates: true usage_based_charges: - id: fggdgd5c-31a6-4d74-b607-ac3915796ab9 metric_id: 92c9175c-31a6-4d74-b607-ac3915796ab9 charge_model: STANDARD properties: amount: '1.00' min_amount: value: 1 currency_code: USD minimum_commitment: amount: value: 100 currency_code: USD invoice_display_name: Minimum Commitment id: cc82edfd-8198-4942-bed8-fcd7afb5191e plan_code: ubb_plan_1753826420 created_at: '2025-07-31T08:41:19Z' updated_at: '2025-07-31T08:41:19Z' created_at: '2025-07-30T00:59:35Z' updated_at: '2025-07-31T08:41:19Z' id: 95de3538-3827-496b-89a0-120745360830 '400': $ref: '#/components/responses/BadRequest' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/InternalServerError' components: parameters: plan_code: name: plan_code in: path required: true description: The code of the plan schema: type: string example: Plan-Code-1758211957 schemas: PlanUpdateRequest: allOf: - $ref: '#/components/schemas/PlanRequest' - type: object properties: cascading_updates: description: >- Determines if changes made to the parent plan should be cascaded to the overridden plans in subscription type: boolean example: true usage_based_charges: type: array items: $ref: '#/components/schemas/UsageBasedChargeUpdateRequest' PlanUpdateResponse: allOf: - $ref: '#/components/schemas/Plan' - type: object properties: cascading_updates: description: >- Determines if changes made to the parent plan should be cascaded to the children plans type: boolean example: true updated_at: allOf: - $ref: '#/components/schemas/DateTimeWithZone' PlanRequest: type: object properties: name: type: string code: type: string billing_cycle: $ref: '#/components/schemas/BillingCycle' description: type: string amount: allOf: - $ref: '#/components/schemas/Amount' trial_period: type: integer pay_in_advance: type: boolean tax_codes: $ref: '#/components/schemas/TaxCodes' minimum_commitment: allOf: - $ref: '#/components/schemas/MinimumCommitmentRequest' UsageBasedChargeUpdateRequest: type: object required: - id - metric_id properties: id: type: string description: Unique identifier of the charge example: 1a901a90-1a90-1a90-1a90-1a901a901a90 metric_id: type: string description: Unique identifier of the metric charge_model: $ref: '#/components/schemas/ChargeModel' description: Defines the pricing model to calculate the charge tax_codes: $ref: '#/components/schemas/TaxCodes' properties: type: object description: Pricing thresholds that determine the charges min_amount: allOf: - $ref: '#/components/schemas/AmountNoCurrency' Plan: type: object properties: id: type: string description: >- Unique identifier of the plan. This ID is used internally to track the plan and cannot be modified. example: 1a901a90-1a90-1a90-1a540-1a901a901a90 name: type: string code: type: string billing_cycle: $ref: '#/components/schemas/BillingCycle' description: type: string amount: allOf: - $ref: '#/components/schemas/Amount' trial_period: type: integer pay_in_advance: type: boolean taxes: type: array description: List of tax entities configured for the plan. items: $ref: '#/components/schemas/TaxResponse' usage_based_charges: type: array items: $ref: '#/components/schemas/UsageBasedCharge' minimum_commitment: allOf: - $ref: '#/components/schemas/MinimumCommitment' created_at: allOf: - $ref: '#/components/schemas/DateTimeWithZone' DateTimeWithZone: type: string format: date-time description: Date and time in ISO 8601 format. example: '2023-10-01T12:00:00Z' Error: type: object properties: name: type: string debug_id: type: string message: type: string details: type: array items: $ref: '#/components/schemas/ErrorDetail' BillingCycle: type: string description: The billing cycle indicating how often the subscription is charged enum: - WEEKLY - MONTHLY - QUARTERLY - YEARLY x-enum-varnames: - WEEKLY - MONTHLY - QUARTERLY - YEARLY x-enum-descriptions: - Recurring billing occurs every week - Recurring billing occurs every month - Recurring billing occurs every three months - Recurring billing occurs once a year example: MONTHLY Amount: allOf: - $ref: '#/components/schemas/AmountNoCurrency' - type: object required: - currency_code properties: currency_code: $ref: '#/components/schemas/Currency' TaxCodes: type: array items: type: string description: List of unique codes used to identify taxes to be applied. example: - standard_vat MinimumCommitmentRequest: type: object description: Minimum commitment for this plan. required: - amount properties: amount: allOf: - $ref: '#/components/schemas/AmountNoCurrency' invoice_display_name: type: string description: >- Specifies the name that will be displayed on an invoice. If no value is set for this field, the default name will be used as the display name. example: Minimum Commitment (C1) tax_codes: $ref: '#/components/schemas/TaxCodes' ChargeModel: type: string description: The pricing model applied to this charge enum: - STANDARD - GRADUATED - PACKAGE - PERCENTAGE - VOLUME x-enum-varnames: - STANDARD - GRADUATED - PACKAGE - PERCENTAGE - VOLUME x-enum-descriptions: - Standard pricing model where a fixed amount is charged per unit - >- Graduated pricing model where the price per unit decreases as the quantity increases - >- Package pricing model where a fixed price is charged for a set of units - >- Percentage pricing model where a percentage of a base amount is charged - >- Volume-based pricing model where the price varies based on the total volume consumed example: GRADUATED default: STANDARD AmountNoCurrency: type: object required: - value properties: value: type: number format: decimal description: >- The amount value in the corresponding currency unit (e.g., two decimals for USD, no decimals for JPY). example: 120.35 minimum: 0 nullable: false default: 0 TaxResponse: description: >- Represents a customizable tax rate that can be applied to invoices and fees type: object allOf: - $ref: '#/components/schemas/TaxBase' - type: object properties: code: $ref: '#/components/schemas/TaxCode' id: type: string format: uuid description: Unique identifier of the tax example: 1a901a90-1a90-1a90-1a90-1a901a901a90 created_at: allOf: - $ref: '#/components/schemas/DateTimeWithZone' - description: >- The effective start date of the subscription; can be past, current, or future. Date must be provided in ISO 8601 format example: '2025-06-01T00:00:00Z' UsageBasedCharge: type: object required: - id - metric_id properties: id: type: string description: Unique identifier of the charge example: 1a901a90-1a90-1a90-1a90-1a901a901a90 metric_id: type: string description: Unique identifier of the metric charge_model: $ref: '#/components/schemas/ChargeModel' description: Defines the pricing model to calculate the charge properties: type: object description: Pricing thresholds that determine the charges taxes: type: array description: List of tax entities configured for the usage based charge. items: $ref: '#/components/schemas/TaxResponse' min_amount: allOf: - $ref: '#/components/schemas/Amount' MinimumCommitment: allOf: - $ref: '#/components/schemas/MinimumCommitmentBase' - type: object properties: id: type: string format: uuid description: Unique identifier of the minimum commitment, created by Lago. example: 1a901a90-1a90-1a90-1a90-1a901a901a90 plan_code: type: string example: premium description: >- The unique code representing the plan to be attached to the customer. created_at: type: string format: date-time description: >- The date and time when the minimum commitment was created. It is expressed in UTC format according to the ISO 8601 datetime standard. This field provides the timestamp for the exact moment when the minimum commitment was initially created. example: '2022-04-29T08:59:51Z' updated_at: type: string format: date-time description: >- The date and time when the minimum commitment was updated. It is expressed in UTC format according to the ISO 8601 datetime standard. This field provides the timestamp for the exact moment when the minimum commitment was initially created. example: '2022-04-29T08:59:51Z' ErrorDetail: type: object properties: field: type: string value: type: string location: type: string issue: type: string description: type: string Currency: type: string description: Currency code in ISO 4217 format. example: USD minLength: 3 maxLength: 3 pattern: ^[A-Z]{3}$ TaxBase: description: Base schema for tax request/response objects type: object required: - name properties: name: type: string description: Name of the tax example: TVA rate: type: string pattern: >- ^(?!0+(?:\.0+)?$)(?:0?\.\d{1,2}|[1-9]\d?(?:\.\d{1,2})?|100(?:\.0{1,2})?)$ description: >- The percentage rate of the tax applied to transactions. A decimal amount from 0.01 to 100.00 inclusive, always with exactly two decimal places, no leading zeros except 0.xx. example: '20.00' description: type: string description: Detailed description of the tax for internal reference example: French standard VAT TaxCode: type: string description: >- Unique code used to identify the tax. Must contain only alphanumeric characters, underscores, and hyphens. pattern: ^[a-zA-Z0-9_-]*$ example: standard_vat MinimumCommitmentBase: type: object description: Minimum commitment for this plan. required: - amount properties: amount: allOf: - $ref: '#/components/schemas/Amount' invoice_display_name: type: string description: >- Specifies the name that will be displayed on an invoice. If no value is set for this field, the default name will be used as the display name. example: Minimum Commitment (C1) taxes: type: array description: List of tax entities configured for the minimum commitment. items: $ref: '#/components/schemas/TaxResponse' responses: BadRequest: description: Bad Request - Invalid input data content: application/json: schema: $ref: '#/components/schemas/Error' example: name: INVALID_REQUEST message: >- Request is not well-formed, syntactically incorrect, or violates schema. debug_id: dc99e3955cdd8 details: - field: /email value: abc location: body issue: INVALID_PARAMETER_VALUE description: The value of a field does not conform to the expected format. Forbidden: description: Authorization failed due to insufficient permissions. content: application/json: schema: $ref: '#/components/schemas/Error' example: name: NOT_AUTHORIZED message: Authorization failed due to insufficient permissions. debug_id: 565f78f101498 details: - issue: PERMISSION_DENIED description: >- You do not have permission to access or perform operations on this resource. NotFound: description: Resource Not Found. content: application/json: schema: $ref: '#/components/schemas/Error' UnprocessableEntity: description: Bad Request - Invalid input data content: application/json: schema: $ref: '#/components/schemas/Error' example: name: UNPROCESSABLE_ENTITY message: >- The requested action could not be performed, semantically incorrect, or failed business validation. debug_id: 90957fca61718 details: - field: /email value: sdfwdj@sdfs.com location: body issue: UNSUPPORTED_EMAIL description: The email provided is not supported. InternalServerError: description: Internal Server Error - An unexpected error occurred content: application/json: schema: $ref: '#/components/schemas/Error' example: name: INTERNAL_SERVER_ERROR message: An internal server error has occurred. debug_id: 90957fca61718 securitySchemes: BearerAuth: type: oauth2 description: >- Use the /v1/oauth2/token endpoint to obtain an access token and pass it as a Bearer token in the Authorization header. flows: clientCredentials: tokenUrl: https://api-m.sandbox.paypal.com/v1/oauth2/token scopes: read: Read access write: Write access ````