Create a new plan

Authorization

AuthorizationBearer <token>

Use the /v1/oauth2/token endpoint to obtain an access token and pass it as a Bearer token in the Authorization header.

FlowClient CredentialsToken URLhttps://api-m.sandbox.paypal.com/v1/oauth2/tokenInheader

Scopes

Read accessread
Write accesswrite

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

`application/json`

curl -X POST "https://api-m.sandbox.paypal.com/v1/commerce/billing/plans" \  -H "Content-Type: application/json" \  -d '{    "name": "UBB Plan - Pro",    "code": "ubb_plan_1753826420",    "billing_cycle": "WEEKLY",    "description": "Pro plan for pro UBB customers",    "amount": {      "value": 160,      "currency_code": "USD"    },    "trial_period": 0,    "pay_in_advance": true,    "usage_based_charges": [      {        "metric_id": "92c9175c-31a6-4d74-b607-ac3915796ab9",        "charge_model": "STANDARD",        "properties": {          "amount": "1.00"        },        "min_amount": {          "value": 1        }      }    ],    "minimum_commitment": {      "amount": {        "value": 100      },      "invoice_display_name": "Minimum Commitment",      "id": "cc82edfd-8198-4942-bed8-fcd7afb5191e",      "plan_code": "ubb_plan_1753826420",      "created_at": "2025-07-31T08:41:19Z",      "updated_at": "2025-07-31T08:41:19Z"    }  }'

{
  "name": "UBB Plan - Pro",
  "code": "ubb_plan_1753826420",
  "billing_cycle": "WEEKLY",
  "description": "Pro plan for pro UBB customers",
  "amount": {
    "value": 160,
    "currency_code": "USD"
  },
  "trial_period": 0,
  "pay_in_advance": true,
  "usage_based_charges": [
    {
      "id": "fggdgd5c-31a6-4d74-b607-ac3915796ab9",
      "metric_id": "92c9175c-31a6-4d74-b607-ac3915796ab9",
      "charge_model": "STANDARD",
      "properties": {
        "amount": "1.00"
      },
      "min_amount": {
        "value": 1,
        "currency_code": "USD"
      }
    }
  ],
  "minimum_commitment": {
    "amount": {
      "value": 100,
      "currency_code": "USD"
    },
    "invoice_display_name": "Minimum Commitment",
    "id": "cc82edfd-8198-4942-bed8-fcd7afb5191e",
    "plan_code": "ubb_plan_1753826420",
    "created_at": "2025-07-31T08:41:19Z"
  },
  "created_at": "2025-07-30T00:59:35Z",
  "id": "95de3538-3827-496b-89a0-120745360830"
}

{
  "name": "INVALID_REQUEST",
  "message": "Request is not well-formed, syntactically incorrect, or violates schema.",
  "debug_id": "dc99e3955cdd8",
  "details": [
    {
      "field": "/email",
      "value": "abc",
      "location": "body",
      "issue": "INVALID_PARAMETER_VALUE",
      "description": "The value of a field does not conform to the expected format."
    }
  ]
}

{
  "name": "NOT_AUTHORIZED",
  "message": "Authorization failed due to insufficient permissions.",
  "debug_id": "565f78f101498",
  "details": [
    {
      "issue": "PERMISSION_DENIED",
      "description": "You do not have permission to access or perform operations on this resource."
    }
  ]
}

{
  "name": "UNPROCESSABLE_ENTITY",
  "message": "The requested action could not be performed, semantically incorrect, or failed business validation.",
  "debug_id": "90957fca61718",
  "details": [
    {
      "field": "/email",
      "value": "[email protected]",
      "location": "body",
      "issue": "UNSUPPORTED_EMAIL",
      "description": "The email provided is not supported."
    }
  ]
}

{
  "name": "INTERNAL_SERVER_ERROR",
  "message": "An internal server error has occurred.",
  "debug_id": "90957fca61718"
}

Authorization

AuthorizationBearer <token>

Use the /v1/oauth2/token endpoint to obtain an access token and pass it as a Bearer token in the Authorization header.

FlowClient CredentialsToken URLhttps://api-m.sandbox.paypal.com/v1/oauth2/tokenInheader

Scopes

Read accessread
Write accesswrite

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name?string

code?string

billing_cycle?BillingCycle

The billing cycle indicating how often the subscription is charged

Value in"WEEKLY" | "MONTHLY" | "QUARTERLY" | "YEARLY"

description?string

amount?

trial_period?integer

pay_in_advance?boolean

tax_codes?array<string>

List of unique codes used to identify taxes to be applied.

minimum_commitment?

usage_based_charges?array<>

curl -X POST "https://api-m.sandbox.paypal.com/v1/commerce/billing/plans" \ -H "Content-Type: application/json" \ -d '{ "name": "UBB Plan - Pro", "code": "ubb_plan_1753826420", "billing_cycle": "WEEKLY", "description": "Pro plan for pro UBB customers", "amount": { "value": 160, "currency_code": "USD" }, "trial_period": 0, "pay_in_advance": true, "usage_based_charges": [ { "metric_id": "92c9175c-31a6-4d74-b607-ac3915796ab9", "charge_model": "STANDARD", "properties": { "amount": "1.00" }, "min_amount": { "value": 1 } } ], "minimum_commitment": { "amount": { "value": 100 }, "invoice_display_name": "Minimum Commitment", "id": "cc82edfd-8198-4942-bed8-fcd7afb5191e", "plan_code": "ubb_plan_1753826420", "created_at": "2025-07-31T08:41:19Z", "updated_at": "2025-07-31T08:41:19Z" } }'

{ "name": "UBB Plan - Pro", "code": "ubb_plan_1753826420", "billing_cycle": "WEEKLY", "description": "Pro plan for pro UBB customers", "amount": { "value": 160, "currency_code": "USD" }, "trial_period": 0, "pay_in_advance": true, "usage_based_charges": [ { "id": "fggdgd5c-31a6-4d74-b607-ac3915796ab9", "metric_id": "92c9175c-31a6-4d74-b607-ac3915796ab9", "charge_model": "STANDARD", "properties": { "amount": "1.00" }, "min_amount": { "value": 1, "currency_code": "USD" } } ], "minimum_commitment": { "amount": { "value": 100, "currency_code": "USD" }, "invoice_display_name": "Minimum Commitment", "id": "cc82edfd-8198-4942-bed8-fcd7afb5191e", "plan_code": "ubb_plan_1753826420", "created_at": "2025-07-31T08:41:19Z" }, "created_at": "2025-07-30T00:59:35Z", "id": "95de3538-3827-496b-89a0-120745360830" }

{ "name": "INVALID_REQUEST", "message": "Request is not well-formed, syntactically incorrect, or violates schema.", "debug_id": "dc99e3955cdd8", "details": [ { "field": "/email", "value": "abc", "location": "body", "issue": "INVALID_PARAMETER_VALUE", "description": "The value of a field does not conform to the expected format." } ] }

{ "name": "NOT_AUTHORIZED", "message": "Authorization failed due to insufficient permissions.", "debug_id": "565f78f101498", "details": [ { "issue": "PERMISSION_DENIED", "description": "You do not have permission to access or perform operations on this resource." } ] }

{ "name": "UNPROCESSABLE_ENTITY", "message": "The requested action could not be performed, semantically incorrect, or failed business validation.", "debug_id": "90957fca61718", "details": [ { "field": "/email", "value": "[email protected]", "location": "body", "issue": "UNSUPPORTED_EMAIL", "description": "The email provided is not supported." } ] }

Create a new plan

Authorization

Request Body

Response Body

201application/json

400application/json

403application/json

422application/json

500application/json

Response of a Standard Charge Model with required properties

Response of a Package Charge Model with required properties

Response of a Percentage Charge Model with required properties

Response of a Graduated Charge Model with required properties

Response of a Volume Charge Model with required properties

On this page

If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more

Create a new plan

Authorization

Request Body

Response Body

201application/json

400application/json

403application/json

422application/json

500application/json

Response of a Standard Charge Model with required properties

Response of a Package Charge Model with required properties

Response of a Percentage Charge Model with required properties

Response of a Graduated Charge Model with required properties

Response of a Volume Charge Model with required properties

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`