Billing Plans API

You use billing plans and billing agreements to create subscriptions, or recurring payments, for goods or services.

Note: The terms billing agreement, subscription, and recurring payment mean the same thing.

A billing plan includes payment definitions and other details for a subscription. A plan must include at least one regular payment definition and, optionally, a trial payment definition. Each definition determines 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 also defines merchant preferences including how much it costs to set up the subscription, the URLs where customers can approve and cancel the subscription, and the action if the subscriber's initial payment fails. By default, a plan is not active when you create it. To activate it, you update its state to ACTIVE.

To create a subscription for goods or services, you base one or more billing agreements on an active plan.

To create an agreement from a plan, see Billing Plans and Agreements.

Billing Plans (resource group)

Use the /billing-plans resource to create, update, show details for, and list plans.

Create plan

POST /v1/payments/billing-plans
Creates a billing plan. In the JSON request body, include the plan details. A plan must include at least one regular payment definition and, optionally, a trial payment definition. Each payment definition specifies a billing period, which determines how often and for how long the subscriber is charged. A plan can specify a fixed or infinite number of payment cycles. A payment definition can optionally specify shipping fee and tax amounts. The default state of a new plan is CREATED. You must activate the plan by updating the plan state to ACTIVE before you can create an agreement from the plan.

Request

In the JSON request body, include the plan details including the following plan object properties:

  • name

    string

    required

    The plan name.

    Maximum length: 128.

  • description

    string

    required

    The plan description.

    Maximum length: 128.

  • type

    enum

    required

    The plan type. Indicates whether the payment definitions in the plan have a fixed number of or infinite payment cycles. Value is:
    • FIXED. The plan has a fixed number of payment cycles.
    • INFINITE. The plan has infinite, or 0, payment cycles.

    Allowed values: FIXED, INFINITE.

    Maximum length: 20.

  • payment_definitions

    array (contains the payment_definition object)

    required

    A payment definition, which determines how often and for how long the subscriber is charged. Includes the interval at which the subscriber is charged, the charge amount, and optional shipping fees and taxes.
  • merchant_preferences

    object

    The merchant preferences for this plan. Defines how much it costs to set up the subscription, the URLs where customers can approve and cancel the subscription, and the action if the subscriber's initial payment fails.
SDK samples: C#, JAVA, Node.js, PHP, Python

Sample Request

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"
  }
}'

Response

Returns a plan object with the billing plan state and a billing plan ID that uniquely identifies the plan.

  • id

    string

    The ID of the plan.

    Read only.

    Maximum length: 128.

  • name

    string

    The plan name.

    Maximum length: 128.

  • description

    string

    The plan description.

    Maximum length: 128.

  • type

    enum

    The plan type. Indicates whether the payment definitions in the plan have a fixed number of or infinite payment cycles. Value is:
    • FIXED. The plan has a fixed number of payment cycles.
    • INFINITE. The plan has infinite, or 0, payment cycles.

    Possible values: FIXED, INFINITE.

    Maximum length: 20.

  • state

    enum

    The plan status.

    Read only.

    Possible values: CREATED, ACTIVE, INACTIVE, DELETED.

  • create_time

    string

    The date and time when the plan was created, in Internet date and time format.

    Read only.

  • update_time

    string

    The date and time when the plan was updated, in Internet date and time format.

    Read only.

  • payment_definitions

    array (contains the payment_definition object)

    A payment definition, which determines how often and for how long the subscriber is charged. Includes the interval at which the subscriber is charged, the charge amount, and optional shipping fees and taxes.
  • terms

    array (contains the terms object)

    The plan terms.

    Read only.

  • merchant_preferences

    object

    The merchant preferences for this plan. Defines how much it costs to set up the subscription, the URLs where customers can approve and cancel the subscription, and the action if the subscriber's initial payment fails.
  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

Sample Response

{
  "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"
    }
  ]
}

Update plan

PATCH /v1/payments/billing-plans/plan-id

Replaces fields in a billing plan, by ID. In the JSON request body, include a patch object that specifies the operation to perform, one or more fields to update, and a new value for each updated field.

To activate a billing plan, submit a PATCH request to update the state from CREATED to ACTIVE.

Parameters

  • plan-id

    path string

    The ID of the billing plan to update.

Request

  • items

    array (contains the json_patch object)

    A JSON patch object that you can use to apply partial updates to resources.
SDK samples: C#, JAVA, Node.js, PHP, Python

Sample Request

curl -v -X PATCH https://api.sandbox.paypal.com/v1/payments/billing-plans/P-6EM196669U062173D7QCVDRA/ \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token" \
-d '[
  {
  "op": "replace",
  "path": "/merchant-preferences",
  "value": {
    "cancel_url": "http://www.cancel.com",
    "setup_fee": {
    "value": "5",
    "currency": "USD"
    }
  }
  }
]'

Sample Response

200 OK

Show plan details

GET /v1/payments/billing-plans/plan-id
Shows details for a billing plan, by ID.

Parameters

  • plan-id

    path string

    The ID of the billing plan for which to show details.
SDK samples: C#, JAVA, Node.js, PHP, Python

Sample Request

curl -v -X GET https://api.sandbox.paypal.com/v1/payments/billing-plans/P-7DC96732KA7763723UOPKETA \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token"

Response

Returns a plan object that includes a link that enables you to access billing plan information.

  • id

    string

    The ID of the plan.

    Read only.

    Maximum length: 128.

  • name

    string

    The plan name.

    Maximum length: 128.

  • description

    string

    The plan description.

    Maximum length: 128.

  • type

    enum

    The plan type. Indicates whether the payment definitions in the plan have a fixed number of or infinite payment cycles. Value is:
    • FIXED. The plan has a fixed number of payment cycles.
    • INFINITE. The plan has infinite, or 0, payment cycles.

    Possible values: FIXED, INFINITE.

    Maximum length: 20.

  • state

    enum

    The plan status.

    Read only.

    Possible values: CREATED, ACTIVE, INACTIVE, DELETED.

  • create_time

    string

    The date and time when the plan was created, in Internet date and time format.

    Read only.

  • update_time

    string

    The date and time when the plan was updated, in Internet date and time format.

    Read only.

  • payment_definitions

    array (contains the payment_definition object)

    A payment definition, which determines how often and for how long the subscriber is charged. Includes the interval at which the subscriber is charged, the charge amount, and optional shipping fees and taxes.
  • terms

    array (contains the terms object)

    The plan terms.

    Read only.

  • merchant_preferences

    object

    The merchant preferences for this plan. Defines how much it costs to set up the subscription, the URLs where customers can approve and cancel the subscription, and the action if the subscriber's initial payment fails.
  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

Sample Response

{
  "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-03223056L66578712UOPKETA",
      "name": "Trial payment definition",
      "type": "TRIAL",
      "frequency": "Week",
      "amount": {
        "currency": "USD",
        "value": "9.19"
      },
      "charge_models": [
        {
          "id": "CHM-6JY06508UT8026625UOPKETA",
          "type": "TAX",
          "amount": {
            "currency": "USD",
            "value": "2"
          }
        },
        {
          "id": "CHM-7XN63093LF858372XUOPKETA",
          "type": "SHIPPING",
          "amount": {
            "currency": "USD",
            "value": "1"
          }
        }
      ],
      "cycles": "2",
      "frequency_interval": "5"
    },
    {
      "id": "PD-0MF87809KK310750TUOPKETA",
      "name": "Regular payment definition",
      "type": "REGULAR",
      "frequency": "Month",
      "amount": {
        "currency": "USD",
        "value": "100"
      },
      "charge_models": [
        {
          "id": "CHM-1V202179WT9709019UOPKETA",
          "type": "TAX",
          "amount": {
            "currency": "USD",
            "value": "12"
          }
        },
        {
          "id": "CHM-89H01708244053321UOPKETA",
          "type": "SHIPPING",
          "amount": {
            "currency": "USD",
            "value": "10"
          }
        }
      ],
      "cycles": "12",
      "frequency_interval": "2"
    }
  ],
  "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"
    }
  ]
}

List plans

GET /v1/payments/billing-plans
Lists billing plans. To filter the plans that appear in the response, specify one or more optional query and pagination parameters.

Parameters

  • page

    query_string string

    The zero-indexed number of the first page that begins the set of pages that are returned in the response. Default is 0.
  • status

    query_string enum

    Filters the plans in the response by a plan status.

    Possible values: CREATED, ACTIVE, INACTIVE, DELETED.

  • page_size

    query_string string

    The number of plans to list on a single page. For example, if page_size is 10, each page shows ten plans. A valid value is a non-negative, non-zero integer. Default is 10.
  • total_required

    query_string string

    Indicates whether the response includes the total_items and total_pages fields. Value is yes or no.
SDK samples: C#, Node.js, PHP, Python

Sample Request

curl -v -X GET https://api.sandbox.paypal.com/v1/payments/billing-plans?page_size=3&status=ACTIVE&page_size=2&page=1&total_required=yes \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token"

Response

Lists billing plans in a plan list object. Note that this object includes only a partial plan resource for each returned plan, including basic information such as the plan ID, description, and state and a link that enables you to request full details about each returned plan. The response sample shows billing plans in the CREATED state. Links provide access to the next and previous records.

  • plans

    array (contains the plan object)

    A billing plan. You can base one or more agreements on an active plan.
  • total_items

    string

    The total number of plans in the list.

    Read only.

  • total_pages

    string

    The total number of pages in the response. The page_size request value determines how many plans appear on each page. The total_items and page_size request values are used to calculate the total number of pages in the response.

    Read only.

  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

Sample Response

{
  "total_items": "166",
  "total_pages": "83",
  "plans": [
    {
      "id": "P-7DC96732KA7763723UOPKETA",
      "state": "ACTIVE",
      "name": "Plan with Regular and Trial Payment Definitions",
      "description": "Plan with regular and trial billing payment definitions.",
      "type": "FIXED",
      "create_time": "2017-08-22T04:41:52.836Z",
      "update_time": "2017-08-22T04:41:53.169Z",
      "links": [
        {
          "href": "https://api.sandbox.paypal.com//v1/payments/billing-plans/P-7DC96732KA7763723UOPKETA",
          "rel": "self",
          "method": "GET"
        }
      ]
    },
    {
      "id": "P-1TV69435N82273154UPWDU4I",
      "state": "ACTIVE",
      "name": "Plan with Regular Payment Definition",
      "description": "Plan with one regular payment definition, minimal merchant preferences, and no shipping fees or tax.",
      "type": "INFINITE",
      "create_time": "2017-08-22T04:41:55.623Z",
      "update_time": "2017-08-22T04:41:56.055Z",
      "links": [
        {
          "href": "https://api.sandbox.paypal.com//v1/payments/billing-plans/P-1TV69435N82273154UPWDU4I",
          "rel": "self",
          "method": "GET"
        }
      ]
    }
  ],
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/billing-plans?page_size=2&page=1&start=3&status=active",
      "rel": "start",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/billing-plans?page_size=2&page=0&status=active",
      "rel": "previous_page",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/billing-plans?page_size=2&page=2&status=active",
      "rel": "next_page",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/billing-plans?page_size=2&page=82&status=active",
      "rel": "last",
      "method": "GET"
    }
  ]
}

Common object definitions

charge_models

  • id

    string

    The ID of the charge model.

    Read only.

    Maximum length: 128.

  • type

    enum

    The charge model type, which is tax or shipping.

    Possible values: TAX, SHIPPING.

    Maximum length: 20.

  • amount

    object

    The amount.

currency

  • currency

    string

    The three-letter ISO 4217 alphabetic currency code.
  • value

    string

    The amount up to N digits after the decimal separator, as defined in ISO 4217 for the appropriate currency code.

json_patch

  • op

    enum

    The operation to perform.

    Possible values: add, remove, replace, move, copy, test.

  • path

    string

    A JSON pointer. References a location in the target document where the operation is performed.
  • value

    see description

    The value to apply. The remove operation does not require a value.
    Possible types: number, integer, string, boolean, null, array, object
  • from

    string

    A JSON pointer. References the location in the target document from which to move the value. Required for the move operation.

json_patch_request

  • items

    (contains the json_patch object)

    A JSON patch object that you can use to apply partial updates to resources.

merchant_preferences

  • setup_fee

    object

    The set-up fee amount. Default is 0.
  • cancel_url

    string

    The URL where the subscriber can cancel the subscription.

    Maximum length: 1000.

  • return_url

    string

    The URL where the customer can approve the subscription.

    Maximum length: 1000.

  • notify_url

    string

    The URL where the subscriber is notified that the subscription was created. Read-only and reserved for future use.

    Read only.

    Maximum length: 1000.

  • max_fail_attempts

    string

    The maximum number of allowed failed payment attempts. Default is 0, which allows infinite failed payment attempts.
  • auto_bill_amount

    enum

    Indicates whether auto-billing is allowed for the outstanding balance of the agreement in the next payment cycle. Value is YES or NO. Default is NO.

    Possible values: YES, NO.

  • initial_fail_amount_action

    enum

    The action if the subscriber's initial payment fails. Default is CONTINUE.

    Possible values: CONTINUE, CANCEL.

  • accepted_payment_type

    string

    The payment types that are accepted for this plan. Read-only and reserved for future use.

    Read only.

  • char_set

    string

    The character set for this plan. Read-only and reserved for future use.

    Read only.

payment_definition

  • id

    string

    The ID of the payment definition.

    Read only.

    Maximum length: 128.

  • name

    string

    The payment definition name.

    Maximum length: 128.

  • type

    enum

    The payment definition type. Each plan must have at least one regular payment definition and, optionally, a trial payment definition. Each definition specifies how often and for how long the subscriber is charged.

    Possible values: TRIAL, REGULAR.

  • frequency_interval

    string

    The interval at which the subscriber is charged. Value cannot be greater than 12 months.
  • frequency

    enum

    The frequency of the payment in this definition.

    Possible values: WEEK, DAY, YEAR, MONTH.

  • cycles

    string

    The number of payment cycles. For infinite plans with a regular payment definition, set cycles to 0.
  • amount

    object

    The amount to charge at the end of each payment cycle for this definition.
  • charge_models

    array (contains the charge_models object)

    The shipping fee and tax information.

plan

  • id

    string

    The ID of the plan.

    Read only.

    Maximum length: 128.

  • name

    string

    The plan name.

    Maximum length: 128.

  • description

    string

    The plan description.

    Maximum length: 128.

  • type

    enum

    The plan type. Indicates whether the payment definitions in the plan have a fixed number of or infinite payment cycles. Value is:
    • FIXED. The plan has a fixed number of payment cycles.
    • INFINITE. The plan has infinite, or 0, payment cycles.

    Possible values: FIXED, INFINITE.

    Maximum length: 20.

  • state

    enum

    The plan status.

    Read only.

    Possible values: CREATED, ACTIVE, INACTIVE, DELETED.

  • create_time

    string

    The date and time when the plan was created, in Internet date and time format.

    Read only.

  • update_time

    string

    The date and time when the plan was updated, in Internet date and time format.

    Read only.

  • payment_definitions

    array (contains the payment_definition object)

    A payment definition, which determines how often and for how long the subscriber is charged. Includes the interval at which the subscriber is charged, the charge amount, and optional shipping fees and taxes.
  • terms

    array (contains the terms object)

    The plan terms.

    Read only.

  • merchant_preferences

    object

    The merchant preferences for this plan. Defines how much it costs to set up the subscription, the URLs where customers can approve and cancel the subscription, and the action if the subscriber's initial payment fails.
  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

plan_list

  • plans

    array (contains the plan object)

    A billing plan. You can base one or more agreements on an active plan.
  • total_items

    string

    The total number of plans in the list.

    Read only.

  • total_pages

    string

    The total number of pages in the response. The page_size request value determines how many plans appear on each page. The total_items and page_size request values are used to calculate the total number of pages in the response.

    Read only.

  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

terms

  • id

    string

    The ID of the terms.

    Read only.

    Maximum length: 128.

  • type

    enum

    The term type.

    Possible values: MONTHLY, WEEKLY, YEARLY.

  • max_billing_amount

    object

    The maximum amount to bill for this term.
  • occurrences

    string

    The number of times that money can be pulled during this term.
  • amount_range

    object

    The amount range for this term.
  • buyer_editable

    string

    Indicates whether the subscriber can edit the amount in this term.

Additional API information

Error messages

In addition to common REST API errors, the Billing Plans API can return the following errors. Corrective action is provided where possible.

  • INTERNAL_SERVICE_ERROR

    An internal service error has occurred. Resend the request at another time. If this error continues, contact PayPal Merchant Technical Support.

  • REQUIRED_SCOPE_MISSING

    Access token does not have required scope. Use the scope required for this request type to get buyer consent.

  • UNAUTHORIZED_ACCESS

    You don't have permission to access this resource. Pass a valid plan ID.

  • VALIDATION_ERROR

    Invalid request - see details. A validation issue occurred with your request.