Skip to main content
GET
/
subscriptions
/
{id}
Get a subscription by ID
curl --request GET \
  --url https://api-m.paypal.com/v1/commerce/billing/subscriptions/{id} \
  --header 'Authorization: Bearer <token>'
{
  "name": "API Count Usage Subscription1",
  "external_customer_id": "CUSTOMER_1752766931284",
  "external_id": "SUB_1752779018503",
  "plan_code": "PLAN_CODE_1752694759534",
  "billing_time": "CALENDAR",
  "status": "ACTIVE",
  "plan_overrides": {
    "amount": {
      "value": 0.2,
      "currency_code": "USD"
    },
    "name": "Basic API Plan",
    "trial_period": 14,
    "charges": [
      {
        "id": "99fa7a6b-d005-43a5-8bab-0df7a2a721fb",
        "metric_id": "2e097d19-1350-4baf-8add-5d19ecef8113",
        "charge_model": "STANDARD",
        "properties": {
          "amount": "0.01"
        },
        "min_amount": {
          "value": 200,
          "currency_code": "USD"
        }
      }
    ]
  },
  "start_date": "2025-07-17T19:03:47Z",
  "created_at": "2025-07-30T01:54:40Z",
  "current_period_start": "2025-07-17T19:03:47Z",
  "current_period_end": "2025-07-31T23:59:59Z",
  "trial_ended_at": "2025-07-31T19:03:47Z",
  "id": "073a0619-f59c-4e7c-8dd4-02c83e583105"
}

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.

Path Parameters

​
external_subscription_id
string
required

The unique external identifier of the subscription

Response

A subscription object

​
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