Subscriptions (1)

You can use billing plans and subscriptions to create subscriptions that process recurring PayPal payments for physical or digital goods, or services. A plan includes pricing and billing cycle information that defines the amount and frequency of charge for a subscription. You can also define a fixed plan, such as a $5 basic plan or a volume- or graduated-based plan with pricing tiers based on the quantity purchased. For more information, see Subscriptions Overview.

Create plan

post/v1/billing/plans

Creates a plan that defines pricing and billing cycle details for subscriptions.

SecurityOauth2
Request
header Parameters
Authorization
required
string

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <client_id>:<secret>.

Content-Type
required
string

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

Prefer
string
Default: return=minimal

The preferred server response upon successful completion of the request. Value is:

  • return=minimal. The server returns a minimal response to optimize communication between the API caller and the server. A minimal response includes the id, status and HATEOAS links.
  • return=representation. The server returns a complete resource representation, including the current state of the resource.

PayPal-Request-Id
string

The server stores keys for 72 hours.

Request Body schema: application/json
product_id
required
string = 22 characters ^PROD-[A-Z0-9]*$

The ID of the product created through Catalog Products API.

name
required
string [ 1 .. 127 ] characters ^.*$

The plan name.

status
string [ 1 .. 24 ] characters ^[A-Z_]+$
Default: "ACTIVE"

The initial state of the plan. Allowed input values are CREATED and ACTIVE.

Enum: Description
CREATED

The plan was created. You cannot create subscriptions for a plan in this state.

INACTIVE

The plan is inactive.

ACTIVE

The plan is active. You can only create subscriptions for a plan in this state.

description
string [ 1 .. 127 ] characters ^.*$

The detailed description of the plan.

required
Array of objects (billing_cycle) [ 1 .. 12 ] items

An array of billing cycles for trial billing and regular billing. A plan can have at most two trial cycles and only one regular cycle.

quantity_supported
boolean
Default: false

Indicates whether you can subscribe to this plan by providing a quantity for the goods or service.

required
object (payment_preferences)

The payment preferences for a subscription.

object (taxes)

The tax details.

Responses
201

A successful request returns the HTTP 201 Created status code and a JSON response body that shows billing plan details.

Request samples
application/json
{
  • "product_id": "PROD-XXCD1234QWER65782",
  • "name": "Video Streaming Service Plan",
  • "billing_cycles": [
    • {
      • "tenure_type": "TRIAL",
      • "sequence": 1,
      • "frequency": {
        • "interval_unit": "MONTH",
        • "interval_count": 1
        },
      • "total_cycles": 2,
      • "pricing_scheme": {
        • "fixed_price": {
          • "value": "3",
          • "currency_code": "USD"
          }
        }
      },
    • {
      • "frequency": {
        • "interval_unit": "MONTH",
        • "interval_count": 1
        },
      • "tenure_type": "TRIAL",
      • "sequence": 2,
      • "total_cycles": 3,
      • "pricing_scheme": {
        • "fixed_price": {
          • "value": "6",
          • "currency_code": "USD"
          }
        }
      },
    • {
      • "frequency": {
        • "interval_unit": "MONTH",
        • "interval_count": 1
        },
      • "tenure_type": "REGULAR",
      • "sequence": 3,
      • "total_cycles": 12,
      • "pricing_scheme": {
        • "fixed_price": {
          • "value": "10",
          • "currency_code": "USD"
          }
        }
      }
    ],
  • "payment_preferences": {
    • "auto_bill_outstanding": true,
    • "setup_fee": {
      • "value": "10",
      • "currency_code": "USD"
      },
    • "setup_fee_failure_action": "CONTINUE",
    • "payment_failure_threshold": 3
    },
  • "description": "Video Streaming Service basic plan",
  • "status": "ACTIVE",
  • "taxes": {
    • "percentage": "10",
    • "inclusive": false
    }
}
Response samples
application/json
{
  • "id": "P-5ML4271244454362WXNWU5NQ",
  • "product_id": "PROD-XXCD1234QWER65782",
  • "name": "Video Streaming Service Plan",
  • "description": "Video Streaming Service basic plan",
  • "status": "ACTIVE",
  • "billing_cycles": [
    • {
      • "frequency": {
        • "interval_unit": "MONTH",
        • "interval_count": 1
        },
      • "tenure_type": "TRIAL",
      • "sequence": 1,
      • "total_cycles": 2,
      • "pricing_scheme": {
        • "fixed_price": {
          • "value": "3",
          • "currency_code": "USD"
          },
        • "version": 1,
        • "create_time": "2020-05-27T12:13:51Z",
        • "update_time": "2020-05-27T12:13:51Z"
        }
      },
    • {
      • "frequency": {
        • "interval_unit": "MONTH",
        • "interval_count": 1
        },
      • "tenure_type": "TRIAL",
      • "sequence": 2,
      • "total_cycles": 3,
      • "pricing_scheme": {
        • "fixed_price": {
          • "currency_code": "USD",
          • "value": "6"
          },
        • "version": 1,
        • "create_time": "2020-05-27T12:13:51Z",
        • "update_time": "2020-05-27T12:13:51Z"
        }
      },
    • {
      • "frequency": {
        • "interval_unit": "MONTH",
        • "interval_count": 1
        },
      • "tenure_type": "REGULAR",
      • "sequence": 3,
      • "total_cycles": 12,
      • "pricing_scheme": {
        • "fixed_price": {
          • "currency_code": "USD",
          • "value": "10"
          },
        • "version": 1,
        • "create_time": "2020-05-27T12:13:51Z",
        • "update_time": "2020-05-27T12:13:51Z"
        }
      }
    ],
  • "payment_preferences": {
    • "auto_bill_outstanding": true,
    • "setup_fee": {
      • "value": "10",
      • "currency_code": "USD"
      },
    • "setup_fee_failure_action": "CONTINUE",
    • "payment_failure_threshold": 3
    },
  • "taxes": {
    • "percentage": "10",
    • "inclusive": false
    },
  • "create_time": "2020-05-27T12:13:51Z",
  • "update_time": "2020-05-27T12:13:51Z",
  • "links": []
}

List plans

get/v1/billing/plans

Lists billing plans.

SecurityOauth2
Request
query Parameters
product_id
string [ 6 .. 50 ] characters

Filters the response by a Product ID.

page_size
integer [ 1 .. 20 ]
Default: 10

The number of items to return in the response.

page
integer [ 1 .. 100000 ]
Default: 1

A non-zero integer which is the start index of the entire list of items to return in the response. The combination of page=1 and page_size=20 returns the first 20 items. The combination of page=2 and page_size=20 returns the next 20 items.

total_required
boolean
Default: false

Indicates whether to show the total count in the response.

header Parameters
Authorization
required
string

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <client_id>:<secret>.

Content-Type
required
string

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

Prefer
string
Default: return=minimal

The preferred server response upon successful completion of the request. Value is:

  • return=minimal. The server returns a minimal response to optimize communication between the API caller and the server. A minimal response includes the id, name, description and HATEOAS links.
  • return=representation. The server returns a complete resource representation, including the current state of the resource.

Responses
200

A successful request returns the HTTP 200 OK status code and a JSON response body that lists billing plans.

Request samples 
curl -v -X GET https://api-m.sandbox.paypal.com/v1/billing/plans?sort_by=create_time&sort_order=desc \
-H 'Authorization: Bearer access_token6V7rbVwmlM1gFZKW_8QtzWXqpcwQ6T5vhEGYNJDAAdn3paCgRpdeMdVYmWzgbKSsECednupJ3Zx5Xd-g' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Prefer: return=representation'
Response samples
application/json
{}

Show plan details

get/v1/billing/plans/{id}

Shows details for a plan, by ID.

SecurityOauth2
Request
path Parameters
id
required
string

The ID of the plan.

header Parameters
Authorization
required
string

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <client_id>:<secret>.

Content-Type
required
string

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

Responses
200

A successful request returns the HTTP 200 OK status code and a JSON response body that shows plan details.

Request samples 
curl -v -X GET https://api-m.sandbox.paypal.com/v1/billing/plans/P-5ML4271244454362WXNWU5NQ \
-H 'Authorization: Bearer access_token6V7rbVwmlM1gFZKW_8QtzWXqpcwQ6T5vhEGYNJDAAdn3paCgRpdeMdVYmWzgbKSsECednupJ3Zx5Xd-g' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
Response samples
application/json
{
  • "id": "P-5ML4271244454362WXNWU5NQ",
  • "product_id": "PROD-XXCD1234QWER65782",
  • "name": "Basic Plan",
  • "description": "Basic Plan",
  • "status": "ACTIVE",
  • "billing_cycles": [
    • {
      • "frequency": {
        • "interval_unit": "MONTH",
        • "interval_count": 1
        },
      • "tenure_type": "TRIAL",
      • "sequence": 1,
      • "total_cycles": 2,
      • "pricing_scheme": {
        • "fixed_price": {
          • "currency_code": "USD",
          • "value": "3"
          },
        • "version": 1,
        • "create_time": "2020-05-27T12:13:51Z",
        • "update_time": "2020-05-27T12:13:51Z"
        }
      },
    • {
      • "frequency": {
        • "interval_unit": "MONTH",
        • "interval_count": 1
        },
      • "tenure_type": "TRIAL",
      • "sequence": 2,
      • "total_cycles": 3,
      • "pricing_scheme": {
        • "fixed_price": {
          • "currency_code": "USD",
          • "value": "6"
          },
        • "version": 1,
        • "create_time": "2020-05-27T12:13:51Z",
        • "update_time": "2020-05-27T12:13:51Z"
        }
      },
    • {
      • "frequency": {
        • "interval_unit": "MONTH",
        • "interval_count": 1
        },
      • "tenure_type": "REGULAR",
      • "sequence": 3,
      • "total_cycles": 12,
      • "pricing_scheme": {
        • "fixed_price": {
          • "value": "10",
          • "currency_code": "USD"
          },
        • "status": "ACTIVE",
        • "version": 1,
        • "create_time": "2020-05-27T12:13:51Z",
        • "update_time": "2020-05-27T12:13:51Z"
        }
      }
    ],
  • "taxes": {
    • "percentage": "10",
    • "inclusive": false
    },
  • "create_time": "2020-05-27T12:13:51Z",
  • "update_time": "2020-05-27T12:13:51Z",
  • "links": []
}

Update plan

patch/v1/billing/plans/{id}

Updates a plan with the CREATED or ACTIVE status. For an INACTIVE plan, you can make only status updates.
You can patch these attributes and objects:

Attribute or objectOperations
descriptionreplace
payment_preferences.auto_bill_outstandingreplace
taxes.percentagereplace
payment_preferences.payment_failure_thresholdreplace
payment_preferences.setup_feereplace
payment_preferences.setup_fee_failure_actionreplace
namereplace

SecurityOauth2
Request
path Parameters
id
required
string

The ID of the plan.

header Parameters
Authorization
required
string

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <client_id>:<secret>.

Content-Type
required
string

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

Request Body schema: application/json
Array
op
required
string

The operation.

Enum: Description
add

Depending on the target location reference, completes one of these functions:

  • The target location is an array index. Inserts a new value into the array at the specified index.
  • The target location is an object parameter that does not already exist. Adds a new parameter to the object.
  • The target location is an object parameter that does exist. Replaces that parameter's value.
The value parameter defines the value to add. For more information, see 4.1. add.

remove

Removes the value at the target location. For the operation to succeed, the target location must exist. For more information, see 4.2. remove.

replace

Replaces the value at the target location with a new value. The operation object must contain a value parameter that defines the replacement value. For the operation to succeed, the target location must exist. For more information, see 4.3. replace.

move

Removes the value at a specified location and adds it to the target location. The operation object must contain a from parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to move the value. For the operation to succeed, the from location must exist. For more information, see 4.4. move.

copy

Copies the value at a specified location to the target location. The operation object must contain a from parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to copy the value. For the operation to succeed, the from location must exist. For more information, see 4.5. copy.

test

Tests that a value at the target location is equal to a specified value. The operation object must contain a value parameter that defines the value to compare to the target location's value. For the operation to succeed, the target location must be equal to the value value. For test, equal indicates that the value at the target location and the value that value defines are of the same JSON type. The data type of the value determines how equality is defined:

TypeConsidered equal if both values
stringsContain the same number of Unicode characters and their code points are byte-by-byte equal.
numbersAre numerically equal.
arraysContain the same number of values, and each value is equal to the value at the corresponding position in the other array, by using these type-specific rules.
objectsContain the same number of parameters, and each parameter is equal to a parameter in the other object, by comparing their keys (as strings) and their values (by using these type-specific rules).
literals (false, true, and null)Are the same. The comparison is a logical comparison. For example, whitespace between the parameter values of an array is not significant. Also, ordering of the serialization of object parameters is not significant.
For more information, see 4.6. test.

path
string

The JSON Pointer to the target document location at which to complete the operation.

value
object (Patch Value)

The value to apply. The remove operation does not require a value.

from
string

The JSON Pointer to the target document location from which to move the value. Required for the move operation.

Responses
204

A successful request returns the HTTP 204 No Content status code with no JSON response body.

Request samples
application/json
[
  • {
    • "op": "replace",
    • "path": "/payment_preferences/payment_failure_threshold",
    • "value": 7
    },
  • {
    • "op": "replace",
    • "path": "/name",
    • "value": "Updated Video Streaming Service Plan"
    }
]

Activate plan

post/v1/billing/plans/{id}/activate

Activates a plan, by ID.

SecurityOauth2
Request
path Parameters
id
required
string

The ID of the plan.

header Parameters
Authorization
required
string

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <client_id>:<secret>.

Content-Type
required
string

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

Responses
204

A successful request returns the HTTP 204 No Content status code with no JSON response body.

Request samples 
curl -v -X POST https://api-m.sandbox.paypal.com/v1/billing/plans/P-7GL4271244454362WXNWU5NQ/activate \
-H 'Authorization: Bearer access_token6V7rbVwmlM1gFZKW_8QtzWXqpcwQ6T5vhEGYNJDAAdn3paCgRpdeMdVYmWzgbKSsECednupJ3Zx5Xd-g' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'

Deactivate plan

post/v1/billing/plans/{id}/deactivate

Deactivates a plan, by ID.

SecurityOauth2
Request
path Parameters
id
required
string

The ID of the plan.

header Parameters
Authorization
required
string

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <client_id>:<secret>.

Content-Type
required
string

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

Responses
204

A successful request returns the HTTP 204 No Content status code with no JSON response body.

Request samples 
curl -v -X POST https://api-m.sandbox.paypal.com/v1/billing/plans/P-7GL4271244454362WXNWU5NQ/deactivate \
-H 'Authorization: Bearer access_token6V7rbVwmlM1gFZKW_8QtzWXqpcwQ6T5vhEGYNJDAAdn3paCgRpdeMdVYmWzgbKSsECednupJ3Zx5Xd-g' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'

Update pricing

post/v1/billing/plans/{id}/update-pricing-schemes

Updates pricing for a plan. For example, you can update a regular billing cycle from $5 per month to $7 per month.

SecurityOauth2
Request
path Parameters
id
required
string

The ID for the plan.

header Parameters
Authorization
required
string

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <client_id>:<secret>.

Content-Type
required
string

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

Request Body schema: application/json
required
Array of objects (update_pricing_scheme_request) [ 1 .. 99 ] items

An array of pricing schemes.

Responses
204

A successful request returns the HTTP 204 No Content status code with no JSON response body.

Request samples
application/json
{
  • "pricing_schemes": [
    • {
      • "billing_cycle_sequence": 1,
      • "pricing_scheme": {
        • "fixed_price": {
          • "value": "50",
          • "currency_code": "USD"
          }
        }
      },
    • {
      • "billing_cycle_sequence": 2,
      • "pricing_scheme": {
        • "fixed_price": {
          • "value": "100",
          • "currency_code": "USD"
          },
        • "pricing_model": "VOLUME",
        • "tiers": [
          • {
            • "starting_quantity": "1",
            • "ending_quantity": "1000",
            • "amount": {
              • "value": "150",
              • "currency_code": "USD"
              }
            },
          • {
            • "starting_quantity": "1001",
            • "amount": {
              • "value": "250",
              • "currency_code": "USD"
              }
            }
          ]
        }
      }
    ]
}

Create subscription

post/v1/billing/subscriptions

Creates a subscription.

SecurityOauth2
Request
header Parameters
Authorization
required
string

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <client_id>:<secret>.

Content-Type
required
string

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

Prefer
string
Default: return=minimal

The preferred server response upon successful completion of the request. Value is:

  • return=minimal. The server returns a minimal response to optimize communication between the API caller and the server. A minimal response includes the id, status and HATEOAS links.
  • return=representation. The server returns a complete resource representation, including the current state of the resource.

PayPal-Request-Id
string

The server stores keys for 72 hours.

Request Body schema: application/json
plan_id
required
string = 26 characters ^P-[A-Z0-9]*$

The ID of the plan.

quantity
string [ 1 .. 32 ] characters ^([0-9]+|([0-9]+)?[.][0-9]+)$

The quantity of the product in the subscription.

auto_renewal
boolean
Default: false

DEPRECATED. Indicates whether the subscription auto-renews after the billing cycles complete.

custom_id
string [ 1 .. 127 ] characters ^[\x20-\x7E]+

The custom id for the subscription. Can be invoice id.

start_time
string <ppaas_date_time_v3> (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...
Default: "Current time"

The date and time when the subscription started, in Internet date and time format.

object (Money)

The shipping charges.

object <payer_v1> (subscriber_request)

The subscriber request information .

object (application_context)

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

object (plan_override)

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.

Responses
201

A successful request returns the HTTP 201 Created status code and a JSON response body that shows subscription details.

Request samples
application/json
{
  • "plan_id": "P-5ML4271244454362WXNWU5NQ",
  • "start_time": "2018-11-01T00:00:00Z",
  • "quantity": "20",
  • "shipping_amount": {
    • "currency_code": "USD",
    • "value": "10.00"
    },
  • "subscriber": {
    • "name": {
      • "given_name": "John",
      • "surname": "Doe"
      },
    • "email_address": "customer@example.com",
    • "shipping_address": {
      • "name": {
        • "full_name": "John Doe"
        },
      • "address": {
        • "address_line_1": "2211 N First Street",
        • "address_line_2": "Building 17",
        • "admin_area_2": "San Jose",
        • "admin_area_1": "CA",
        • "postal_code": "95131",
        • "country_code": "US"
        }
      }
    },
  • "application_context": {
    • "brand_name": "walmart",
    • "locale": "en-US",
    • "shipping_preference": "SET_PROVIDED_ADDRESS",
    • "user_action": "SUBSCRIBE_NOW",
    • "payment_method": {
      • "payer_selected": "PAYPAL",
      • "payee_preferred": "IMMEDIATE_PAYMENT_REQUIRED"
      },
    • "return_url": "https://example.com/returnUrl",
    • "cancel_url": "https://example.com/cancelUrl"
    }
}
Response samples
application/json
{}

Show subscription details

get/v1/billing/subscriptions/{id}

Shows details for a subscription, by ID.

SecurityOauth2
Request
path Parameters
id
required
string

The ID of the subscription.

query Parameters
fields
string [ 1 .. 100 ] characters

List of fields that are to be returned in the response. Possible value for fields are last_failed_payment and plan.

header Parameters
Authorization
required
string

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <client_id>:<secret>.

Content-Type
required
string

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

Responses
200

A successful request returns the HTTP 200 OK status code and a JSON response body that shows subscription details.

Request samples 
curl -v -X GET https://api-m.sandbox.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G \
-H 'Authorization: Bearer access_token6V7rbVwmlM1gFZKW_8QtzWXqpcwQ6T5vhEGYNJDAAdn3paCgRpdeMdVYmWzgbKSsECednupJ3Zx5Xd-g' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
Response samples
application/json
{
  • "id": "I-BW452GLLEP1G",
  • "plan_id": "P-5ML4271244454362WXNWU5NQ",
  • "start_time": "2019-04-10T07:00:00Z",
  • "quantity": "20",
  • "shipping_amount": {
    • "currency_code": "USD",
    • "value": "10.0"
    },
  • "subscriber": {
    • "shipping_address": {
      • "name": {
        • "full_name": "John Doe"
        },
      • "address": {
        • "address_line_1": "2211 N First Street",
        • "address_line_2": "Building 17",
        • "admin_area_2": "San Jose",
        • "admin_area_1": "CA",
        • "postal_code": "95131",
        • "country_code": "US"
        }
      },
    • "name": {
      • "given_name": "John",
      • "surname": "Doe"
      },
    • "email_address": "customer@example.com",
    • "payer_id": "2BBBB8YJQSCCC"
    },
  • "billing_info": {
    • "outstanding_balance": {
      • "currency_code": "USD",
      • "value": "1.0"
      },
    • "cycle_executions": [
      • {
        • "tenure_type": "TRIAL",
        • "sequence": 1,
        • "cycles_completed": 0,
        • "cycles_remaining": 2,
        • "total_cycles": 2
        },
      • {
        • "tenure_type": "TRIAL",
        • "sequence": 2,
        • "cycles_completed": 0,
        • "cycles_remaining": 3,
        • "total_cycles": 3
        },
      • {
        • "tenure_type": "REGULAR",
        • "sequence": 3,
        • "cycles_completed": 0,
        • "cycles_remaining": 12,
        • "total_cycles": 12
        }
      ],
    • "last_payment": {
      • "amount": {
        • "currency_code": "USD",
        • "value": "1.15"
        },
      • "time": "2019-04-09T10:27:20Z"
      },
    • "next_billing_time": "2019-04-10T10:00:00Z",
    • "failed_payments_count": 0
    },
  • "create_time": "2019-04-09T10:26:04Z",
  • "update_time": "2019-04-09T10:27:27Z",
  • "links": [],
  • "status": "ACTIVE",
  • "status_update_time": "2019-04-09T10:27:27Z"
}

Update subscription

patch/v1/billing/subscriptions/{id}

Updates a subscription which could be in ACTIVE or SUSPENDED status. You can override plan level default attributes by providing customised values for plan path in the patch request.

  • You cannot update attributes that have already completed (Example - trial cycles can’t be updated if completed).
  • Once overridden, changes to plan resource will not impact subscription.
  • Any price update will not impact billing cycles within next 10 days (Applicable only for subscriptions funded by PayPal account).
Following are the fields eligible for patch.
Attribute or objectOperations
billing_info.outstanding_balancereplace
custom_idadd,replace
plan.billing_cycles[@sequence==n].
pricing_scheme.fixed_price		add,replace
plan.billing_cycles[@sequence==n].
pricing_scheme.tiers		replace
plan.billing_cycles[@sequence==n].
total_cycles		replace
plan.payment_preferences.
auto_bill_outstanding		replace
plan.payment_preferences.
payment_failure_threshold		replace
plan.taxes.inclusiveadd,replace
plan.taxes.percentageadd,replace
shipping_amountadd,replace
start_timereplace
subscriber.shipping_addressadd,replace
subscriber.payment_source (for subscriptions funded
by card payments)		replace

SecurityOauth2
Request
path Parameters
id
required
string

The ID for the subscription.

header Parameters
Authorization
required
string

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <client_id>:<secret>.

Content-Type
required
string

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

Request Body schema: application/json
Array
op
required
string

The operation.

Enum: Description
add

Depending on the target location reference, completes one of these functions:

  • The target location is an array index. Inserts a new value into the array at the specified index.
  • The target location is an object parameter that does not already exist. Adds a new parameter to the object.
  • The target location is an object parameter that does exist. Replaces that parameter's value.
The value parameter defines the value to add. For more information, see 4.1. add.

remove

Removes the value at the target location. For the operation to succeed, the target location must exist. For more information, see 4.2. remove.

replace

Replaces the value at the target location with a new value. The operation object must contain a value parameter that defines the replacement value. For the operation to succeed, the target location must exist. For more information, see 4.3. replace.

move

Removes the value at a specified location and adds it to the target location. The operation object must contain a from parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to move the value. For the operation to succeed, the from location must exist. For more information, see 4.4. move.

copy

Copies the value at a specified location to the target location. The operation object must contain a from parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to copy the value. For the operation to succeed, the from location must exist. For more information, see 4.5. copy.

test

Tests that a value at the target location is equal to a specified value. The operation object must contain a value parameter that defines the value to compare to the target location's value. For the operation to succeed, the target location must be equal to the value value. For test, equal indicates that the value at the target location and the value that value defines are of the same JSON type. The data type of the value determines how equality is defined:

TypeConsidered equal if both values
stringsContain the same number of Unicode characters and their code points are byte-by-byte equal.
numbersAre numerically equal.
arraysContain the same number of values, and each value is equal to the value at the corresponding position in the other array, by using these type-specific rules.
objectsContain the same number of parameters, and each parameter is equal to a parameter in the other object, by comparing their keys (as strings) and their values (by using these type-specific rules).
literals (false, true, and null)Are the same. The comparison is a logical comparison. For example, whitespace between the parameter values of an array is not significant. Also, ordering of the serialization of object parameters is not significant.
For more information, see 4.6. test.

path
string

The JSON Pointer to the target document location at which to complete the operation.

value
object (Patch Value)

The value to apply. The remove operation does not require a value.

from
string

The JSON Pointer to the target document location from which to move the value. Required for the move operation.

Responses
204

A successful request returns the HTTP 204 No Content status code with no JSON response body.

Request samples
application/json
[
  • {
    • "op": "replace",
    • "path": "/plan/billing_cycles/@sequence==1/pricing_scheme/fixed_price",
    • "value": {
      • "currency_code": "USD",
      • "value": "50.00"
      }
    },
  • {
    • "op": "replace",
    • "path": "/plan/billing_cycles/@sequence==2/pricing_scheme/tiers",
    • "value": [
      • {
        • "starting_quantity": "1",
        • "ending_quantity": "1000",
        • "amount": {
          • "value": "500",
          • "currency_code": "USD"
          }
        },
      • {
        • "starting_quantity": "1001",
        • "amount": {
          • "value": "2000",
          • "currency_code": "USD"
          }
        }
      ]
    },
  • {
    • "op": "replace",
    • "path": "/plan/payment_preferences/auto_bill_outstanding",
    • "value": true
    },
  • {
    • "op": "replace",
    • "path": "/plan/payment_preferences/payment_failure_threshold",
    • "value": 1
    },
  • {
    • "op": "replace",
    • "path": "/plan/taxes/percentage",
    • "value": "10"
    }
]

Revise plan or quantity of subscription

post/v1/billing/subscriptions/{id}/revise

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.

SecurityOauth2
Request
path Parameters
id
required
string

The ID of the subscription.

header Parameters
Authorization
required
string

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <client_id>:<secret>.

Content-Type
required
string

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

Request Body schema: application/json
plan_id
string = 26 characters ^P-[A-Z0-9]*$

The unique PayPal-generated ID for the plan.

quantity
string [ 1 .. 32 ] characters ^([0-9]+|([0-9]+)?[.][0-9]+)$

The quantity of the product or service in the subscription.

object (Money)

The shipping charges.

object (shipping_detail)

The shipping address of the subscriber.

object (application_context)

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

object (plan_override)

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.

Responses
200

A successful request returns the HTTP 200 OK status code and a JSON response body that shows subscription details.

Request samples
application/json
{
  • "plan_id": "P-5ML4271244454362WXNWU5NQ",
  • "shipping_amount": {
    • "currency_code": "USD",
    • "value": "10.00"
    },
  • "shipping_address": {
    • "name": {
      • "full_name": "John Doe"
      },
    • "address": {
      • "address_line_1": "2211 N First Street",
      • "address_line_2": "Building 17",
      • "admin_area_2": "San Jose",
      • "admin_area_1": "CA",
      • "postal_code": "95131",
      • "country_code": "US"
      }
    },
  • "application_context": {}
}
Response samples
application/json
{}

Suspend subscription

post/v1/billing/subscriptions/{id}/suspend

Suspends the subscription.

SecurityOauth2
Request
path Parameters
id
required
string

The ID of the subscription.

header Parameters
Authorization
required
string

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <client_id>:<secret>.

Content-Type
required
string

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

Request Body schema: application/json
reason
required
string [ 1 .. 128 ] characters ^.*$

The reason for suspension of the Subscription.

Responses
204

A successful request returns the HTTP 204 No Content status code with no JSON response body.

Request samples
application/json
{
  • "reason": "Item out of stock"
}

Cancel subscription

post/v1/billing/subscriptions/{id}/cancel

Cancels the subscription.

SecurityOauth2
Request
path Parameters
id
required
string

The ID of the subscription.

header Parameters
Authorization
required
string

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <client_id>:<secret>.

Content-Type
required
string

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

Request Body schema: application/json
reason
required
string [ 1 .. 128 ] characters ^.*$

The reason for the cancellation of a subscription.

Responses
204

A successful request returns the HTTP 204 No Content status code with no JSON response body.

Request samples
application/json
{
  • "reason": "Not satisfied with the service"
}

Activate subscription

post/v1/billing/subscriptions/{id}/activate

Activates the subscription.

SecurityOauth2
Request
path Parameters
id
required
string

The ID of the subscription.

header Parameters
Authorization
required
string

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <client_id>:<secret>.

Content-Type
required
string

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

Request Body schema: application/json
reason
string [ 1 .. 128 ] characters ^.*$

The reason for activation of a subscription. Required to reactivate the subscription.

Responses
204

A successful request returns the HTTP 204 No Content status code with no JSON response body.

Request samples
application/json
{
  • "reason": "Reactivating the subscription"
}

Capture authorized payment on subscription

post/v1/billing/subscriptions/{id}/capture

Captures an authorized payment from the subscriber on the subscription.

SecurityOauth2
Request
path Parameters
id
required
string

The ID of the subscription.

header Parameters
Authorization
required
string

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <client_id>:<secret>.

Content-Type
required
string

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

PayPal-Request-Id
string

The server stores keys for 72 hours.

Request Body schema: application/json
note
required
string [ 1 .. 128 ] characters ^.*$

The reason or note for the subscription charge.

capture_type
required
string [ 1 .. 24 ] characters ^[A-Z_]+$

The type of capture.

Value: Description
OUTSTANDING_BALANCE

The outstanding balance that the subscriber must clear.

required
object (Money)

The currency and amount for a financial transaction, such as a balance or payment due.

Responses
202

Request Accepted.

Request samples
application/json
{
  • "note": "Charging as the balance reached the limit",
  • "capture_type": "OUTSTANDING_BALANCE",
  • "amount": {
    • "currency_code": "USD",
    • "value": "100"
    }
}

List transactions for subscription

get/v1/billing/subscriptions/{id}/transactions

Lists transactions for a subscription.

SecurityOauth2
Request
path Parameters
id
required
string

The ID of the subscription.

query Parameters
start_time
required
string <ppaas_date_time_v3> [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...

The start time of the range of transactions to list.

end_time
required
string <ppaas_date_time_v3> [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...

The end time of the range of transactions to list.

header Parameters
Authorization
required
string

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <client_id>:<secret>.

Content-Type
required
string

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

Responses
200

A successful request returns the HTTP 200 OK status code and a JSON response body that shows subscription details.

Request samples 
curl -v -X GET https://api-m.sandbox.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G/transactions?start_time=2018-01-21T07:50:20.940Z&end_time=2018-08-21T07:50:20.940Z \
-H 'Authorization: Bearer access_token6V7rbVwmlM1gFZKW_8QtzWXqpcwQ6T5vhEGYNJDAAdn3paCgRpdeMdVYmWzgbKSsECednupJ3Zx5Xd-g' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
Response samples
application/json
{
  • "transactions": [
    • {
      • "id": "TRFGHNJKOIIOJKL",
      • "status": "COMPLETED",
      • "payer_email": "customer@example.com",
      • "payer_name": {
        • "given_name": "John",
        • "surname": "Doe"
        },
      • "amount_with_breakdown": {
        • "gross_amount": {
          • "currency_code": "USD",
          • "value": "10.00"
          },
        • "fee_amount": {
          • "currency_code": "USD",
          • "value": "1.00"
          },
        • "net_amount": {
          • "currency_code": "USD",
          • "value": "9.00"
          }
        },
      • "time": "2018-03-16T07:40:20.940Z"
      },
    • {
      • "id": "VDFG45345FFGS",
      • "status": "COMPLETED",
      • "payer_email": "customer2@example.com",
      • "payer_name": {
        • "given_name": "Jhonny",
        • "surname": "Cat"
        },
      • "amount_with_breakdown": {
        • "gross_amount": {
          • "currency_code": "USD",
          • "value": "15.00"
          },
        • "fee_amount": {
          • "currency_code": "USD",
          • "value": "1.00"
          },
        • "net_amount": {
          • "currency_code": "USD",
          • "value": "14.00"
          }
        },
      • "time": "2018-08-21T07:50:20.940Z"
      }
    ],
  • "links": []
}

Definitions

amount_with_breakdown

The breakdown details for the amount. Includes the gross, tax, fee, and shipping amounts.

required
object (Money)

The amount for this transaction.

object (Money)

The item total for the transaction.

object (Money)

The fee details for the transaction.

object (Money)

The shipping amount for the transaction.

object (Money)

The tax amount for the transaction.

object (Money)

The net amount that the payee receives for this transaction in their PayPal account. The net amount is computed as gross_amount minus the paypal_fee.

{
  • "gross_amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "total_item_amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "fee_amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "shipping_amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "tax_amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "net_amount": {
    • "currency_code": "str",
    • "value": "string"
    }
}

application_context

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

brand_name
string [ 1 .. 127 ] characters ^.*$

The label that overrides the business name in the PayPal account on the PayPal site.

shipping_preference
string [ 1 .. 24 ] characters ^[A-Z_]+$
Default: "GET_FROM_FILE"

The location from which the shipping address is derived.

Enum: Description
GET_FROM_FILE

Get the customer-provided shipping address on the PayPal site.

NO_SHIPPING

Redacts the shipping address from the PayPal site. Recommended for digital goods.

SET_PROVIDED_ADDRESS

Get the merchant-provided address. The customer cannot change this address on the PayPal site. If merchant does not pass an address, customer can choose the address on PayPal pages.

user_action
string [ 1 .. 24 ] characters ^[A-Z_]+$
Default: "SUBSCRIBE_NOW"

Configures the label name to Continue or Subscribe Now for subscription consent experience.

Enum: Description
CONTINUE

After you redirect the customer to the PayPal subscription consent page, a Continue button appears. Use this option when you want to control the activation of the subscription and do not want PayPal to activate the subscription.

SUBSCRIBE_NOW

After you redirect the customer to the PayPal subscription consent page, a Subscribe Now button appears. Use this option when you want PayPal to activate the subscription.

return_url
required
string <uri> [ 10 .. 4000 ] characters

The URL where the customer is redirected after the customer approves the payment.

cancel_url
required
string <uri> [ 10 .. 4000 ] characters

The URL where the customer is redirected after the customer cancels the payment.

locale
string <ppaas_common_language_v3> (language) [ 2 .. 10 ] characters ^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}))...

The BCP 47-formatted locale of pages that the PayPal payment experience shows. PayPal supports a five-character code. For example, da-DK, he-IL, id-ID, ja-JP, no-NO, pt-BR, ru-RU, sv-SE, th-TH, zh-CN, zh-HK, or zh-TW.

object (payment_method)

The customer and merchant payment preferences. Currently only PAYPAL payment method is supported.

{
  • "brand_name": "string",
  • "shipping_preference": "GET_FROM_FILE",
  • "user_action": "CONTINUE",
  • "return_url": "http://example.com",
  • "cancel_url": "http://example.com",
  • "locale": "string",
  • "payment_method": {
    • "payer_selected": "PAYPAL",
    • "payee_preferred": "UNRESTRICTED"
    }
}

application_context

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

brand_name
string [ 1 .. 127 ] characters ^.*$

The label that overrides the business name in the PayPal account on the PayPal site.

shipping_preference
string [ 1 .. 24 ] characters ^[A-Z_]+$
Default: "GET_FROM_FILE"

The location from which the shipping address is derived.

Enum: Description
GET_FROM_FILE

Get the customer-provided shipping address on the PayPal site.

NO_SHIPPING

Redacts the shipping address from the PayPal site. Recommended for digital goods.

SET_PROVIDED_ADDRESS

Get the merchant-provided address. The customer cannot change this address on the PayPal site. If merchant does not pass an address, customer can choose the address on PayPal pages.

return_url
required
string <uri> [ 10 .. 4000 ] characters

The URL where the customer is redirected after the customer approves the payment.

cancel_url
required
string <uri> [ 10 .. 4000 ] characters

The URL where the customer is redirected after the customer cancels the payment.

locale
string <ppaas_common_language_v3> (language) [ 2 .. 10 ] characters ^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}))...

The BCP 47-formatted locale of pages that the PayPal payment experience shows. PayPal supports a five-character code. For example, da-DK, he-IL, id-ID, ja-JP, no-NO, pt-BR, ru-RU, sv-SE, th-TH, zh-CN, zh-HK, or zh-TW.

object (payment_method)

The customer and merchant payment preferences. Currently only PAYPAL payment method is supported.