--- title: "Update a subscription" method: PUT path: "/subscriptions/{external_subscription_id}" tags: ["Subscriptions"] --- # Update a subscription `PUT /subscriptions/{external_subscription_id}` ## Request - Base URL: `https://api-m.sandbox.paypal.com` - URL: `https://api-m.sandbox.paypal.com/subscriptions/{external_subscription_id}` - Auth: OAuth 2 - Client credentials - Token URL: `/api/oauth-proxy` scopes: `read`, `write` - TypeScript: (a function with typed inputs; its response is checked against the schema) Updates an existing subscription's details such as name, or metadata. Can also schedule a future cancellation date. ## Path parameters - `external_subscription_id` string, required ## Request body - SubscriptionUpdateRequest: Update request for a subscription. - `name` string: The name of the subscription. - `start_date` string, date-time: The effective start date of the subscription; can be past, current, or future. Date must be provided in ISO 8601 format - `end_date` string, date-time: The subscription will terminate on this date without renewal. Date must be provided in ISO 8601 format - `status` 'PENDING' | 'ACTIVE' | 'TERMINATED' | 'CANCELED': If the status field is not defined and multiple active and pending subscriptions exists, we will update the active subscription. However, if you wish to update a pending subscription, please ensure that you include the status attribute with the pending value in your request body. - `plan_overrides` PlanOverridesUpdateRequest - `amount` AmountNoCurrency - `value` number, required: The amount value in the corresponding currency unit (e.g., two decimals for USD, no decimals for JPY). - `description` string: The description on the plan - `invoice_display_name` string: Specifies the name that will appear on the invoice - `name` string: The name of the plan - `charges` SubscriptionUsageBasedCharge[] - `id` string, required: Unique identifier of the charge - `tax_codes` string[]: List of unique codes used to identify taxes to be applied. - `properties` object: Pricing thresholds that determine the charges - `minimum_commitment` MinimumCommitmentRequest: Minimum commitment for this plan. - `amount` AmountNoCurrency, required - `value` number, required: The amount value in the corresponding currency unit (e.g., two decimals for USD, no decimals for JPY). - `invoice_display_name` string: 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. - `tax_codes` string[]: List of unique codes used to identify taxes to be applied. - `tax_codes` string[]: List of unique codes used to identify taxes to be applied. ## Response `200` Updated subscription object - SubscriptionResponse - `name` string: The name of the subscription. - `start_date` string, date-time: The effective start date of the subscription; can be past, current, or future. Date must be provided in ISO 8601 format - `end_date` string, date-time: The subscription will terminate on this date without renewal. Date must be provided in ISO 8601 format - `external_customer_id` string, required: External reference to the customer - `external_id` string, required: The subscription external unique identifier supplied by client. Must contain only alphanumeric characters, underscores, and hyphens. - `plan_code` string, required: The plan code - `billing_time` 'CALENDAR' | 'ANNIVERSARY': The billing time for the subscription, which can be set as either anniversary or calendar - `id` string: Unique identifier for the subscription - `status` 'PENDING' | 'ACTIVE' | 'TERMINATED' | 'CANCELED': The status of the subscription - `plan_overrides` PlanOverridesResponse - `amount` Amount - `value` number, required: The amount value in the corresponding currency unit (e.g., two decimals for USD, no decimals for JPY). - `currency_code` string, required: Currency code in ISO 4217 format. - `description` string: The description on the plan - `invoice_display_name` string: Specifies the name that will appear on the invoice - `name` string: The name of the plan - `charges` UsageBasedCharge[] - `id` string, required: Unique identifier of the charge - `metric_id` string, required: Unique identifier of the metric - `charge_model` 'STANDARD' | 'GRADUATED' | 'PACKAGE' | 'PERCENTAGE' | 'VOLUME': The pricing model applied to this charge - `properties` object: Pricing thresholds that determine the charges - `taxes` TaxResponse[]: List of tax entities configured for the usage based charge. - `name` string, required: Name of the tax - `rate` string: 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. - `description` string: Detailed description of the tax for internal reference - `code` string: Unique code used to identify the tax. Must contain only alphanumeric characters, underscores, and hyphens. - `id` string, uuid: Unique identifier of the tax - `created_at` string, date-time: The effective start date of the subscription; can be past, current, or future. Date must be provided in ISO 8601 format - `min_amount` Amount - `value` number, required: The amount value in the corresponding currency unit (e.g., two decimals for USD, no decimals for JPY). - `currency_code` string, required: Currency code in ISO 4217 format. - `minimum_commitment` MinimumCommitment: Minimum commitment for this plan. - `amount` Amount, required - `value` number, required: The amount value in the corresponding currency unit (e.g., two decimals for USD, no decimals for JPY). - `currency_code` string, required: Currency code in ISO 4217 format. - `invoice_display_name` string: 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. - `taxes` TaxResponse[]: List of tax entities configured for the minimum commitment. - `name` string, required: Name of the tax - `rate` string: 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. - `description` string: Detailed description of the tax for internal reference - `code` string: Unique code used to identify the tax. Must contain only alphanumeric characters, underscores, and hyphens. - `id` string, uuid: Unique identifier of the tax - `created_at` string, date-time: The effective start date of the subscription; can be past, current, or future. Date must be provided in ISO 8601 format - `id` string, uuid: Unique identifier of the minimum commitment, created by Lago. - `plan_code` string: The unique code representing the plan to be attached to the customer. - `created_at` string, date-time: 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. - `updated_at` string, date-time: 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. - `chargeUsage` ChargeUsageThresholdResponse[] - `id` string: Refers to the charge usage threshold unique identifier - `recurring` string: Indicates if recurring invoices will be created - `threshold_display_name` string: Indicates the name for the usage threshold - `created_at` string, date-time: Date and time in ISO 8601 format. - `updated_at` string, date-time: Date and time in ISO 8601 format. - `amount` Amount - `value` number, required: The amount value in the corresponding currency unit (e.g., two decimals for USD, no decimals for JPY). - `currency_code` string, required: Currency code in ISO 4217 format. - `taxes` TaxResponse[]: List of tax entities configured for the plan. - `name` string, required: Name of the tax - `rate` string: 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. - `description` string: Detailed description of the tax for internal reference - `code` string: Unique code used to identify the tax. Must contain only alphanumeric characters, underscores, and hyphens. - `id` string, uuid: Unique identifier of the tax - `created_at` string, date-time: The effective start date of the subscription; can be past, current, or future. Date must be provided in ISO 8601 format - `trial_period` integer: The number of days the plan's base cost is provided at no charge - `canceled_at` string, date-time: The date at which a pending subscription is canceled. - `terminated_at` string, date-time: The date at which an active subscription is canceled. - `current_period_start` string, date-time: Start date of the current billing period - `current_period_end` string, date-time: Date and time in ISO 8601 format. - `trial_ended_at` string, date-time: The date when the free trial is ended, represented in ISO 8601 date format ## Other responses - `400`: Bad Request - Invalid input data - `403`: Authorization failed due to insufficient permissions. - `404`: Resource Not Found. - `500`: Internal Server Error - An unexpected error occurred --- [API](https://skmtc.dev/paypal/apis/usage-based-billing-api.md) - [All operations](https://skmtc.dev/paypal/apis/usage-based-billing-api/llms.txt) - [OpenAPI document](https://skmtc.dev/paypal/apis/usage-based-billing-api/revisions/22fb46514ac4?raw)