Create a new subscription

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/subscriptions" \  -H "Content-Type: application/json" \  -d '{    "name": "API Count Usage Subscription1",    "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1753840218",    "external_id": "Subscription_External_1",    "plan_code": "Plan-Code-1753840215",    "billing_time": "ANNIVERSARY",    "start_date": "2025-07-30T04:26:24Z",    "end_date": "2025-09-09T04:26:24Z",    "plan_overrides": {      "amount": {        "value": 20,        "currency_code": "USD"      },      "name": "Plan-Name-_1753840215",      "trial_period": 14,      "charges": [        {          "id": "2e097d19-1350-4baf-8add-5d19ecef8113",          "properties": {            "amount": "100.15"          },          "min_amount": {            "value": 200,            "currency_code": "USD"          }        }      ]    }  }'

{
  "id": "b71befc2-4799-402c-9d13-ca1f72759c64",
  "name": "API Count Usage Subscription1",
  "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1753840218",
  "external_id": "Subscription_External_1",
  "plan_code": "Plan-Code-1753840215",
  "billing_time": "ANNIVERSARY",
  "status": "ACTIVE",
  "plan_overrides": {
    "amount": {
      "value": 20,
      "currency_code": "USD"
    },
    "name": "Plan-Name-_1753840215",
    "trial_period": 14,
    "charges": [
      {
        "id": "99fa7a6b-d005-43a5-8bab-0df7a2a721fb",
        "metric_id": "d0682999-67a0-418e-b29b-3757426db01f",
        "charge_model": "STANDARD",
        "properties": {
          "amount": "100.15"
        },
        "min_amount": {
          "value": 200,
          "currency_code": "USD"
        }
      }
    ]
  },
  "current_period_start": "2025-07-30T01:54:40Z",
  "current_period_end": "2025-08-05T23:59:59Z",
  "start_date": "2025-07-30T04:26:24Z",
  "end_date": "2025-09-09T04:26:24Z"
}

{
  "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": "sdfwdj@sdfs.com",
      "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

The name of the subscription.

start_date?string

Formatdate-time

end_date?string

Formatdate-time

external_customer_id*string

External reference to the customer

Match^[a-zA-Z0-9_-]*$

external_id*SubscriptionExternalId

The subscription external unique identifier supplied by client. Must contain only alphanumeric characters, underscores, and hyphens.

Match^[a-zA-Z0-9_-]*$

plan_code*string

The plan code

billing_time?BillingTime

The billing time for the subscription, which can be set as either anniversary or calendar

Default"CALENDAR"

Value in"CALENDAR" | "ANNIVERSARY"

plan_overrides?

curl -X POST "https://api-m.sandbox.paypal.com/v1/commerce/billing/subscriptions" \ -H "Content-Type: application/json" \ -d '{ "name": "API Count Usage Subscription1", "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1753840218", "external_id": "Subscription_External_1", "plan_code": "Plan-Code-1753840215", "billing_time": "ANNIVERSARY", "start_date": "2025-07-30T04:26:24Z", "end_date": "2025-09-09T04:26:24Z", "plan_overrides": { "amount": { "value": 20, "currency_code": "USD" }, "name": "Plan-Name-_1753840215", "trial_period": 14, "charges": [ { "id": "2e097d19-1350-4baf-8add-5d19ecef8113", "properties": { "amount": "100.15" }, "min_amount": { "value": 200, "currency_code": "USD" } } ] } }'

{ "id": "b71befc2-4799-402c-9d13-ca1f72759c64", "name": "API Count Usage Subscription1", "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1753840218", "external_id": "Subscription_External_1", "plan_code": "Plan-Code-1753840215", "billing_time": "ANNIVERSARY", "status": "ACTIVE", "plan_overrides": { "amount": { "value": 20, "currency_code": "USD" }, "name": "Plan-Name-_1753840215", "trial_period": 14, "charges": [ { "id": "99fa7a6b-d005-43a5-8bab-0df7a2a721fb", "metric_id": "d0682999-67a0-418e-b29b-3757426db01f", "charge_model": "STANDARD", "properties": { "amount": "100.15" }, "min_amount": { "value": 200, "currency_code": "USD" } } ] }, "current_period_start": "2025-07-30T01:54:40Z", "current_period_end": "2025-08-05T23:59:59Z", "start_date": "2025-07-30T04:26:24Z", "end_date": "2025-09-09T04:26:24Z" }

{ "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": "sdfwdj@sdfs.com", "location": "body", "issue": "UNSUPPORTED_EMAIL", "description": "The email provided is not supported." } ] }

Create a new subscription

Authorization

Request Body

Response Body

201application/json

400application/json

403application/json

422application/json

500application/json

Example SimpleSubscriptionCreate

Example SubscriptionCreationWithPlanOverrides

Example SubscriptionCreationWithPlanOverridesAlongWithMinimumCommitment

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 subscription

Authorization

Request Body

Response Body

201application/json

400application/json

403application/json

422application/json

500application/json

Example SimpleSubscriptionCreate

Example SubscriptionCreationWithPlanOverrides

Example SubscriptionCreationWithPlanOverridesAlongWithMinimumCommitment

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`