---
title: "Retrieve lifetime usage for a specific subscription"
method: GET
path: "/subscriptions/{external_subscription_id}/lifetime-usage"
tags: ["Subscriptions"]
---

# Retrieve lifetime usage for a specific subscription

`GET /subscriptions/{external_subscription_id}/lifetime-usage`

## Request

- Base URL: `https://api-m.sandbox.paypal.com`
- URL: `https://api-m.sandbox.paypal.com/subscriptions/{external_subscription_id}/lifetime-usage`
- Auth: OAuth 2
  - Client credentials
  - Token URL: `/api/oauth-proxy` scopes: `read`, `write`
- TypeScript: <https://skmtc.dev/paypal/apis/usage-based-billing-api/docs/subscriptions/:external_subscription_id/lifetime-usage/get.ts> (a function with typed inputs; its response is checked against the schema)

## Path parameters

- `external_subscription_id` string, required

## Response `200`

Returns the lifetime usage for the specified subscription.

- LifetimeUsage: Represents the lifetime usage metrics for a given subscription.
  - `external_subscription_id` string: Unique external identifier of the subscription.
  - `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.
    - `value` number, required: The amount value in the corresponding currency unit (e.g., two decimals for USD, no decimals for JPY).
    - `currency_code` string, required: Currency code in ISO 4217 format.
  - `invoiced_usage_amount` object: The total usage amount, that has been invoiced for this subscription, provided by your own application.
    - `value` number, required: The amount value in the corresponding currency unit (e.g., two decimals for USD, no decimals for JPY).
    - `currency_code` string, required: Currency code in ISO 4217 format.
  - `current_usage_amount` object: The total usage amount, accumulated for the subscription during the current billing period
    - `value` number, required: The amount value in the corresponding currency unit (e.g., two decimals for USD, no decimals for JPY).
    - `currency_code` string, required: Currency code in ISO 4217 format.
  - `from` string, date-time: The start date and time (with timezone) of the tracked lifetime usage for the subscription.
  - `to` string, date-time: The end date and time (with timezone) of the tracked lifetime usage for the subscription.
  - `usage_thresholds` UsageThreshold[]: An array of usage thresholds configured in the subscription's plan.
    - `amount` object: The usage threshold amount
      - `value` number, required: The amount value in the corresponding currency unit (e.g., two decimals for USD, no decimals for JPY).
      - `currency_code` string, required: Currency code in ISO 4217 format.
    - `completion_ratio` number, double: The ratio (between 0 and 1) representing the proportion of the threshold amount that has been used.
    - `reached_at` string, date-time: The date and time (in ISO 8601 format with timezone) when this usage threshold was reached.

## Other responses

- `403`: Authorization failed due to insufficient permissions.
- `404`: Resource Not Found.
- `500`: Internal Server Error - An unexpected error occurred

---

[API](https://skmtc.dev/paypal/apis/usage-based-billing-api.md) - [All operations](https://skmtc.dev/paypal/apis/usage-based-billing-api/llms.txt) - [OpenAPI document](https://skmtc.dev/paypal/apis/usage-based-billing-api/revisions/22fb46514ac4?raw)