Skip to main content
PUT
/
plans
/
{plan_code}
Update a plan by Code
curl --request PUT \
  --url https://api-m.paypal.com/v1/commerce/billing/plans/{plan_code} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "<string>",
  "code": "<string>",
  "billing_cycle": "MONTHLY",
  "description": "<string>",
  "amount": {
    "value": 120.35,
    "currency_code": "USD"
  },
  "trial_period": 123,
  "pay_in_advance": true,
  "tax_codes": [
    "standard_vat"
  ],
  "minimum_commitment": {
    "amount": {
      "value": 120.35
    },
    "invoice_display_name": "Minimum Commitment (C1)",
    "tax_codes": [
      "standard_vat"
    ]
  },
  "cascading_updates": true,
  "usage_based_charges": [
    {
      "id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
      "metric_id": "<string>",
      "charge_model": "GRADUATED",
      "tax_codes": [
        "standard_vat"
      ],
      "properties": {},
      "min_amount": {
        "value": 120.35
      }
    }
  ]
}'
{
  "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"
  }
}

Authorizations

Authorization
string
header
required

Use the /v1/oauth2/token endpoint to obtain an access token and pass it as a Bearer token in the Authorization header.

Path Parameters

plan_code
string
required

The code of the plan

Body

application/json
name
string
code
string
billing_cycle
enum<string>

The billing cycle indicating how often the subscription is charged

Available options:
WEEKLY,
MONTHLY,
QUARTERLY,
YEARLY
Example:

"MONTHLY"

description
string
amount
object
trial_period
integer
pay_in_advance
boolean
tax_codes
string[]

List of unique codes used to identify taxes to be applied.

Example:
["standard_vat"]
minimum_commitment
object

Minimum commitment for this plan.

cascading_updates
boolean

Determines if changes made to the parent plan should be cascaded to the overridden plans in subscription

Example:

true

usage_based_charges
object[]

Response

A plan object

id
string

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
string
code
string
billing_cycle
enum<string>

The billing cycle indicating how often the subscription is charged

Available options:
WEEKLY,
MONTHLY,
QUARTERLY,
YEARLY
Example:

"MONTHLY"

description
string
amount
object
trial_period
integer
pay_in_advance
boolean
taxes
object[]

List of tax entities configured for the plan.

usage_based_charges
object[]
minimum_commitment
object

Minimum commitment for this plan.

created_at
string<date-time>

Date and time in ISO 8601 format.

Example:

"2023-10-01T12:00:00Z"

cascading_updates
boolean

Determines if changes made to the parent plan should be cascaded to the children plans

Example:

true

updated_at
string<date-time>

Date and time in ISO 8601 format.

Example:

"2023-10-01T12:00:00Z"

I