Billing Plans and Agreements

You use billing plans and billing agreements to create an agreement for a recurring credit card, bank card, or PayPal payment for goods or services.

Billing plans

A billing plan includes payment definitions and other details. A plan must include at least one regular payment definition and, optionally, a trial payment definition. A payment definition indicates how often and for how long the subscriber is charged. A plan can specify a type, which indicates whether the payment definitions in the plan have a fixed or infinite number of payment cycles.

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 plan includes two payment definitions, each with a fixed number of payment cycles, and a set of merchant preferences:

{
  "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": "http://www.paypal.com",
    "cancel_url": "http://www.paypal.com/cancel",
    "auto_bill_amount": "YES",
    "initial_fail_amount_action": "CONTINUE",
    "max_fail_attempts": "0"
  }
}

The plan includes these payment definitions:

Payment definition The customer is charged How often and for how long
Regular $100 plus $10 shipping fee and $12 tax Every two months for twelve payment cycles.
Trial $9.19 plus $1 shipping fee and $2 tax Every five weeks for two payment cycles.

By default, a plan is not active when you create it. To activate it, you must update its state to ACTIVE.

Billing agreements

After you activate a plan, you can create one or more billing agreements, or actual subscriptions, that you base on the plan. The agreement inherits information from the referenced plan. You also supply customer and payment information and, optionally, can override the referenced plan's merchant preferences and shipping fees and taxes.

You can create an agreement for a recurring credit card, bank card, or PayPal payment.

An agreement for a credit card or bank card payment executes automatically and no further action is necessary.

The customer must approve an agreement for a PayPal payment before you can execute it:

  1. You create the agreement. The response includes links to get the customer's approval and execute the plan. Both links include a payment token.

  2. The customer approves the agreement and enters customer and payment details.

  3. You execute the agreement by using the execute link and the payment token.

The agreement becomes an actual subscription and the customer becomes a subscriber.

Integration steps

1. Required Meet the prerequisites.
2. Required Create a plan.
3. Required Activate a plan.
4. Required Create an agreement.
5. Required for PayPal payments only Get customer approval.
6. Required for PayPal payments only Execute an agreement.

Prerequisites

Before you can use the Billing Plans and Billing Agreements APIs, you must make your first call and learn about REST API authentication and headers.

Then, become familiar with basic payment processes, such as how to accept credit card payments.

If you are a non-US developer, see International Developer Questions.

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 plan must include at least one regular payment definition and, optionally, a trial payment definition. A payment definition indicates how often and for how long the subscriber is charged. A plan can specify a type, which indicates whether the payment definitions in the plan have a fixed or infinite number of payment cycles.

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": "http://www.paypal.com",
    "cancel_url": "http://www.paypal.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": "http://www.paypal.com",
    "cancel_url": "http://www.paypal.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.

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.

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.

When you create an agreement for a credit card or bank card payment, the agreement executes automatically. No further action is necessary.

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": "http://www.example.com/success",
      "cancel_url": "http://www.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.

Get customer approval

When you create an agreement for a PayPal payment, the customer must approve the agreement before you can execute it. When the customer approves an agreement, he or she subscribes to the agreement.

Note: Agreements for credit card and bank card payments automatically execute when you create them.

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.

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

Complete these billing plan operations, as needed:

Complete these billing agreement operations, as needed:

Additional information