Skip to main content
POST
/
subscriptions
curl --request POST \
  --url https://api-m.paypal.com/v1/commerce/billing/subscriptions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1753840218",
  "external_id": "Subscription_External_1",
  "plan_code": "Plan-Code-1753840215"
}'
{
  "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"
}

Authorizations

​
Authorization
string
header
required

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

Body

application/json
​
external_customer_id
string
required

External reference to the customer

Example:

"client-jkl101"

​
external_id
string
required

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

Example:

"SUB_1752779018503"

​
plan_code
string
required

The plan code

Example:

"Plan-Code-1753840215"

​
plan_overrides
object
​
name
string

The name of the subscription.

Example:

"Subscription_1"

​
start_date
string<date-time>

Date and time in ISO 8601 format. The effective start date of the subscription; can be past, current, or future. Date must be provided in ISO 8601 format

Example:

"2025-06-01T00:00:00Z"

​
end_date
string<date-time>

Date and time in ISO 8601 format. The subscription will terminate on this date without renewal. Date must be provided in ISO 8601 format

Example:

"2028-01-01T00:00:00Z"

​
billing_time
enum<string>
default:CALENDAR

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

Available options:
CALENDAR,
ANNIVERSARY
Example:

"CALENDAR"

Response

Subscription created successfully

​
external_customer_id
string
required

External reference to the customer

Example:

"client-jkl101"

​
external_id
string
required

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

Example:

"SUB_1752779018503"

​
plan_code
string
required

The plan code

Example:

"Plan-Code-1753840215"

​
id
string

Unique identifier for the subscription

Example:

"b71befc2-4799-402c-9d13-ca1f72759c64"

​
status
enum<string>

The status of the subscription

Available options:
PENDING,
ACTIVE,
TERMINATED,
CANCELED
Example:

"ACTIVE"

​
plan_overrides
object
​
canceled_at
string<date-time>

Date and time in ISO 8601 format. The date at which a pending subscription is canceled.

Example:

"2025-01-01T00:00:00Z"

​
terminated_at
string<date-time>

Date and time in ISO 8601 format. The date at which an active subscription is canceled.

Example:

"2025-01-01T00:00:00Z"

​
current_period_start
string<date-time>

Date and time in ISO 8601 format. Start date of the current billing period

Example:

"2025-05-01T00:00:00Z"

​
current_period_end
string<date-time>

End date of the current billing period Date and time in ISO 8601 format.

Example:

"2023-10-01T12:00:00Z"

​
trial_ended_at
string<date-time>

Date and time in ISO 8601 format. The date when the free trial is ended, represented in ISO 8601 date format

Example:

"2025-05-01T00:00:00Z"

​
name
string

The name of the subscription.

Example:

"Subscription_1"

​
start_date
string<date-time>

Date and time in ISO 8601 format. The effective start date of the subscription; can be past, current, or future. Date must be provided in ISO 8601 format

Example:

"2025-06-01T00:00:00Z"

​
end_date
string<date-time>

Date and time in ISO 8601 format. The subscription will terminate on this date without renewal. Date must be provided in ISO 8601 format

Example:

"2028-01-01T00:00:00Z"

​
billing_time
enum<string>
default:CALENDAR

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

Available options:
CALENDAR,
ANNIVERSARY
Example:

"CALENDAR"

⌘I