Plans

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

List plans

get

/v1/billing/plans

Lists billing plans.

Required scopes

This endpoint requires the following scopes:

: Manage plan & subscription

Authorizations

OAuth2clientCredentialsRequired

Oauth 2.0 authentication

Token URL:

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

400

Request is not well-formed, syntactically incorrect, or violates schema.

application/json

401

Authentication failed due to missing authorization header, or invalid authentication credentials.

application/json

403

Authorization failed due to insufficient permissions.

application/json

404

The specified resource does not exist.

application/json

500

An internal server error has occurred.

application/json

default

The default response.

application/json

get

/v1/billing/plans

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

/v1/billing/plans

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

Required scopes

This endpoint requires the following scopes:

: Manage plan & subscription

Authorizations

OAuth2clientCredentialsRequired

Oauth 2.0 authentication

Token URL:

Header parameters

PreferstringOptional

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

201

A successful request returns the HTTP 201 Created status code and a JSON response body that shows billing plan details.

application/json

400

Bad Request. Request is not well-formed, syntactically incorrect, or violates schema.

application/json

401

Authentication failed due to missing authorization header, or invalid authentication credentials.

application/json

403

Authorization failed due to insufficient permissions.

application/json

422

The requested action could not be performed, semantically incorrect, or failed business validation.

application/json

500

An internal server error has occurred.

application/json

default

The default response.

application/json

post

/v1/billing/plans

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

/v1/billing/plans/{id}

Shows details for a plan, by ID.

Required scopes

This endpoint requires the following scopes:

: Manage plan & subscription

Authorizations

OAuth2clientCredentialsRequired

Oauth 2.0 authentication

Token URL:

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

401

Authentication failed due to missing authorization header, or invalid authentication credentials.

application/json

403

Authorization failed due to insufficient permissions.

application/json

404

The specified resource does not exist.

application/json

500

An internal server error has occurred.

application/json

default

The default response.

application/json

get

/v1/billing/plans/{id}

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

/v1/billing/plans/{id}

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

Required scopes

This endpoint requires the following scopes:

: Manage plan & subscription

Authorizations

OAuth2clientCredentialsRequired

Oauth 2.0 authentication

Token URL:

Path parameters

idstringRequired

The ID of the subscription.

Bodyobject · Patch[]

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.

400

Request is not well-formed, syntactically incorrect, or violates schema.

application/json

401

Authentication failed due to missing authorization header, or invalid authentication credentials.

application/json

403

Authorization failed due to insufficient permissions.

application/json

404

The specified resource does not exist.

application/json

422

The requested action could not be performed, semantically incorrect, or failed business validation.

application/json

500

An internal server error has occurred.

application/json

default

The default response.

application/json

patch

/v1/billing/plans/{id}

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

/v1/billing/plans/{id}/activate

Activates a plan, by ID.

Required scopes

This endpoint requires the following scopes:

: Manage plan & subscription

Authorizations

OAuth2clientCredentialsRequired

Oauth 2.0 authentication

Token URL:

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.

401

Authentication failed due to missing authorization header, or invalid authentication credentials.

application/json

403

Authorization failed due to insufficient permissions.

application/json

404

The specified resource does not exist.

application/json

422

The requested action could not be performed, semantically incorrect, or failed business validation.

application/json

500

An internal server error has occurred.

application/json

default

The default response.

application/json

post

/v1/billing/plans/{id}/activate

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

/v1/billing/plans/{id}/deactivate

Deactivates a plan, by ID.

Required scopes

This endpoint requires the following scopes:

: Manage plan & subscription

Authorizations

OAuth2clientCredentialsRequired

Oauth 2.0 authentication

Token URL:

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.

401

Authentication failed due to missing authorization header, or invalid authentication credentials.

application/json

403

Authorization failed due to insufficient permissions.

application/json

404

The specified resource does not exist.

application/json

422

The requested action could not be performed, semantically incorrect, or failed business validation.

application/json

500

An internal server error has occurred.

application/json

default

The default response.

application/json

post

/v1/billing/plans/{id}/deactivate

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

/v1/billing/plans/{id}/update-pricing-schemes

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

Required scopes

This endpoint requires the following scopes:

: Manage plan & subscription

Authorizations

OAuth2clientCredentialsRequired

Oauth 2.0 authentication

Token URL:

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.

400

Bad Request. Request is not well-formed, syntactically incorrect, or violates schema.

application/json

401

Authentication failed due to missing authorization header, or invalid authentication credentials.

application/json

403

Authorization failed due to insufficient permissions.

application/json

404

The specified resource does not exist.

application/json

422

The requested action could not be performed, semantically incorrect, or failed business validation.

application/json

500

An internal server error has occurred.

application/json

default

The default response.

application/json

post

/v1/billing/plans/{id}/update-pricing-schemes

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 Reference NextSubscriptions

Last updated 7 months ago

Was this helpful?

Good night

hashtagList plans

hashtagCreate plan

hashtagShow plan details

hashtagUpdate plan

hashtagActivate plan

hashtagDeactivate plan

hashtagUpdate pricing

List plans

Create plan

Show plan details

Update plan

Activate plan

Deactivate plan

Update pricing