> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paypal.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Create subscriptions
Limited Release
A subscription is a customer's enrollment in a pricing plan with specific billing configuration.
Subscriptions connect the following:
* Customers who receive service and are billed for usage.
* Pricing plans that define metrics, pricing models, and features.
* Billing configuration that determines when billing starts and which payment method to use.
## Prerequisites
* Create and set up all
pricing plans
that you offer to customers.
* Register customers
who use Usage-based Billing plans.
## 1. Understand subscription configuration
Before you create a subscription, collect these configuration details from your customer and system. Then, you can make a POST call to the Create subscription endpoint to send the information to PayPal.
**Customer information**
**External customer ID**: Set this to the unique identifier (`external_id`) returned when you created the customer. This value links the subscription to a specific customer.
**Plan details**
* **Plan code**: Set this to the code for the pricing plan your customer selected.
* **Plan overrides**: You can negotiate special contracts with customers. These contracts can include custom discounts and price adjustments that differ from your standard plan. When you create the subscription, you can override the base plan with these negotiated terms.
You can override these plan elements:
* Subscription invoice display name
* Subscription fee
* Plan trial period
* Plan taxes
* Charge properties (except the charge model)
* Charge minimum spending
* Charge taxes
* Charge invoice display name
* Minimum commitment amount and display name
If you later update the original plan, you can choose to cascade those updates to subscriptions with overridden plan values. You can use the `cascading_updates` parameter in your plan update request to do this.
**Billing setup**
* **Billing time**: Choose when billing cycles start. You can start them on a calendar date (like the 1st of each month) or on the same date the subscription begins each month.
* **Start date**: Send the date when your customer's subscription starts.
* **End date**: Optionally specify when the subscription should end if it has a defined term.
**Additional required information**
**External ID**: Create and set a unique identifier for your subscription.
## 2. Create subscription
Use a valid access token and make a POST call to the `/v1/commerce/billing/subscriptions` endpoint. Include the following parameters:
| Parameter | Action |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `name`
string | Provide a human-readable name for the subscription. |
| `external_customer_id`
Required, string | Set to the `external_id` returned when you registered the customer. |
| `external_id`
Required, string | Set a unique identifier for this subscription. Use only alphanumeric characters, underscores, and hyphens. |
| `plan_code`
Required, string | Set to the `code` returned when you created the pricing plan. |
| `billing_time`
string | Set to `CALENDAR` to align billing cycles to calendar periods (for example, bill on the 1st of each month) or `ANNIVERSARY` to start billing cycles from the subscription date. |
| `start_date`
string | Set the date when the subscription begins in ISO 8601 format with timezone. Usage tracking starts from this date. |
| `end_date`
string | Set the date when the subscription ends in ISO 8601 format with timezone. Optional for subscriptions with a specific end date. |
| `plan_overrides`
object | Add plan customizations based on negotiated contracts.
Possible values: `amount`, `name`, `trial_period`, `tax_codes`, `charges`, `minimum_commitment`. |
| `plan_overrides.tax_codes`
array | Provide an array of tax codes to apply at the plan level (for example, `["standard_vat"]`). |
| `plan_overrides.charges[].id`
Required when plan\_overrides.charges\[] provided, string | Set to the `usage_based_charges[].id` returned when you created the pricing plan. |
| `plan_overrides.charges[].tax_codes`
array | Provide an array of tax codes to apply to this charge (for example, `["standard_vat"]`). |
| `plan_overrides.minimum_commitment.tax_codes`
array | Provide an array of tax codes to apply to the minimum commitment (for example, `["standard_vat"]`). |
For information on all parameters, see API reference.
```shell lines expandable title="Sample request" theme={null}
curl -X POST -L 'https://api-m.sandbox.paypal.com/v1/commerce/billing/subscriptions' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ' \
-d '{
"name": "Premium Monthly Subscription",
"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-30T01:54:40Z",
"end_date": "2025-09-09T04:26:24Z",
"plan_overrides": {
"amount": {
"value": 20.05,
"currency_code": "USD"
},
"name": "Plan-Name-_1753840215",
"trial_period": 14,
"tax_codes": [
"standard_vat"
],
"charges": [
{
"id": "2e097d19-1350-4baf-8add-5d19ecef8113",
"properties": {
"amount": "100.15"
},
"min_amount": {
"value": 200.00
},
"tax_codes": [
"standard_vat"
]
}
],
"minimum_commitment": {
"invoice_display_name": "Negotiated Minimum Commitment",
"amount": {
"value": 500.00
},
"tax_codes": [
"standard_vat"
]
}
}
}'
```
```json lines expandable title="Sample response" theme={null}
{
"id": "b71befc2-4799-402c-9d13-ca1f72759c64",
"name": "Premium Monthly Subscription",
"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.05,
"currency_code": "USD"
},
"taxes": [
{
"id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
"name": "TVA",
"code": "standard_vat",
"description": "French standard VAT",
"rate": "20.00",
"created_at": "2023-07-06T14:35:58Z"
}
],
"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.00,
"currency_code": "USD"
},
"taxes": [
{
"id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
"name": "TVA",
"code": "standard_vat",
"description": "French standard VAT",
"rate": "20.00",
"created_at": "2023-07-06T14:35:58Z"
}
]
}
],
"minimum_commitment": {
"amount": {
"value": 500.00,
"currency_code": "USD"
},
"taxes": [
{
"id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
"name": "TVA",
"code": "standard_vat",
"description": "French standard VAT",
"rate": "20.00",
"created_at": "2023-07-06T14:35:58Z"
}
],
"invoice_display_name": "Negotiated Minimum Commitment",
"plan_code": "Plan-Code-_1753840215",
"created_at": "2025-07-31T13:00:04Z",
"updated_at": "2025-07-31T13:00:04Z"
}
},
"start_date": "2025-07-30T01:54:40Z",
"end_date": "2025-09-09T04:26:24Z",
"created_at": "2022-07-30T00:00:00Z",
"current_period_start": "2025-07-30T01:54:40Z",
"current_period_end": "2025-08-05T23:59:59Z"
}
```
A successful call returns a `201 Created` response. The response includes the following parameter:
| Parameter | Description | Further action |
| -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `external_id`
string | Unique identifier for the subscription. | Use this `external_id` when querying current and past usage data. |
For information on all parameters, see API reference.
## 3. Understand subscription lifecycle and manage subscriptions
Subscriptions progress through distinct states throughout their lifecycle. These states determine billing behavior and available management actions.
To monitor a subscription's current state, make a GET call to the /v1/commerce/billing/subscriptions/{id} endpoint and review the `status` parameter. The subscription's lifecycle state determines the management actions you can perform to ensure proper subscription handling.
| State | Description | Customer billing | Possible management actions |
| -------------- | ------------------------------------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **ACTIVE** | Subscription is running and tracking usage | Customer is billed according to plan | Update subscription details – customer ID, plan configuration, billing setting, and customer metadata.
Cancel subscription |
| **PENDING** | Subscription is created but not yet started | No billing occurs | Update subscription details - limited to plan configuration
|
| **CANCELED** | Pending subscription is canceled before becoming active | No billing occurs | Subscription cannot be modified |
| **TERMINATED** | Previously active subscription is ended | No billing occurs, final invoice may be generated | Subscription cannot be modified |