subscriptions

Integrate Subscriptions

Here's how to integrate PayPal Subscriptions:

1. Create a plan

To create a plan, specify the plan details in the JSON request body.

A billing plan includes payment definitions and other details. A payment definition indicates how often and for how long the subscriber is charged. A plan must include at least one regular payment definition and, optionally, a trial payment definition. A plan can specify a type, which indicates whether the payment definitions in the plan have a fixed or infinite number of payment cycles. Billing plans are used to create billing agreements, which are also referred to as subscriptions.

The plan can also define these optional merchant preferences:

  • How much it costs to set up the subscription.

  • The URLs where the customer can approve the subscription and the subscriber can cancel the subscription.

  • The maximum number of allowed failed payment attempts.

  • Whether PayPal automatically bills the outstanding balance in the next billing cycle. The outstanding balance is the total amount of any previously failed scheduled payments.

  • The action if the subscriber's initial payment fails. By default, the subscription remains active and the failed payment amount is added to the outstanding balance. If auto-billing is enabled, PayPal automatically bills the outstanding balance in the next billing cycle.

This sample request creates a plan that defines two payment definitions, each with a fixed number of payment cycles and a set of merchant preferences:

curl -v -X POST https://api.sandbox.paypal.com/v1/payments/billing-plans/ \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "name": "Plan with Regular and Trial Payment Definitions",
  "description": "Plan with regular and trial payment definitions.",
  "type": "fixed",
  "payment_definitions": [
  {
    "name": "Regular payment definition",
    "type": "REGULAR",
    "frequency": "MONTH",
    "frequency_interval": "2",
    "amount":
    {
      "value": "100",
      "currency": "USD"
    },
    "cycles": "12",
    "charge_models": [
    {
      "type": "SHIPPING",
      "amount":
      {
        "value": "10",
        "currency": "USD"
      }
    },
    {
      "type": "TAX",
      "amount":
      {
        "value": "12",
        "currency": "USD"
      }
    }]
  },
  {
    "name": "Trial payment definition",
    "type": "trial",
    "frequency": "week",
    "frequency_interval": "5",
    "amount":
    {
      "value": "9.19",
      "currency": "USD"
    },
    "cycles": "2",
    "charge_models": [
    {
      "type": "SHIPPING",
      "amount":
      {
        "value": "1",
        "currency": "USD"
      }
    },
    {
      "type": "TAX",
      "amount":
      {
        "value": "2",
        "currency": "USD"
      }
    }]
  }],
  "merchant_preferences":
  {
    "setup_fee":
    {
      "value": "1",
      "currency": "USD"
    },
    "return_url": "https://example.com/return",
    "cancel_url": "https://example.com/cancel",
    "auto_bill_amount": "YES",
    "initial_fail_amount_action": "CONTINUE",
    "max_fail_attempts": "0"
  }
}'

A successful request returns the HTTP 201 status code and a JSON response that includes an id and the plan details. You use the ID in a subsequent call to activate the plan.

{
  "id": "P-7DC96732KA7763723UOPKETA",
  "state": "CREATED",
  "name": "Plan with Regular and Trial Payment Definitions",
  "description": "Plan with regular and trial payment definitions.",
  "type": "FIXED",
  "payment_definitions": [
    {
      "id": "PD-0MF87809KK310750TUOPKETA",
      "name": "Regular payment definition",
      "type": "REGULAR",
      "frequency": "Month",
      "amount": {
        "currency": "USD",
        "value": "100"
      },
      "charge_models": [
        {
          "id": "CHM-89H01708244053321UOPKETA",
          "type": "SHIPPING",
          "amount": {
            "currency": "USD",
            "value": "10"
          }
        },
        {
          "id": "CHM-1V202179WT9709019UOPKETA",
          "type": "TAX",
          "amount": {
            "currency": "USD",
            "value": "12"
          }
        }
      ],
      "cycles": "12",
      "frequency_interval": "2"
    },
    {
      "id": "PD-03223056L66578712UOPKETA",
      "name": "Trial payment definition",
      "type": "TRIAL",
      "frequency": "Week",
      "amount": {
        "currency": "USD",
        "value": "9.19"
      },
      "charge_models": [
        {
          "id": "CHM-7XN63093LF858372XUOPKETA",
          "type": "SHIPPING",
          "amount": {
            "currency": "USD",
            "value": "1"
          }
        },
        {
          "id": "CHM-6JY06508UT8026625UOPKETA",
          "type": "TAX",
          "amount": {
            "currency": "USD",
            "value": "2"
          }
        }
      ],
      "cycles": "2",
      "frequency_interval": "5"
    }
  ],
  "merchant_preferences": {
    "setup_fee": {
      "currency": "USD",
      "value": "1"
    },
    "max_fail_attempts": "0",
    "return_url": "https://example.com/return",
    "cancel_url": "https://example.com/cancel",
    "auto_bill_amount": "YES",
    "initial_fail_amount_action": "CONTINUE"
  },
  "create_time": "2017-06-16T07:40:20.940Z",
  "update_time": "2017-06-16T07:40:20.940Z",
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/billing-plans/P-7DC96732KA7763723UOPKETA",
      "rel": "self",
      "method": "GET"
    }
  ]
}

Next, you must activate a plan before your customer can approve an agreement that is based on this plan.

2. Activate a plan

By default, a plan is not active when you create it.

This sample request updates a plan's state to ACTIVE:

curl -v -X PATCH https://api.sandbox.paypal.com/v1/payments/billing-plans/P-7DC96732KA7763723UOPKETA/ \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token" \
-d '[{
  "op": "replace",
  "path": "/",
  "value": {
    "state": "ACTIVE"
  }
}]'

A successful request returns the HTTP 200 OK status code.

Next, create an agreement that is based on the plan.

3. Create an agreement

This sample request creates an agreement for a PayPal payment that is based on the plan with ID P-7DC96732KA7763723UOPKETA.

curl -v -X POST https://api.sandbox.paypal.com/v1/payments/billing-agreements/ \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "name": "Magazine Subscription",
  "description": "Monthly agreement with a regular monthly payment definition and two-month trial payment definition.",
  "start_date": "2017-12-22T09:13:49Z",
  "plan":
  {
    "id": "P-7DC96732KA7763723UOPKETA"
  },
  "payer":
  {
    "payment_method": "paypal"
  },
  "shipping_address":
  {
    "line1": "751235 Stout Drive",
    "line2": "0976249 Elizabeth Court",
    "city": "Quimby",
    "state": "IA",
    "postal_code": "51049",
    "country_code": "US"
  }
}'

A successful call returns agreement details and approval and execute URLs. Both HATEOAS links include a payment token.

Note: When you create an agreement for a PayPal payment, you must get customer approval and execute the agreement.

The payment token in this response is EC-7WN97463LN263864T:

{
  "name": "Magazine Subscription",
  "description": "Monthly agreement with a regular monthly payment definition and two-month trial payment definition.",
  "plan":
  {
    "id": "P-3NL67884YE672133CEXBTJTA",
    "state": "ACTIVE",
    "name": "Magazine Subscription",
    "description": "Monthly agreement with a regular monthly payment definition and two-month trial payment definition.",
    "type": "FIXED",
    "payment_definitions": [
    {
      "id": "PD-7AP59297JL233383BEXBTJTA",
      "name": "Regular monthly payment definition",
      "type": "REGULAR",
      "frequency": "Month",
      "amount":
      {
        "currency": "USD",
        "value": "5.99"
      },
      "cycles": "10",
      "charge_models": [
      {
        "id": "CHM-0808282002866834SEXBTJTA",
        "type": "TAX",
        "amount":
        {
          "currency": "USD",
          "value": "0.29"
        }
      },
      {
        "id": "CHM-86952323Y27891226EXBTJTA",
        "type": "SHIPPING",
        "amount":
        {
          "currency": "USD",
          "value": "0.2"
        }
      }],
      "frequency_interval": "1"
    },
    {
      "id": "PD-3F67327340580952AEXBTJTA",
      "name": "Free trial payment definition",
      "type": "TRIAL",
      "frequency": "Month",
      "amount":
      {
        "currency": "USD",
        "value": "0"
      },
      "cycles": "2",
      "charge_models": [],
      "frequency_interval": "1"
    }],
    "merchant_preferences":
    {
      "setup_fee":
      {
        "currency": "USD",
        "value": "0.4"
      },
      "max_fail_attempts": "2",
      "return_url": "https://example.com/return",
      "cancel_url": "https://example.com/cancel",
      "auto_bill_amount": "YES",
      "initial_fail_amount_action": "CONTINUE"
    }
  },
  "start_date": "2017-12-22T09:13:49Z",
  "links": [
  {
    "href": "https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=EC-7WN97463LN263864T",
    "rel": "approval_url",
    "method": "REDIRECT"
  },
  {
    "href": "https://api.sandbox.paypal.com/v1/payments/billing-agreements/EC-7WN97463LN263864T/agreement-execute",
    "rel": "execute",
    "method": "POST"
  }]
}

Note the approval and execute URLs from this response.

Next, for PayPal payments only, redirect the customer to the approval URL to get approval for the agreement.

4. Get customer approval

When you create an agreement for a PayPal payment, the customer must approve the agreement before you can execute it. By approving an agreement, the customer subscribes to it.

Direct the customer to the approval URL from the create agreement response. The customer approves, and subscribes to, the agreement and enters his or her customer and payment details. After you get the customer and payment details, you can execute the agreement. Then, it becomes an active subscription.

5. Execute an agreement

After the customer approves an agreement for a recurring PayPal payment, you execute the agreement.

This sample request shows how to use the execute link with the payment token from the previous sample response to execute the agreement:

curl -v -X POST https://api.sandbox.paypal.com/v1/payments/billing-agreements/EC-7WN97463LN263864T/agreement-execute \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token"

A successful call returns agreement details:

{
  "id": "I-1TJ3GAGG82Y9",
  "state": "Active",
  "description": "Monthly agreement with free trial payment definition.",
  "payer":
  {
    "payment_method": "paypal",
    "status": "unverified",
    "payer_info":
    {
      "email": "johndoe@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "payer_id": "NEW8A85AK4ET4",
      "shipping_address":
      {
        "recipient_name": "John Doe",
        "line1": "751235 Stout Drive",
        "line2": "0976249 Elizabeth Court",
        "city": "Quimby",
        "state": "IA",
        "postal_code": "51049",
        "country_code": "US"
      }
    }
  },
  "plan":
  {
    "payment_definitions": [
    {
      "type": "TRIAL",
      "frequency": "Month",
      "amount":
      {
        "value": "0.00",
        "currency": "USD"
      },
      "cycles": "2",
      "charge_models": [
      {
        "type": "TAX",
        "amount":
        {
          "value": "0.00",
          "currency": "USD"
        }
      },
      {
        "type": "SHIPPING",
        "amount":
        {
          "value": "0.00",
          "currency": "USD"
        }
      }],
      "frequency_interval": "1"
    },
    {
      "type": "REGULAR",
      "frequency": "Month",
      "amount":
      {
        "value": "5.99",
        "currency": "USD"
      },
      "cycles": "10",
      "charge_models": [
      {
        "type": "TAX",
        "amount":
        {
          "value": "0.29",
          "currency": "USD"
        }
      },
      {
        "type": "SHIPPING",
        "amount":
        {
          "value": "0.20",
          "currency": "USD"
        }
      }],
      "frequency_interval": "1"
    }],
    "merchant_preferences":
    {
      "setup_fee":
      {
        "value": "0.40",
        "currency": "USD"
      },
      "max_fail_attempts": "2",
      "auto_bill_amount": "YES"
    },
    "links": [],
    "currency_code": "USD"
  },
  "start_date": "2017-12-22T09:13:49Z",
  "shipping_address":
  {
    "recipient_name": "John Doe",
    "line1": "751235 Stout Drive",
    "line2": "0976249 Elizabeth Court",
    "city": "Quimby",
    "state": "IA",
    "postal_code": "51049",
    "country_code": "US"
  },
  "agreement_details":
  {
    "outstanding_balance":
    {
      "value": "0.00",
      "currency": "USD"
    },
    "cycles_remaining": "2",
    "cycles_completed": "0",
    "next_billing_date": "2017-11-22T09:13:49Z",
    "last_payment_date": "2017-10-22T09:13:49Z",
    "last_payment_amount":
    {
      "value": "0.40",
      "currency": "USD"
    },
    "final_payment_date": "2017-12-22T09:13:49Z",
    "failed_payment_count": "0"
  },
  "links": [
  {
    "href": "https://api.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9",
    "rel": "self",
    "method": "GET"
  }]
}

Next

Customize integration with additional billing plan and billing agreement operations.

Feedback

Have feedback?

Let us know.