Skip to main content
GET
/
subscriptions
/
{external_subscription_id}
/
lifetime-usage
Retrieve lifetime usage for a specific subscription
curl --request GET \
  --url https://api-m.sandbox.paypal.com/v1/commerce/billing/subscriptions/{external_subscription_id}/lifetime-usage \
  --header 'Authorization: Bearer <token>'
{
  "external_subscription_id": "Subscription_External_1",
  "external_historical_usage_amount": {
    "value": 0,
    "currency_code": "USD"
  },
  "invoiced_usage_amount": {
    "value": 0,
    "currency_code": "USD"
  },
  "current_usage_amount": {
    "value": 0,
    "currency_code": "USD"
  },
  "from": "2025-07-31T12:59:15Z",
  "to": "2025-08-01T07:04:39Z"
}

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

Returns the lifetime usage for the specified subscription.

Represents the lifetime usage metrics for a given subscription.

​
external_subscription_id
string

Unique external identifier of the subscription.

Example:

"1a901a90-1a90-1a90-1a90-1a901a901a90"

​
external_historical_usage_amount
object

The total historical usage amount for this subscription, representing usage accumulated prior to the start of invoiced and current usage tracking.

​
invoiced_usage_amount
object

The total usage amount, that has been invoiced for this subscription, provided by your own application.

​
current_usage_amount
object

The total usage amount, accumulated for the subscription during the current billing period

​
from
string<date-time>

The start date and time (with timezone) of the tracked lifetime usage for the subscription.

Example:

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

​
to
string<date-time>

The end date and time (with timezone) of the tracked lifetime usage for the subscription.

Example:

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

​
usage_thresholds
object[]

An array of usage thresholds configured in the subscription's plan.