Skip to main content
PUT
/
subscriptions
/
{external_subscription_id}
Update a subscription
curl --request PUT \
  --url https://api-m.sandbox.paypal.com/v1/commerce/billing/subscriptions/{external_subscription_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>

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>

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>

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"

​
name
string

The name of the subscription.

Example:

"Subscription_1"

​
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

Example:

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

​
end_date
string<date-time>

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"

​
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>

The date at which a pending subscription is canceled.

Example:

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

​
terminated_at
string<date-time>

The date at which an active subscription is canceled.

Example:

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

​
current_period_start
string<date-time>

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

Example:

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

​
trial_ended_at
string<date-time>

The date when the free trial is ended, represented in ISO 8601 date format

Example:

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