Subscriptions Management

DocsCurrent

Show subscription details

This sample request shows subscription details:

curl -v -X GET https://api-m.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-m.sandbox.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G",
      "rel": "edit",
      "method": "PATCH"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G/cancel",
      "rel": "cancel",
      "method": "POST"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G/activate",
      "rel": "activate",
      "method": "POST"
    },
    {
      "href": "https://api-m.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-m.sandbox.paypal.com/v1/billing/subscriptions/I-EXCCE2B4J0D5/cancel",
            "rel": "cancel",
            "method": "POST"
        },
        {
            "href": "https://api-m.sandbox.paypal.com/v1/billing/subscriptions/I-EXCCE2B4J0D5",
            "rel": "edit",
            "method": "PATCH"
        },
        {
            "href": "https://api-m.sandbox.paypal.com/v1/billing/subscriptions/I-EXCCE2B4J0D5",
            "rel": "self",
            "method": "GET"
        },
        {
            "href": "https://api-m.sandbox.paypal.com/v1/billing/subscriptions/I-EXCCE2B4J0D5/suspend",
            "rel": "suspend",
            "method": "POST"
        },
        {
            "href": "https://api-m.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-m.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_address
shipping_amount
billing_info.outstanding_balance
subscriber.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-m.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-m.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-m.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-m.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-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 "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-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",
    "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-m.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.

PayPal Commerce Platform for Business

PayPal Commerce Platform for Marketplaces and Platforms

PayPal Commerce Platform for Enterprise

Docs Catalog

Reference

Developer Tools

Regional Codes

Subscriptions Management

Show subscription details

Update subscription

Suspend subscription

Cancel subscription

Activate subscription

Capture amount on subscription

List transactions for a subscription

Revise subscription

Revise a subscription using the Subscriptions API