PayPal Billing Subscriptions API
The PayPal Billing Subscriptions API enables businesses to create and manage subscription plans, activate, suspend, cancel, capture, and revise customer subscriptions, and track recurring payments.
OpenAPI Specification
openapi: 3.0.3
info:
title: Paypal Subscriptions
description: 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 <a href="/docs/subscriptions/">Subscriptions Overview</a>.
version: '1.6'
contact: {}
servers:
- url: https://api-m.sandbox.paypal.com
description: PayPal Sandbox Environment
- url: https://api-m.paypal.com
description: PayPal Live Environment
tags:
- name: Plans
description: Use the `/billing/plans` resource to create and manage plans.
- name: Subscriptions
description: Use the `/billing/subscriptions` resource to create and manage subscriptions.
externalDocs:
url: https://developer.paypal.com/docs/api/subscriptions/v1/
paths:
"/v1/billing/plans":
post:
summary: Paypal Create plan
description: Creates a plan that defines pricing and billing cycle details for subscriptions.
operationId: plans.create
responses:
'200':
description: A successful request returns the HTTP `200 OK` status code and a JSON response body that shows billing plan details.
content:
application/json:
schema:
"$ref": "#/components/schemas/plan"
examples:
plan:
value:
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:
- href: https://api-m.paypal.com/v1/billing/plans/P-5ML4271244454362WXNWU5NQ
rel: self
method: GET
- href: https://api-m.paypal.com/v1/billing/plans/P-5ML4271244454362WXNWU5NQ
rel: edit
method: PATCH
- href: https://api-m.paypal.com/v1/billing/plans/P-5ML4271244454362WXNWU5NQ/deactivate
rel: deactivate
method: POST
- href: https://api-m.paypal.com/v1/billing/plans/P-5ML4271244454362WXNWU5NQ/update-pricing-schemes
rel: edit
method: POST
'201':
description: A successful request returns the HTTP `201 Created` status code and a JSON response body that shows billing plan details.
content:
application/json:
schema:
"$ref": "#/components/schemas/plan"
'400':
description: Bad Request. Request is not well-formed, syntactically incorrect, or violates schema.
content:
application/json:
schema:
allOf:
- "$ref": "#/components/schemas/error_400"
- "$ref": "#/components/schemas/plans.create-400"
'401':
description: Authentication failed due to missing authorization header, or invalid authentication credentials.
content:
application/json:
schema:
allOf:
- "$ref": "#/components/schemas/error_401"
- "$ref": "#/components/schemas/401"
'403':
description: Authorization failed due to insufficient permissions.
content:
application/json:
schema:
allOf:
- "$ref": "#/components/schemas/error_403"
- "$ref": "#/components/schemas/403"
'422':
description: The requested action could not be performed, semantically incorrect, or failed business validation.
content:
application/json:
schema:
allOf:
- "$ref": "#/components/schemas/error_422"
- "$ref": "#/components/schemas/422"
'500':
description: An internal server error has occurred.
content:
application/json:
schema:
"$ref": "#/components/schemas/error_500"
default:
"$ref": "#/components/responses/default"
parameters:
- "$ref": "#/components/parameters/prefer"
- "$ref": "#/components/parameters/paypal_request_id"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/plan_request_POST"
examples:
plan_request_post:
value:
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
- 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
taxes:
percentage: '10'
inclusive: false
security:
- Oauth2:
- https://uri.paypal.com/services/subscriptions
tags:
- Plans
get:
summary: Paypal List plans
description: Lists billing plans.
operationId: plans.list
responses:
'200':
description: A successful request returns the HTTP `200 OK` status code and a JSON response body that lists billing plans.
content:
application/json:
schema:
"$ref": "#/components/schemas/plan_collection"
'400':
description: Request is not well-formed, syntactically incorrect, or violates schema.
content:
application/json:
schema:
allOf:
- "$ref": "#/components/schemas/error_400"
- "$ref": "#/components/schemas/400"
'401':
description: Authentication failed due to missing authorization header, or invalid authentication credentials.
content:
application/json:
schema:
allOf:
- "$ref": "#/components/schemas/error_401"
- "$ref": "#/components/schemas/401"
'403':
description: Authorization failed due to insufficient permissions.
content:
application/json:
schema:
allOf:
- "$ref": "#/components/schemas/error_403"
- "$ref": "#/components/schemas/403"
'404':
description: The specified resource does not exist.
content:
application/json:
schema:
"$ref": "#/components/schemas/error_404"
'500':
description: An internal server error has occurred.
content:
application/json:
schema:
"$ref": "#/components/schemas/error_500"
default:
"$ref": "#/components/responses/default"
parameters:
- "$ref": "#/components/parameters/prefer"
- "$ref": "#/components/parameters/product_id"
- "$ref": "#/components/parameters/plan_ids"
- "$ref": "#/components/parameters/page_size"
- "$ref": "#/components/parameters/page"
- "$ref": "#/components/parameters/total_required"
security:
- Oauth2:
- https://uri.paypal.com/services/subscriptions
tags:
- Plans
"/v1/billing/plans/{id}":
get:
summary: Paypal Show plan details
description: Shows details for a plan, by ID.
operationId: plans.get
responses:
'200':
description: A successful request returns the HTTP `200 OK` status code and a JSON response body that shows plan details.
content:
application/json:
schema:
"$ref": "#/components/schemas/plan"
'401':
description: Authentication failed due to missing authorization header, or invalid authentication credentials.
content:
application/json:
schema:
allOf:
- "$ref": "#/components/schemas/error_401"
- "$ref": "#/components/schemas/401"
'403':
description: Authorization failed due to insufficient permissions.
content:
application/json:
schema:
allOf:
- "$ref": "#/components/schemas/error_403"
- "$ref": "#/components/schemas/403"
'404':
description: The specified resource does not exist.
content:
application/json:
schema:
allOf:
- "$ref": "#/components/schemas/error_404"
- "$ref": "#/components/schemas/404"
'500':
description: An internal server error has occurred.
content:
application/json:
schema:
"$ref": "#/components/schemas/error_500"
default:
"$ref": "#/components/responses/default"
parameters:
- "$ref": "#/components/parameters/id"
security:
- Oauth2:
- https://uri.paypal.com/services/subscriptions
tags:
- Plans
patch:
summary: Paypal Update plan
description: Updates a plan with the `CREATED` or `ACTIVE` status. For an `INACTIVE` plan, you can make only status updates.<br/>You can patch these attributes and objects:<table><thead><tr><th>Attribute or object</th><th>Operations</th></tr></thead><tbody><tr><td><code>description</code></td><td>replace</td></tr><tr><td><code>payment_preferences.auto_bill_outstanding</code></td><td>replace</td></tr><tr><td><code>taxes.percentage</code></td><td>replace</td></tr><tr><td><code>payment_preferences.payment_failure_threshold</code></td><td>replace</td></tr><tr><td><code>payment_preferences.setup_fee</code></td><td>replace</td></tr><tr><td><code>payment_preferences.setup_fee_failure_action</code></td><td>replace</td></tr><tr><td><code>name</code></td><td>replace</td></tr></tbody></table>
operationId: plans.patch
responses:
'204':
description: A successful request returns the HTTP `204 No Content` status code with no JSON response body.
'400':
description: Request is not well-formed, syntactically incorrect, or violates schema.
content:
application/json:
schema:
allOf:
- "$ref": "#/components/schemas/error_400"
- "$ref": "#/components/schemas/plans.patch-400"
'401':
description: Authentication failed due to missing authorization header, or invalid authentication credentials.
content:
application/json:
schema:
allOf:
- "$ref": "#/components/schemas/error_401"
- "$ref": "#/components/schemas/401"
'403':
description: Authorization failed due to insufficient permissions.
content:
application/json:
schema:
allOf:
- "$ref": "#/components/schemas/error_403"
- "$ref": "#/components/schemas/403"
'404':
description: The specified resource does not exist.
content:
application/json:
schema:
allOf:
- "$ref": "#/components/schemas/error_404"
- "$ref": "#/components/schemas/404"
'422':
description: The requested action could not be performed, semantically incorrect, or failed business validation.
content:
application/json:
schema:
allOf:
- "$ref": "#/components/schemas/error_422"
- "$ref": "#/components/schemas/plans.patch-422"
'500':
description: An internal server error has occurred.
content:
application/json:
schema:
"$ref": "#/components/schemas/error_500"
default:
"$ref": "#/components/responses/default"
parameters:
- "$ref": "#/components/parameters/id"
requestBody:
"$ref": "#/components/requestBodies/patch_request"
security:
- Oauth2:
- https://uri.paypal.com/services/subscriptions
tags:
- Plans
"/v1/billing/plans/{id}/activate":
post:
summary: Paypal Activate plan
description: Activates a plan, by ID.
operationId: plans.activate
responses:
'204':
description: A successful request returns the HTTP `204 No Content` status code with no JSON response body.
'401':
description: Authentication failed due to missing authorization header, or invalid authentication credentials.
content:
application/json:
schema:
allOf:
- "$ref": "#/components/schemas/error_401"
- "$ref": "#/components/schemas/401"
'403':
description: Authorization failed due to insufficient permissions.
content:
application/json:
schema:
allOf:
- "$ref": "#/components/schemas/error_403"
- "$ref": "#/components/schemas/403"
'404':
description: The specified resource does not exist.
content:
application/json:
schema:
allOf:
- "$ref": "#/components/schemas/error_404"
- "$ref": "#/components/schemas/404"
'422':
description: The requested action could not be performed, semantically incorrect, or failed business validation.
content:
application/json:
schema:
allOf:
- "$ref": "#/components/schemas/error_422"
- "$ref": "#/components/schemas/plans.activate-422"
'500':
description: An internal server error has occurred.
content:
application/json:
schema:
"$ref": "#/components/schemas/error_500"
default:
"$ref": "#/components/responses/default"
parameters:
- "$ref": "#/components/parameters/id"
security:
- Oauth2:
- https://uri.paypal.com/services/subscriptions
tags:
- Plans
"/v1/billing/plans/{id}/deactivate":
post:
summary: Paypal Deactivate plan
description: Deactivates a plan, by ID.
operationId: plans.deactivate
responses:
'204':
description: A successful request returns the HTTP `204 No Content` status code with no JSON response body.
'401':
description: Authentication failed due to missing authorization header, or invalid authentication credentials.
content:
application/json:
schema:
allOf:
- "$ref": "#/components/schemas/error_401"
- "$ref": "#/components/schemas/401"
'403':
description: Authorization failed due to insufficient permissions.
content:
application/json:
schema:
allOf:
- "$ref": "#/components/schemas/error_403"
- "$ref": "#/components/schemas/403"
'404':
description: The specified resource does not exist.
content:
application/json:
schema:
allOf:
- "$ref": "#/components/schemas/error_404"
- "$ref": "#/components/schemas/404"
'422':
description: The requested action could not be performed, semantically incorrect, or failed business validation.
content:
application/json:
schema:
allOf:
- "$ref": "#/components/schemas/error_422"
- "$ref": "#/components/schemas/plans.deactivate-422"
'500':
description: An internal server error has occurred.
content:
application/json:
schema:
"$ref": "#/components/schemas/error_500"
default:
"$ref": "#/components/responses/default"
parameters:
- "$ref": "#/components/parameters/id"
security:
- Oauth2:
- https://uri.paypal.com/services/subscriptions
tags:
- Plans
"/v1/billing/plans/{id}/update-pricing-schemes":
post:
summary: Paypal Update pricing
description: Updates pricing for a plan. For example, you can update a regular billing cycle from $5 per month to $7 per month.
operationId: plans.update-pricing-schemes
responses:
'204':
description: A successful request returns the HTTP `204 No Content` status code with no JSON response body.
'400':
description: Bad Request. Request is not well-formed, syntactically incorrect, or violates schema.
content:
application/json:
schema:
allOf:
- "$ref": "#/components/schemas/error_400"
- "$ref": "#/components/schemas/plans.update-pricing-schemes-400"
'401':
description: Authentication failed due to missing authorization header, or invalid authentication credentials.
content:
application/json:
schema:
allOf:
- "$ref": "#/components/schemas/error_401"
- "$ref": "#/components/schemas/401"
'403':
description: Authorization failed due to insufficient permissions.
content:
application/json:
schema:
allOf:
- "$ref": "#/components/schemas/error_403"
- "$ref": "#/components/schemas/403"
'404':
description: The specified resource does not exist.
content:
application/json:
schema:
allOf:
- "$ref": "#/components/schemas/error_404"
- "$ref": "#/components/schemas/404"
'422':
description: The requested action could not be performed, semantically incorrect, or failed business validation.
content:
application/json:
schema:
allOf:
- "$ref": "#/components/schemas/error_422"
- "$ref": "#/components/schemas/plans.update-pricing-schemes-422"
'500':
description: An internal server error has occurred.
content:
application/json:
schema:
"$ref": "#/components/schemas/error_500"
default:
"$ref": "#/components/responses/default"
parameters:
- "$ref": "#/components/parameters/id"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/update_pricing_schemes_list_request"
examples:
update_pricing_schemes_list_request:
value:
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
security:
- Oauth2:
- https://uri.paypal.com/services/subscriptions
tags:
- Plans
"/v1/billing/subscriptions":
post:
summary: Paypal Create subscription
description: Creates a subscription.
operationId: subscriptions.create
responses:
'200':
description: A successful request returns the HTTP `200 OK` status code and a JSON response body that shows subscription details.
content:
application/json:
schema:
"$ref": "#/components/schemas/subscription"
examples:
subscription:
value:
id: I-BW452GLLEP1G
status: APPROVAL_PENDING
status_update_time: '2018-12-10T21:20:49Z'
plan_id: P-5ML4271244454362WXNWU5NQ
plan_overridden: false
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: [email protected]
payer_id: 2J6QB8YJQSJRJ
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
create_time: '2018-12-10T21:20:49Z'
links:
- href: https://www.paypal.com/webapps/billing/subscriptions?ba_token=BA-2M539689T3856352J
rel: approve
method: GET
- href: https://api-m.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G
rel: edit
method: PATCH
- href: https://api-m.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G
rel: self
method: GET
'201':
description: A successful request returns the HTTP `201 Created` status code and a JSON response body that shows subscription details.
content:
application/json:
schema:
"$ref": "#/components/schemas/subscription"
examples:
subscription:
value:
id: I-BW452GLLEP1G
status: APPROVAL_PENDING
status_update_time: '2018-12-10T21:20:49Z'
plan_id: P-5ML4271244454362WXNWU5NQ
plan_overridden: false
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: [email protected]
payer_id: 2J6QB8YJQSJRJ
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
create_time: '2018-12-10T21:20:49Z'
links:
- href: https://www.paypal.com/webapps/billing/subscriptions?ba_token=BA-2M539689T3856352J
rel: approve
method: GET
- href: https://api-m.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G
rel: edit
method: PATCH
- href: https://api-m.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G
rel: self
method: GET
'400':
description: Bad Request. Request is not well-formed, syntactically incorrect, or violates schema.
content:
application/json:
schema:
allOf:
- "$ref": "#/components/schemas/error_400"
- "$ref": "#/components/schemas/subscriptions.create-400"
'401':
description: Authentication failed due to missing authorization header, or invalid authentication credentials.
content:
application/json:
schema:
allOf:
- "$ref": "#/components/schemas/error_401"
- "$ref": "#/components/schemas/401"
'403':
description: Authorization failed due to insufficient permissions.
content:
application/json:
schema:
allOf:
- "$ref": "#/components/schemas/error_403"
- "$ref": "#/components/schemas/403"
'422':
description: The requested action could not be performed, semantically incorrect, or failed business validation.
content:
application/json:
schema:
allOf:
- "$ref": "#/components/schemas/error_422"
- "$ref": "#/components/schemas/subscriptions.create-422"
'500':
description: An internal server error has occurred.
content:
application/json:
schema:
"$ref": "#/components/schemas/error_500"
default:
"$ref": "#/components/responses/default"
parameters:
- "$ref": "#/components/parameters/prefer"
- "$ref": "#/components/parameters/paypal_request_id"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/subscription_request_post"
examples:
subscription_request_post:
value:
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: [email protected]
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
security:
- Oauth2:
- https://uri.paypal.com/services/subscriptions
tags:
- Subscriptions
"/v1/billing/subscriptions/{id}":
get:
summary: Paypal Show subscription details
description: Shows details for a subscription, by ID.
operationId: subscriptions.get
responses:
'200':
description: A successful request returns the HTTP `200 OK` status code and a JSON response body that shows subscription details.
content:
application/json:
schema:
"$ref": "#/components/schemas/subscr
# --- truncated at 32 KB (196 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/paypal/refs/heads/main/openapi/paypal-billing-subscriptions-openapi-original.yml