HelpLog inSign up

Plans

Use the /billing/plans resource to create and manage plans.

List plans

get

Lists billing plans.

Authorizations
Query parameters
product_idstring · min: 6 · max: 50Optional

Filters the response by a Product ID.

plan_idsstring · min: 3 · max: 270Optional

Filters the response by list of plan IDs. Filter supports upto 10 plan IDs.

page_sizeinteger · min: 1 · max: 20Optional

The number of items to return in the response.

Default: 10
pageinteger · min: 1 · max: 100000Optional

A non-zero integer which is the start index of the entire list of items to return in the response. The combination of page=1 and page_size=20 returns the first 20 items. The combination of page=2 and page_size=20 returns the next 20 items.

Default: 1
total_requiredbooleanOptional

Indicates whether to show the total count in the response.

Default: false
Header parameters
PreferstringOptional

The preferred server response upon successful completion of the request. Value is:return=minimal. The server returns a minimal response to optimize communication between the API caller and the server. A minimal response includes the id, status and HATEOAS links.return=representation. The server returns a complete resource representation, including the current state of the resource.

Default: return=minimal
Responses
200
A successful request returns the HTTP `200 OK` status code and a JSON response body that lists billing plans.
application/json
get
GET /v1/billing/plans HTTP/1.1
Host: api-m.sandbox.paypal.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "plans": [
    {
      "id": "text",
      "product_id": "text",
      "name": "text",
      "status": "CREATED",
      "description": "text",
      "billing_cycles": [
        {
          "pricing_scheme": {
            "version": 1,
            "fixed_price": {
              "currency_code": "text",
              "value": "text"
            },
            "pricing_model": "VOLUME",
            "tiers": [
              {
                "starting_quantity": "text",
                "ending_quantity": "text",
                "amount": {
                  "currency_code": "text",
                  "value": "text"
                }
              }
            ],
            "create_time": "text",
            "update_time": "text"
          },
          "frequency": {
            "interval_unit": "DAY",
            "interval_count": 1
          },
          "tenure_type": "REGULAR",
          "sequence": 1,
          "total_cycles": 1
        }
      ],
      "payment_preferences": {
        "auto_bill_outstanding": true,
        "setup_fee": {
          "currency_code": "text",
          "value": "text"
        },
        "setup_fee_failure_action": "CANCEL",
        "payment_failure_threshold": 0
      },
      "taxes": {
        "percentage": "text",
        "inclusive": true
      },
      "quantity_supported": false,
      "create_time": "text",
      "update_time": "text",
      "links": [
        {
          "href": "text",
          "rel": "text",
          "method": "GET"
        }
      ]
    }
  ],
  "total_items": 1,
  "total_pages": 1,
  "links": [
    {
      "href": "text",
      "rel": "text",
      "method": "GET"
    }
  ]
}

Create plan

post

Creates a plan that defines pricing and billing cycle details for subscriptions.

Authorizations
Header parameters
PreferstringOptional

The preferred server response upon successful completion of the request. Value is:return=minimal. The server returns a minimal response to optimize communication between the API caller and the server. A minimal response includes the id, status and HATEOAS links.return=representation. The server returns a complete resource representation, including the current state of the resource.

Default: return=minimal
PayPal-Request-IdstringOptional

The server stores keys for 72 hours.

Body

The create plan request details.

product_idstring · min: 6 · max: 50Required

The ID of the product created through Catalog Products API.

namestring · min: 1 · max: 127Required

The plan name.

statusstring · enum · min: 1 · max: 24Optional

The initial state of the plan. Allowed input values are CREATED and ACTIVE.

Default: ACTIVEPattern: ^[A-Z_]+$Possible values:
descriptionstring · min: 1 · max: 127Optional

The detailed description of the plan.

quantity_supportedbooleanOptional

Indicates whether you can subscribe to this plan by providing a quantity for the goods or service.

Default: false
Responses
200
A successful request returns the HTTP `200 OK` status code and a JSON response body that shows billing plan details.
application/json
post
POST /v1/billing/plans HTTP/1.1
Host: api-m.sandbox.paypal.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 925

{
  "product_id": "PROD-XXCD1234QWER65782",
  "name": "Video Streaming Service Plan",
  "description": "Video Streaming Service basic plan",
  "status": "ACTIVE",
  "billing_cycles": [
    {
      "frequency": {
        "interval_unit": "MONTH",
        "interval_count": 1
      },
      "tenure_type": "TRIAL",
      "sequence": 1,
      "total_cycles": 2,
      "pricing_scheme": {
        "fixed_price": {
          "value": "3",
          "currency_code": "USD"
        }
      }
    },
    {
      "frequency": {
        "interval_unit": "MONTH",
        "interval_count": 1
      },
      "tenure_type": "TRIAL",
      "sequence": 2,
      "total_cycles": 3,
      "pricing_scheme": {
        "fixed_price": {
          "value": "6",
          "currency_code": "USD"
        }
      }
    },
    {
      "frequency": {
        "interval_unit": "MONTH",
        "interval_count": 1
      },
      "tenure_type": "REGULAR",
      "sequence": 3,
      "total_cycles": 12,
      "pricing_scheme": {
        "fixed_price": {
          "value": "10",
          "currency_code": "USD"
        }
      }
    }
  ],
  "payment_preferences": {
    "auto_bill_outstanding": true,
    "setup_fee": {
      "value": "10",
      "currency_code": "USD"
    },
    "setup_fee_failure_action": "CONTINUE",
    "payment_failure_threshold": 3
  },
  "taxes": {
    "percentage": "10",
    "inclusive": false
  }
}
{
  "id": "P-5ML4271244454362WXNWU5NQ",
  "product_id": "PROD-XXCD1234QWER65782",
  "name": "Video Streaming Service Plan",
  "description": "Video Streaming Service basic plan",
  "status": "ACTIVE",
  "billing_cycles": [
    {
      "frequency": {
        "interval_unit": "MONTH",
        "interval_count": 1
      },
      "tenure_type": "TRIAL",
      "sequence": 1,
      "total_cycles": 2,
      "pricing_scheme": {
        "fixed_price": {
          "value": "3",
          "currency_code": "USD"
        },
        "version": 1,
        "create_time": "2020-05-27T12:13:51Z",
        "update_time": "2020-05-27T12:13:51Z"
      }
    },
    {
      "frequency": {
        "interval_unit": "MONTH",
        "interval_count": 1
      },
      "tenure_type": "TRIAL",
      "sequence": 2,
      "total_cycles": 3,
      "pricing_scheme": {
        "fixed_price": {
          "currency_code": "USD",
          "value": "6"
        },
        "version": 1,
        "create_time": "2020-05-27T12:13:51Z",
        "update_time": "2020-05-27T12:13:51Z"
      }
    },
    {
      "frequency": {
        "interval_unit": "MONTH",
        "interval_count": 1
      },
      "tenure_type": "REGULAR",
      "sequence": 3,
      "total_cycles": 12,
      "pricing_scheme": {
        "fixed_price": {
          "currency_code": "USD",
          "value": "10"
        },
        "version": 1,
        "create_time": "2020-05-27T12:13:51Z",
        "update_time": "2020-05-27T12:13:51Z"
      }
    }
  ],
  "payment_preferences": {
    "auto_bill_outstanding": true,
    "setup_fee": {
      "value": "10",
      "currency_code": "USD"
    },
    "setup_fee_failure_action": "CONTINUE",
    "payment_failure_threshold": 3
  },
  "taxes": {
    "percentage": "10",
    "inclusive": false
  },
  "create_time": "2020-05-27T12:13:51Z",
  "update_time": "2020-05-27T12:13:51Z",
  "links": [
    {
      "href": "https://api-m.paypal.com/v1/billing/plans/P-5ML4271244454362WXNWU5NQ",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api-m.paypal.com/v1/billing/plans/P-5ML4271244454362WXNWU5NQ",
      "rel": "edit",
      "method": "PATCH"
    },
    {
      "href": "https://api-m.paypal.com/v1/billing/plans/P-5ML4271244454362WXNWU5NQ/deactivate",
      "rel": "deactivate",
      "method": "POST"
    },
    {
      "href": "https://api-m.paypal.com/v1/billing/plans/P-5ML4271244454362WXNWU5NQ/update-pricing-schemes",
      "rel": "edit",
      "method": "POST"
    }
  ]
}

Show plan details

get

Shows details for a plan, by ID.

Authorizations
Path parameters
idstringRequired

The ID of the subscription.

Responses
200
A successful request returns the HTTP `200 OK` status code and a JSON response body that shows plan details.
application/json
get
GET /v1/billing/plans/{id} HTTP/1.1
Host: api-m.sandbox.paypal.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "id": "text",
  "product_id": "text",
  "name": "text",
  "status": "CREATED",
  "description": "text",
  "billing_cycles": [
    {
      "pricing_scheme": {
        "version": 1,
        "fixed_price": {
          "currency_code": "text",
          "value": "text"
        },
        "pricing_model": "VOLUME",
        "tiers": [
          {
            "starting_quantity": "text",
            "ending_quantity": "text",
            "amount": {
              "currency_code": "text",
              "value": "text"
            }
          }
        ],
        "create_time": "text",
        "update_time": "text"
      },
      "frequency": {
        "interval_unit": "DAY",
        "interval_count": 1
      },
      "tenure_type": "REGULAR",
      "sequence": 1,
      "total_cycles": 1
    }
  ],
  "payment_preferences": {
    "auto_bill_outstanding": true,
    "setup_fee": {
      "currency_code": "text",
      "value": "text"
    },
    "setup_fee_failure_action": "CANCEL",
    "payment_failure_threshold": 0
  },
  "taxes": {
    "percentage": "text",
    "inclusive": true
  },
  "quantity_supported": false,
  "create_time": "text",
  "update_time": "text",
  "links": [
    {
      "href": "text",
      "rel": "text",
      "method": "GET"
    }
  ]
}

Update plan

patch

Updates a plan with the CREATED or ACTIVE status. For an INACTIVE plan, you can make only status updates. You can patch these attributes and objects:

Attribute or object
Operations

description

replace

payment_preferences.auto_bill_outstanding

replace

taxes.percentage

replace

payment_preferences.payment_failure_threshold

replace

payment_preferences.setup_fee

replace

payment_preferences.setup_fee_failure_action

replace

name

replace

Authorizations
Path parameters
idstringRequired

The ID of the subscription.

Body

An array of JSON patch objects to apply partial updates to resources.

opstring · enumRequired

The operation.

Possible values:
pathstringOptional

The JSON Pointer to the target document location at which to complete the operation.

valueanyOptional

The value to apply. The remove operation does not require a value.

fromstringOptional

The JSON Pointer to the target document location from which to move the value. Required for the move operation.

Responses
204
A successful request returns the HTTP `204 No Content` status code with no JSON response body.
patch
PATCH /v1/billing/plans/{id} HTTP/1.1
Host: api-m.sandbox.paypal.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 55

[
  {
    "op": "add",
    "path": "text",
    "value": null,
    "from": "text"
  }
]
No content

Activate plan

post

Activates a plan, by ID.

Authorizations
Path parameters
idstringRequired

The ID of the subscription.

Responses
204
A successful request returns the HTTP `204 No Content` status code with no JSON response body.
post
POST /v1/billing/plans/{id}/activate HTTP/1.1
Host: api-m.sandbox.paypal.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

No content

Deactivate plan

post

Deactivates a plan, by ID.

Authorizations
Path parameters
idstringRequired

The ID of the subscription.

Responses
204
A successful request returns the HTTP `204 No Content` status code with no JSON response body.
post
POST /v1/billing/plans/{id}/deactivate HTTP/1.1
Host: api-m.sandbox.paypal.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

No content

Update pricing

post

Updates pricing for a plan. For example, you can update a regular billing cycle from $5 per month to $7 per month.

Authorizations
Path parameters
idstringRequired

The ID of the subscription.

Body

The update pricing scheme request details.

Responses
204
A successful request returns the HTTP `204 No Content` status code with no JSON response body.
post
POST /v1/billing/plans/{id}/update-pricing-schemes HTTP/1.1
Host: api-m.sandbox.paypal.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 429

{
  "pricing_schemes": [
    {
      "billing_cycle_sequence": 1,
      "pricing_scheme": {
        "fixed_price": {
          "value": "50",
          "currency_code": "USD"
        }
      }
    },
    {
      "billing_cycle_sequence": 2,
      "pricing_scheme": {
        "fixed_price": {
          "value": "100",
          "currency_code": "USD"
        },
        "pricing_model": "VOLUME",
        "tiers": [
          {
            "starting_quantity": "1",
            "ending_quantity": "1000",
            "amount": {
              "value": "150",
              "currency_code": "USD"
            }
          },
          {
            "starting_quantity": "1001",
            "amount": {
              "value": "250",
              "currency_code": "USD"
            }
          }
        ]
      }
    }
  ]
}
No content
PreviousAPI ReferenceNextSubscriptions

Was this helpful?