Skip to main content
PUT
/
subscriptions
/
{id}
Update a subscription
curl --request PUT \
  --url https://api-m.paypal.com/v1/commerce/billing/subscriptions/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Subscription_1",
  "start_date": "2025-06-01T00:00:00Z",
  "end_date": "2028-01-01T00:00:00Z",
  "status": "ACTIVE",
  "plan_overrides": {
    "amount": {
      "value": 120.35,
      "currency_code": "USD"
    },
    "description": "Plan for early stage startups",
    "invoice_display_name": "Startup plan",
    "name": "Startup",
    "charges": [
      {
        "id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "tax_codes": [
          "standard_vat"
        ],
        "properties": {}
      }
    ],
    "minimum_commitment": {
      "amount": {
        "value": 120.35
      },
      "invoice_display_name": "Minimum Commitment (C1)",
      "tax_codes": [
        "standard_vat"
      ]
    },
    "tax_codes": [
      "standard_vat"
    ]
  }
}'
{
  "name": "Subscription_External",
  "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1753840218",
  "external_id": "Subscription_External_1",
  "plan_code": "Plan-Code-1753840215",
  "billing_time": "ANNIVERSARY",
  "status": "ACTIVE",
  "plan_overrides": {
    "amount": {
      "value": 20,
      "currency_code": "USD"
    },
    "name": "Plan-Name-_1753840215",
    "trial_period": 14,
    "charges": [
      {
        "id": "99fa7a6b-d005-43a5-8bab-0df7a2a721fb",
        "metric_id": "d0682999-67a0-418e-b29b-3757426db01f",
        "charge_model": "STANDARD",
        "properties": {
          "amount": "100.15"
        },
        "min_amount": {
          "value": 200,
          "currency_code": "USD"
        }
      }
    ]
  },
  "start_date": "2025-07-30T01:54:40Z",
  "end_date": "2025-09-09T04:26:24Z",
  "current_period_start": "2025-07-30T01:54:40Z",
  "current_period_end": "2025-08-05T23:59:59Z",
  "id": "b71befc2-4799-402c-9d13-ca1f72759c64"
}

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

​
external_subscription_id
string
required

The unique external identifier of the subscription

Body

application/json

Update request for a subscription.

​
name
string

The name of the subscription.

Example:

"Subscription_1"

​
start_date
string<date-time>

Date and time in ISO 8601 format. 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"

​
end_date
string<date-time>

Date and time in ISO 8601 format. The subscription will terminate on this date without renewal. Date must be provided in ISO 8601 format

Example:

"2028-01-01T00:00:00Z"

​
status
enum<string>

The status of the subscription 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.

Available options:
PENDING,
ACTIVE,
TERMINATED,
CANCELED
Example:

"ACTIVE"

​
plan_overrides
object

Response

Updated subscription object

​
external_customer_id
string
required

External reference to the customer

Example:

"client-jkl101"

​
external_id
string
required

The subscription external unique identifier supplied by client. Must contain only alphanumeric characters, underscores, and hyphens.

Example:

"SUB_1752779018503"

​
plan_code
string
required

The plan code

Example:

"Plan-Code-1753840215"

​
id
string

Unique identifier for the subscription

Example:

"b71befc2-4799-402c-9d13-ca1f72759c64"

​
status
enum<string>

The status of the subscription

Available options:
PENDING,
ACTIVE,
TERMINATED,
CANCELED
Example:

"ACTIVE"

​
plan_overrides
object
​
canceled_at
string<date-time>

Date and time in ISO 8601 format. The date at which a pending subscription is canceled.

Example:

"2025-01-01T00:00:00Z"

​
terminated_at
string<date-time>

Date and time in ISO 8601 format. The date at which an active subscription is canceled.

Example:

"2025-01-01T00:00:00Z"

​
current_period_start
string<date-time>

Date and time in ISO 8601 format. Start date of the current billing period

Example:

"2025-05-01T00:00:00Z"

​
current_period_end
string<date-time>

End date of the current billing period Date and time in ISO 8601 format.

Example:

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

​
trial_ended_at
string<date-time>

Date and time in ISO 8601 format. The date when the free trial is ended, represented in ISO 8601 date format

Example:

"2025-05-01T00:00:00Z"

​
name
string

The name of the subscription.

Example:

"Subscription_1"

​
start_date
string<date-time>

Date and time in ISO 8601 format. 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"

​
end_date
string<date-time>

Date and time in ISO 8601 format. The subscription will terminate on this date without renewal. Date must be provided in ISO 8601 format

Example:

"2028-01-01T00:00:00Z"

​
billing_time
enum<string>
default:CALENDAR

The billing time for the subscription, which can be set as either anniversary or calendar

Available options:
CALENDAR,
ANNIVERSARY
Example:

"CALENDAR"

⌘I