Subscriptions Overview


Important: A new Subscriptions version is available. To integrate with the latest APIs, see the most recent integration guide.

PayPal Subscriptions lets you accept recurring payments for your service. When you set up Subscriptions, you can offer subscribers a trial period with special introductory rates or a regular rate. Subscribers receive billings according to the terms you specify, so you know automatically which payments you have and have not received.

You use billing plans to create a billing agreement, also referred to as a subscription, for a recurring PayPal payment for goods or services.

Subscriptions flow diagram

  1. Buyer clicks the Subscribe button.
  2. Buyer logs in or creates a PayPal account.
  3. Buyer agrees to the subscription plan.
  4. Buyer approval is complete.

Billing plans

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.

Billing agreements

After you activate a billing plan, you can create one or more billing agreements, or actual subscriptions, that you base on the plan. A billing agreement allows a merchant to charge a buyer's PayPal account when they purchase goods from them or use their service. An example of this would be an agreement to pay seller fees for listing items on an online store.

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 PayPal payment.

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.


Set up your development environment.