openapi: 3.0.3
info:
title: Paypal Authorizations Subscriptions API
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: Subscriptions
paths:
/v1/billing/subscriptions:
post:
summary: 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: customer@example.com
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: customer@example.com
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: 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
security:
- Oauth2:
- https://uri.paypal.com/services/subscriptions
tags:
- Subscriptions
/v1/billing/subscriptions/{id}:
get:
summary: 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/subscription'
'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'
- $ref: '#/components/parameters/fields'
security:
- Oauth2:
- https://uri.paypal.com/services/subscriptions
tags:
- Subscriptions
patch:
summary: Update subscription
description: Updates a subscription which could be in <code>ACTIVE</code> or <code>SUSPENDED</code> status. You can override plan level default attributes by providing customised values for plan path in the patch request.<br /> <ul> <li>You cannot update attributes that have already completed (Example - trial cycles cant be updated if completed).</li> <li>Once overridden, changes to plan resource will not impact subscription.</li> <li>Any price update will not impact billing cycles within next 10 days (Applicable only for subscriptions funded by PayPal account).</li> </ul> Following are the fields eligible for patch.<table><thead><tr><th>Attribute or object</th><th>Operations</th></tr></thead><tbody><tr><td><code>billing_info.outstanding_balance</code></td><td>replace</td></tr><tr><td><code>custom_id</code></td><td>add,replace</td></tr><tr><td><code>plan.billing_cycles[@sequence==n].<br/>pricing_scheme.fixed_price</code></td><td>add,replace</td></tr><tr><td><code>plan.billing_cycles[@sequence==n].<br/>pricing_scheme.tiers</code></td><td>replace</td></tr><tr><td><code>plan.billing_cycles[@sequence==n].<br/>total_cycles</code></td><td>replace</td></tr><tr><td><code>plan.payment_preferences.<br/>auto_bill_outstanding</code></td><td>replace</td></tr><tr><td><code>plan.payment_preferences.<br/>payment_failure_threshold</code></td><td>replace</td></tr><tr><td><code>plan.taxes.inclusive</code></td><td>add,replace</td></tr><tr><td><code>plan.taxes.percentage</code></td><td>add,replace</td></tr><tr><td><code>shipping_amount</code></td><td>add,replace</td></tr><tr><td><code>start_time</code></td><td>replace</td></tr><tr><td><code>subscriber.shipping_address</code></td><td>add,replace</td></tr><tr><td><code>subscriber.payment_source (for subscriptions funded<br/>by card payments)</code></td><td>replace</td></tr></tbody></table>
operationId: subscriptions.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/subscriptions.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/subscriptions.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:
- Subscriptions
/v1/billing/subscriptions/{id}/revise:
post:
summary: Revise plan or quantity of subscription
description: 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.
operationId: subscriptions.revise
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_revise_response'
examples:
subscription_revise_response:
value:
plan_id: P-5ML4271244454362WXNWU5NQ
plan_overridden: false
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
links:
- href: https://www.paypal.com/webapps/billing/subscriptions/update?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
- href: https://api-m.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G/cancel
rel: cancel
method: POST
- href: https://api-m.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G/suspend
rel: suspend
method: POST
- href: https://api-m.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G/capture
rel: capture
method: POST
'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.revise-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/subscriptions.revise-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/subscriptions.revise-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/subscription_revise_request'
examples:
subscription_revise_request:
value:
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:
brand_name: walmart
locale: en-US
shipping_preference: SET_PROVIDED_ADDRESS
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}/suspend:
post:
summary: Suspend subscription
description: Suspends the subscription.
operationId: subscriptions.suspend
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/subscriptions.suspend-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/subscriptions.suspend-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/subscription_suspend_request'
examples:
subscription_suspend_request:
value:
reason: Item out of stock
security:
- Oauth2:
- https://uri.paypal.com/services/subscriptions
tags:
- Subscriptions
/v1/billing/subscriptions/{id}/cancel:
post:
summary: Cancel subscription
description: Cancels the subscription.
operationId: subscriptions.cancel
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/subscriptions.cancel-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/subscriptions.cancel-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/subscription_cancel_request'
examples:
subscription_cancel_request:
value:
reason: Not satisfied with the service
security:
- Oauth2:
- https://uri.paypal.com/services/subscriptions
tags:
- Subscriptions
/v1/billing/subscriptions/{id}/activate:
post:
summary: Activate subscription
description: Activates the subscription.
operationId: subscriptions.activate
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/subscriptions.activate-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/subscriptions.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'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/subscription_activate_request'
examples:
subscription_activate_request:
value:
reason: Reactivating the subscription
security:
- Oauth2:
- https://uri.paypal.com/services/subscriptions
tags:
- Subscriptions
/v1/billing/subscriptions/{id}/capture:
post:
summary: Capture authorized payment on subscription
description: Captures an authorized payment from the subscriber on the subscription.
operationId: subscriptions.capture
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/transaction'
'202':
description: Request Accepted.
'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.capture-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/subscriptions.capture-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/paypal_request_id'
- $ref: '#/components/parameters/id'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/subscription_capture_request'
examples:
subscription_capture_request:
value:
note: Charging as the balance reached the limit
capture_type: OUTSTANDING_BALANCE
amount:
currency_code: USD
value: '100'
security:
- Oauth2:
- https://uri.paypal.com/services/subscriptions
tags:
- Subscriptions
/v1/billing/subscriptions/{id}/transactions:
get:
summary: List transactions for subscription
description: Lists transactions for a subscription.
operationId: subscriptions.transactions
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/transactions_list'
'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.transactions-400'
'401':
descrip
# --- truncated at 32 KB (146 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/paypal/refs/heads/main/openapi/paypal-subscriptions-api-openapi.yml