Revise plan or quantity of subscription

Updates the quantity of the product or service in a subscription. You can also use this method to switch the plan and update the `shipping_amount`, `shipping_address` values for the subscription. This type of update requires the buyer's consent.

Authorization

AuthorizationBearer <token>

FlowClient CredentialsToken URLhttps://api-m.sandbox.paypal.com/v1/oauth2/tokenInheader

Scopes

Manage plan & subscriptionhttps://uri.paypal.com/services/subscriptions

Path Parameters

Header Parameters

Content-TypestringRequired

The media type. Required for operations with a request body. The value is `application/`, where the `format` is `json`.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

plan_idstringOptional

The unique PayPal-generated ID for the plan.

Match^P-[A-Z0-9]*$Length26 <= length <= 26

quantitystringOptional

The quantity of the product or service in the subscription.

Match^([0-9]+|([0-9]+)?[.][0-9]+)$Length1 <= length <= 32

shipping_amountobject<money>Optional

The shipping charges.

shipping_addressobject<shipping_detail>Optional

The shipping address of the subscriber.

shipping_detail properties

6 properties

nameobject<name>Optional

The name of the party.

email_addressstring<email_address>Optional

The email address of the recipient of the shipped items, which may belong to either the payer, or an alternate contact, for delivery.

Match^(?:[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+)*|"(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21\x23-\x5b\x5d-\x7f]|\\[\x01-\x09\x0b\x0c\x0e-\x7f])*")@(?:(?:[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?\.)+[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?|\[(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?|[A-Za-z0-9-]*[A-Za-z0-9]:(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21-\x5a\x53-\x7f]|\\[\x01-\x09\x0b\x0c\x0e-\x7f])+)\])$Formatppaas_common_email_address_v2Length3 <= length <= 254

phone_numberobject<Phone>Optional

The phone number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en).

typeenumOptional

A classification for the method of purchase fulfillment (e.g shipping, in-store pickup, etc). Either `type` or `options` may be present, but not both.

Match^[0-9A-Z_]+$Length1 <= length <= 255

Allowed values

"SHIPPING"
"PICKUP_IN_PERSON"
"PICKUP_IN_STORE"
"PICKUP_FROM_PERSON"

optionsobject<shipping_option>[]Optional

An array of shipping options that the payee or merchant offers to the payer to ship or pick up their items.

Items0 <= length <= 10

shipping_option properties

5 properties

idstringRequired

A unique ID that identifies a payer-selected shipping option.

Length0 <= length <= 127

labelstringRequired

A description that the payer sees, which helps them choose an appropriate shipping option. For example, `Free Shipping`, `USPS Priority Shipping`, `Expédition prioritaire USPS`, or `USPS yōuxiān fā huò`. Localize this description to the payer's locale.

Length0 <= length <= 127

typeenum<shipping_type>Optional

A classification for the method of purchase fulfillment.

Allowed values

"SHIPPING"
"PICKUP"
"PICKUP_IN_STORE"
"PICKUP_FROM_PERSON"

amountobject<money>Optional

The shipping cost for the selected option.

selectedbooleanRequired

If the API request sets `selected = true`, it represents the shipping option that the payee or merchant expects to be pre-selected for the payer when they first view the `shipping.options` in the PayPal Checkout experience. As part of the response if a `shipping.option` contains `selected=true`, it represents the shipping option that the payer selected during the course of checkout with PayPal. Only one `shipping.option` can be set to `selected=true`.

addressobject<Portable Postal Address (Medium-Grained)>Optional

The portable international postal address. Maps to [AddressValidationMetadata](https://github.com/googlei18n/libaddressinput/wiki/AddressValidationMetadata) and HTML 5.1 [Autofilling form controls: the autocomplete attribute](https://www.w3.org/TR/html51/sec-forms.html#autofilling-form-controls-the-autocomplete-attribute).

application_contextobject<application_context>Optional

The application context, which customizes the payer experience during the subscription approval process with PayPal.

planobject<plan_override>Optional

An inline plan object to customise the subscription. You can override plan level default attributes by providing customised values for the subscription in this object. Any existing overrides will not be carried forward during subscription revise.

Response Body

`application/json`

curl -X POST "https://example.com/v1/billing/subscriptions/string/revise" \  -H "Content-Type: string" \  -H "Content-Type: application/json" \  -d '{}'

{  "plan_id": "stringstringstringstringst",  "quantity": "string",  "shipping_amount": {    "currency_code": "str",    "value": "string"  },  "shipping_address": {    "name": {      "full_name": "string"    },    "email_address": "string",    "phone_number": {      "country_code": "str",      "national_number": "string"    },    "type": "SHIPPING",    "options": [],    "address": {      "address_line_1": "string",      "address_line_2": "string",      "admin_area_2": "string",      "admin_area_1": "string",      "postal_code": "string",      "country_code": "st"    }  },  "plan": {    "billing_cycles": [      {        "pricing_scheme": {          "version": 0,          "fixed_price": {            "currency_code": "str",            "value": "string"          },          "pricing_model": "VOLUME",          "tiers": [            {              "starting_quantity": "string",              "ending_quantity": "string",              "amount": {                "currency_code": "str",                "value": "string"              }            }          ],          "create_time": "stringstringstringst",          "update_time": "stringstringstringst"        },        "sequence": 1,        "total_cycles": 0      }    ],    "payment_preferences": {      "auto_bill_outstanding": true,      "setup_fee": {        "currency_code": "str",        "value": "string"      },      "setup_fee_failure_action": "CONTINUE",      "payment_failure_threshold": 0    },    "taxes": {      "percentage": "string",      "inclusive": true    }  },  "plan_overridden": true,  "links": [    {      "href": "string",      "rel": "string",      "method": "GET"    }  ]}

Header Parameters

Content-TypestringRequired

The media type. Required for operations with a request body. The value is `application/`, where the `format` is `json`.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

plan_idstringOptional

The unique PayPal-generated ID for the plan.

Match^P-[A-Z0-9]*$Length26 <= length <= 26

quantitystringOptional

The quantity of the product or service in the subscription.

Match^([0-9]+|([0-9]+)?[.][0-9]+)$Length1 <= length <= 32

shipping_amountobject<money>Optional

The shipping charges.

shipping_addressobject<shipping_detail>Optional

The shipping address of the subscriber.

shipping_detail properties

6 properties

nameobject<name>Optional

The name of the party.

email_addressstring<email_address>Optional

The email address of the recipient of the shipped items, which may belong to either the payer, or an alternate contact, for delivery.

phone_numberobject<Phone>Optional

The phone number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en).

typeenumOptional

A classification for the method of purchase fulfillment (e.g shipping, in-store pickup, etc). Either `type` or `options` may be present, but not both.

Match^[0-9A-Z_]+$Length1 <= length <= 255

Allowed values

"SHIPPING"
"PICKUP_IN_PERSON"
"PICKUP_IN_STORE"
"PICKUP_FROM_PERSON"

optionsobject<shipping_option>[]Optional

An array of shipping options that the payee or merchant offers to the payer to ship or pick up their items.

Items0 <= length <= 10

shipping_option properties

5 properties

idstringRequired

A unique ID that identifies a payer-selected shipping option.

Length0 <= length <= 127

labelstringRequired

Length0 <= length <= 127

typeenum<shipping_type>Optional

A classification for the method of purchase fulfillment.

Allowed values

"SHIPPING"
"PICKUP"
"PICKUP_IN_STORE"
"PICKUP_FROM_PERSON"

amountobject<money>Optional

The shipping cost for the selected option.

selectedbooleanRequired

addressobject<Portable Postal Address (Medium-Grained)>Optional

application_contextobject<application_context>Optional

The application context, which customizes the payer experience during the subscription approval process with PayPal.

planobject<plan_override>Optional

{ "plan_id": "stringstringstringstringst", "quantity": "string", "shipping_amount": { "currency_code": "str", "value": "string" }, "shipping_address": { "name": { "full_name": "string" }, "email_address": "string", "phone_number": { "country_code": "str", "national_number": "string" }, "type": "SHIPPING", "options": [], "address": { "address_line_1": "string", "address_line_2": "string", "admin_area_2": "string", "admin_area_1": "string", "postal_code": "string", "country_code": "st" } }, "plan": { "billing_cycles": [ { "pricing_scheme": { "version": 0, "fixed_price": { "currency_code": "str", "value": "string" }, "pricing_model": "VOLUME", "tiers": [ { "starting_quantity": "string", "ending_quantity": "string", "amount": { "currency_code": "str", "value": "string" } } ], "create_time": "stringstringstringst", "update_time": "stringstringstringst" }, "sequence": 1, "total_cycles": 0 } ], "payment_preferences": { "auto_bill_outstanding": true, "setup_fee": { "currency_code": "str", "value": "string" }, "setup_fee_failure_action": "CONTINUE", "payment_failure_threshold": 0 }, "taxes": { "percentage": "string", "inclusive": true } }, "plan_overridden": true, "links": [ { "href": "string", "rel": "string", "method": "GET" } ]}

money properties

shipping_detail properties

name properties

Phone properties

shipping_option properties

money properties

Portable Postal Address (Medium-Grained) properties

application_context properties

Payment Method properties

plan_override properties

billing_cycle_override properties

pricing_scheme properties

money properties

pricing_tier properties

money properties

payment_preferences_override properties

money properties

taxes_override properties

200application/json

400application/json

401application/json

403application/json

404application/json

422application/json

500application/json

defaultapplication/json

On this page

On this page

On this page

If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more

Revise plan or quantity of subscription

money properties

shipping_detail properties

name properties

Phone properties

shipping_option properties

money properties

Portable Postal Address (Medium-Grained) properties

application_context properties

Payment Method properties

plan_override properties

billing_cycle_override properties

pricing_scheme properties

money properties

pricing_tier properties

money properties

payment_preferences_override properties

money properties

taxes_override properties

200application/json

400application/json

401application/json

403application/json

404application/json

422application/json

500application/json

defaultapplication/json

On this page

On this page

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`