Subscriptions Management
Show subscription details
This sample request shows subscription details:
curl -v -X GET https://api.sandbox.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"
A successful request returns the HTTP 200 OK status code and a JSON response body.
{
"id": "I-BW452GLLEP1G",
"status": "ACTIVE",
"status_update_time": "2020-02-01T01:00:00Z",
"plan_id": "P-5ML4271244454362WXNWU5NQ",
"start_time": "2020-02-01T01:00:00Z",
"shipping_amount": {
"currency_code": "USD",
"value": "3.00"
},
"subscriber": {
"name": {
"given_name": "John",
"surname": "Doe"
},
"email_address": "john@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"
}
}
},
"billing_info": {
"outstanding_balance": {
"currency_code": "USD",
"value": "10.00"
},
"cycle_executions": [
{
"tenure_type": "TRIAL",
"sequence": 1,
"cycles_completed": 1,
"cycles_remaining": 0,
"total_cycles": 1,
"current_pricing_scheme_version": 1
},
{
"tenure_type": "REGULAR",
"sequence": 2,
"cycles_completed": 1,
"cycles_remaining": 0,
"total_cycles": 0,
"current_pricing_scheme_version": 2
}
],
"last_payment": {
"amount": {
"currency_code": "USD",
"value": "500.00"
},
"time": "2018-12-01T01:20:49Z"
},
"next_billing_time": "2020-01-01T00:20:49Z",
"final_payment_time": "2020-01-01T00:20:49Z",
"failed_payments_count": 2
},
"create_time": "2018-12-10T21:20:49Z",
"update_time": "2018-12-10T21:20:49Z",
"links": [
{
"href": "https://api.sandbox.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G",
"rel": "self",
"method": "GET"
},
{
"href": "https://api.sandbox.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G",
"rel": "edit",
"method": "PATCH"
},
{
"href": "https://api.sandbox.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G/cancel",
"rel": "cancel",
"method": "POST"
},
{
"href": "https://api.sandbox.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G/activate",
"rel": "activate",
"method": "POST"
},
{
"href": "https://api.sandbox.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G/capture",
"rel": "capture",
"method": "POST"
}
]
}
{
"status": "ACTIVE",
"status_update_time": "2020-03-22T10:47:17Z",
"id": "I-EXCCE2B4J0D5",
"plan_id": "P-2UF78835G6983425GLSM44MA",
"start_time": "2020-04-30T07:00:00Z",
"quantity": "1",
"shipping_amount": {
"currency_code": "USD",
"value": "10.0"
},
"subscriber": {
"email_address": "customer@example.com",
"payer_id": "4YVVLBDW9X8JG",
"shipping_address": {
"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"
}
},
"payment_source": {
"card": {
"last_digits": "4781",
"name": "John Doe",
"billing_address": {
"address_line_1": "2211 N First Street",
"address_line_2": "17.3.160",
"admin_area_2": "San Jose",
"admin_area_1": "CA",
"postal_code": "95131",
"country_code": "US"
}
}
}
},
"billing_info": {
"outstanding_balance": {
"currency_code": "USD",
"value": "0.0"
},
"cycle_executions": [
{
"tenure_type": "REGULAR",
"sequence": 1,
"cycles_completed": 0,
"cycles_remaining": 5,
"current_pricing_scheme_version": 1,
"total_cycles": 5
}
],
"last_payment": {
"amount": {
"currency_code": "USD",
"value": "10.0"
},
"time": "2020-03-22T10:43:38Z"
},
"next_billing_time": "2020-04-30T10:00:00Z",
"final_payment_time": "2020-05-04T10:00:00Z",
"failed_payments_count": 0
},
"create_time": "2020-03-22T10:43:33Z",
"update_time": "2020-03-22T10:47:17Z",
"links": [
{
"href": "https://api.sandbox.paypal.com/v1/billing/subscriptions/I-EXCCE2B4J0D5/cancel",
"rel": "cancel",
"method": "POST"
},
{
"href": "https://api.sandbox.paypal.com/v1/billing/subscriptions/I-EXCCE2B4J0D5",
"rel": "edit",
"method": "PATCH"
},
{
"href": "https://api.sandbox.paypal.com/v1/billing/subscriptions/I-EXCCE2B4J0D5",
"rel": "self",
"method": "GET"
},
{
"href": "https://api.sandbox.paypal.com/v1/billing/subscriptions/I-EXCCE2B4J0D5/suspend",
"rel": "suspend",
"method": "POST"
},
{
"href": "https://api.sandbox.paypal.com/v1/billing/subscriptions/I-EXCCE2B4J0D5/capture",
"rel": "capture",
"method": "POST"
}
]
}Update subscription
This sample request updates a subscription:
curl -v -X PATCH https://api.sandbox.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '[
{
"op": "replace",
"path": "/billing_info/outstanding_balance",
"value": {
"currency_code": "USD",
"value": "50.00"
}
}
]'
You can update the following fields:
subscriber.shipping_addressshipping_amountbilling_info.outstanding_balancesubscriber.payment_source—Only for direct card flow
A successful request returns the HTTP 204 No Content status code.
If subscription update succeeds, it triggers the BILLING.SUBSCRIPTION.UPDATED webhook.
Suspend subscription
This sample request suspends a subscription:
curl -v -X POST https://api.sandbox.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G/suspend \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"
A successful request returns the HTTP 204 No Content status code with no JSON response body.
If subscription suspension succeeds, it triggers the BILLING.SUBSCRIPTION.SUSPENDED webhook.
Cancel subscription
This sample request cancels a subscription:
curl -v -X POST https://api.sandbox.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G/cancel \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"
A successful request returns the HTTP 204 No Content status code with no JSON response body.
If subscription cancellation succeeds, it triggers the BILLING.SUBSCRIPTION.CANCELLED webhook.
Activate subscription
The sample request activates a subscription:
curl -v -X POST https://api.sandbox.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G/activate \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"
A successful request returns the HTTP 204 No Content status code with no JSON response body.
If activate subscription succeeds, it triggers the BILLING.SUBSCRIPTION.ACTIVATED webhook.
Capture amount on subscription
This sample request captures any outstanding amount for a subscription:
Note: You can capture up to the maximum outstanding balance for only active or suspended subscriptions.
curl -v -X POST https://api.sandbox.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G/capture \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"
-d '{
"note": "Charging as the balance reached the limit",
"capture_type": "OUTSTANDING_BALANCE",
"amount": {
"value": "100",
"currency_code": "USD"
}
}'
A successful request returns the HTTP 202 Accepted status code without a JSON response body and an idempotent request returns 200 OK with a JSON response body.
If the capture of the outstanding balance succeeds, it triggers the PAYMENT.SALE.COMPLETED webhook.
List transactions for a subscription
This sample request lists the transactions for a subscription:
By default, the response lists 150 transactions.
curl -v -X GET https://api.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 "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"
A successful request returns the HTTP 200 OK status code and a JSON response body.
{
"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": "Johnny",
"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": [{
"href": "https://api.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",
"rel": "self",
"method": "GET"
}]
Revise subscription
You can upgrade or downgrade a subscription by changing the plan and/or quantity of the subscription. Changing from one plan to another is allowed only across plans within the same product.
For example, you can revise a subscription from a $10 basic plan to a $14 premium plan, or revise a five software licenses monthly subscription to 10 licenses per month.
If the buyer originally subscribed using PayPal, the buyer must consent to the revision. If the buyer doesn't consent, they continue to be billed according to the current subscription.
If the buyer originally subscribed using a credit or debit card, the revision does not require the buyer's consent.
Successful revisions are effective in the next billing cycle.
Revise a subscription using the Subscriptions API
To revise a subscription for a plan in active status, call /subscriptions/{subscription_id}/revise.
If the buyer originally subscribed through PayPal, the buyer must consent to the revision before it goes into effect. To redirect the buyer to log into their PayPal account to approve the change, use the approve HATEOS link from the response.
If the buyer subscribed directly using a credit/debit card, the revision doesn't require the buyer's consent and the response will not have an approve HATEOS link.
Successful revisions are effective in the next billing cycle.
curl -v -X POST https://api.sandbox.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G/revise \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
"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": "Video Streaming Service",
"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"
}
}'
A successful request returns the HTTP 200 OK status code and a JSON response body that shows subscription details.
{
"plan_id": "P-5ML4271244454362WXNWU5NQ",
"effective_time": "2018-11-01T00:00:00Z",
"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?ba_token=BA-2M539689T3856352J",
"rel": "approve",
"method": "GET"
}
]
}
If revising the subscription succeeds, it triggers the BILLING.SUBSCRIPTION.UPDATED webhook.
