> ## 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.

# Poll customer's usage

<div className="m-badge-page-wrapper">
  <Badge stroke color="orange" size="sm">Limited Release</Badge>
</div>

Usage monitoring helps you track customer consumption of metrics and send alerts when usage exceeds your set limits. You can monitor usage in two ways:

* **Poll usage endpoints**: Make API requests to retrieve current and past usage data.
* <a href="/limited-release/usage-based-billing/monitor-usage/set-up-alerts" target="_blank" rel="noopener noreferrer">Subscribe to webhooks</a>: Receive automatic notifications when usage crosses a threshold.

This page covers the polling approach. When you poll usage data, you [retrieve current usage](#get-current-usage) at frequent intervals, derive insights, and take appropriate actions. For example, if usage exceeds a threshold, you can restrict services or send alerts to customers.
You can also [review past usage](#get-past-usage) to understand usage patterns and set thresholds.

## Get current usage

Use a <a href="/developer/how-to/api/get-started#2-get-an-access-token" target="_blank" rel="noopener noreferrer">valid access token</a> and make a GET call to the `/v1/commerce/billing/customers/{external_customer_id}/current_usage?subscription_id={subscription_id}` endpoint. Include the following parameters:

* **Path parameter**: `external_customer_id` is the `external_id` you provided when <a href="/limited-release/usage-based-billing/set-up-billing-process/register-customers#2-register-customer-profile" target="_blank" rel="noopener noreferrer">registering the customer</a>.
* **Query parameter**: `subscription_id` is the `external_id` you provided when you <a href="/limited-release/usage-based-billing/set-up-billing-process/create-subscriptions#2-create-subscription" target="_blank" rel="noopener noreferrer">created the subscription</a>.

<CodeGroup>
  ```shell lines title="Sample request" theme={null}
  curl -X GET 'https://api-m.sandbox.paypal.com/v1/commerce/billing/customers/5eb02857-a71e-4ea2-bcf9-1753826282/current_usage?subscription_id=sub_01H3YT8P7Q5R3S1T2U0V4W9X8' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>'
  ```

  ```json lines expandable title="Sample response" theme={null}
  {
    "from_datetime": "2024-01-01T00:00:00Z",
    "to_datetime": "2024-01-31T23:59:59Z",
    "issuing_date": "2024-01-31",
    "total_amount": { "currency_code": "USD", "value": 270.00 },
    "taxes_amount": { "currency_code": "USD", "value": 27.50 },
    "charges_usage": [
      {
        "units": "150.0",
        "events_count": 150,
        "amount": {
          "currency_code": "USD",
          "value": 75.00
        },
        "charge": {
          "id": "1c31a90-1c31-1c31-1c31-1c311c311c31",
          "metric_id": "metric_01H3YT8P7Q5R3S1T2U0V4W9X8",
          "charge_model": "STANDARD",
          "properties": {
            "amount": "0.50"
          },
          "min_amount": {
            "value": 0.01,
            "currency_code": "USD"
          }
        },
        "metric": {
          "name": "API Calls",
          "code": "api_calls",
          "aggregation_type": "COUNT"
        }
      },
      {
        "units": "2400.0",
        "events_count": 2400,
        "amount": {
          "currency_code": "USD",
          "value": 120.00
        },
        "charge": {
          "id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
          "metric_id": "metric_02H3YT8P7Q5R3S1T2U0V4W9Y9",
          "charge_model": "STANDARD",
          "properties": {
            "amount": "0.05"
          },
          "min_amount": {
            "value": 0.01,
            "currency_code": "USD"
          }
        },
        "metric": {
          "name": "Storage GB-Hours",
          "code": "storage_gb_hours",
          "aggregation_type": "SUM"
        }
      },
      {
        "units": "500.0",
        "events_count": 500,
        "amount": {
          "currency_code": "USD",
          "value": 75.00
        },
        "charge": {
          "id": "1b561b56-1b56-1b56-1b56-1b561b561b56",
          "metric_id": "metric_03H3YT8P7Q5R3S1T2U0V4W9Z0",
          "charge_model": "STANDARD",
          "properties": {
            "amount": "0.15"
          },
          "min_amount": {
            "value": 0.01,
            "currency_code": "USD"
          }
        },
        "metric": {
          "name": "Bandwidth MB",
          "code": "bandwidth_mb",
          "aggregation_type": "SUM"
        }
      }
    ]
  }
  ```
</CodeGroup>

A successful call returns a `200 OK` response with current usage data for the customer.

## Get past usage

Use a <a href="/developer/how-to/api/get-started#2-get-an-access-token" target="_blank" rel="noopener noreferrer">valid access token</a> and make a GET call to the `/v1/commerce/billing/customers/{external_customer_id}/past_usage?subscription_id={subscription_id}` endpoint. Include the following parameters:

* **Path parameter**: `external_customer_id` is the `external_id` you provided when <a href="/limited-release/usage-based-billing/set-up-billing-process/register-customers" target="_blank" rel="noopener noreferrer">registering the customer</a>.
* **Query parameter**: `subscription_id` is the `external_id` you provided when you <a href="/limited-release/usage-based-billing/set-up-billing-process/create-subscriptions#2-create-subscription" target="_blank" rel="noopener noreferrer">created the subscription</a>.

For information on all parameters, see <a href="/reference/api/rest/customers/get-past-usage-for-a-customer" target="_blank" rel="noopener noreferrer">API reference</a>.

<Note>
  Past usage data is available once a billing period closes, regardless of subscription status.
</Note>

<CodeGroup>
  ```shell lines title="Sample request" theme={null}
  curl -X GET 'https://api-m.sandbox.paypal.com/v1/commerce/billing/customers/5eb02857-a71e-4ea2-bcf9-1753826282/past_usage?subscription_id=sub_01H3YT8P7Q5R3S1T2U0V4W9X8' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>'
  ```

  ```json lines expandable title="Sample response" theme={null}
  {
    "usage_periods": [
      {
        "from_datetime": "2023-12-01T00:00:00Z",
        "to_datetime": "2023-12-31T23:59:59Z",
        "issuing_date": "2023-12-31",
        "total_amount": { "currency_code": "USD", "value": 250.00 },
        "taxes_amount": { "currency_code": "USD", "value": 25.00 },
        "charges_usage": [
          {
            "units": "200.0",
            "events_count": 200,
            "amount": {
              "currency_code": "USD",
              "value": 100.00
            },
            "charge": {
              "id": "1c31a90-1c31-1c31-1c31-1c311c311c31",
              "metric_id": "metric_01H3YT8P7Q5R3S1T2U0V4W9X8",
              "charge_model": "STANDARD",
              "properties": {
                "amount": "0.50"
              },
              "min_amount": {
                "value": 0.01,
                "currency_code": "USD"
              }
            },
            "metric": {
              "name": "API Calls",
              "code": "api_calls",
              "aggregation_type": "COUNT"
            }
          },
          {
            "units": "3000.0",
            "events_count": 3000,
            "amount": {
              "currency_code": "USD",
              "value": 150.00
            },
            "charge": {
              "id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
              "metric_id": "metric_02H3YT8P7Q5R3S1T2U0V4W9Y9",
              "charge_model": "STANDARD",
              "properties": {
                "amount": "0.05"
              },
              "min_amount": {
                "value": 0.01,
                "currency_code": "USD"
              }
            },
            "metric": {
              "name": "Storage GB-Hours",
              "code": "storage_gb_hours",
              "aggregation_type": "SUM"
            }
          }
        ]
      },
      {
        "from_datetime": "2023-11-01T00:00:00Z",
        "to_datetime": "2023-11-30T23:59:59Z",
        "issuing_date": "2023-11-30",
        "total_amount": { "currency_code": "USD", "value": 210.00 },
        "taxes_amount": { "currency_code": "USD", "value": 21.00 },
        "charges_usage": [
          {
            "units": "120.0",
            "events_count": 120,
            "amount": {
              "currency_code": "USD",
              "value": 60.00
            },
            "charge": {
              "id": "1c31a90-1c31-1c31-1c31-1c311c311c31",
              "metric_id": "metric_01H3YT8P7Q5R3S1T2U0V4W9X8",
              "charge_model": "STANDARD",
              "properties": {
                "amount": "0.50"
              },
              "min_amount": {
                "value": 0.01,
                "currency_code": "USD"
              }
            },
            "metric": {
              "name": "API Calls",
              "code": "api_calls",
              "aggregation_type": "COUNT"
            }
          },
          {
            "units": "1800.0",
            "events_count": 1800,
            "amount": {
              "currency_code": "USD",
              "value": 90.00
            },
            "charge": {
              "id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
              "metric_id": "metric_02H3YT8P7Q5R3S1T2U0V4W9Y9",
              "charge_model": "STANDARD",
              "properties": {
                "amount": "0.05"
              },
              "min_amount": {
                "value": 0.01,
                "currency_code": "USD"
              }
            },
            "metric": {
              "name": "Storage GB-Hours",
              "code": "storage_gb_hours",
              "aggregation_type": "SUM"
            }
          }
        ]
      },
      {
        "from_datetime": "2023-10-01T00:00:00Z",
        "to_datetime": "2023-10-31T23:59:59Z",
        "issuing_date": "2023-10-31",
        "total_amount": { "currency_code": "USD", "value": 155.00 },
        "taxes_amount": { "currency_code": "USD", "value": 15.50 },
        "charges_usage": [
          {
            "units": "95.0",
            "events_count": 95,
            "amount": {
              "currency_code": "USD",
              "value": 47.50
            },
            "charge": {
              "id": "1c31a90-1c31-1c31-1c31-1c311c311c31",
              "metric_id": "metric_01H3YT8P7Q5R3S1T2U0V4W9X8",
              "charge_model": "STANDARD",
              "properties": {
                "amount": "0.50"
              },
              "min_amount": {
                "value": 0.01,
                "currency_code": "USD"
              }
            },
            "metric": {
              "name": "API Calls",
              "code": "api_calls",
              "aggregation_type": "COUNT"
            }
          },
          {
            "units": "1200.0",
            "events_count": 1200,
            "amount": {
              "currency_code": "USD",
              "value": 60.00
            },
            "charge": {
              "id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
              "metric_id": "metric_02H3YT8P7Q5R3S1T2U0V4W9Y9",
              "charge_model": "STANDARD",
              "properties": {
                "amount": "0.05"
              },
              "min_amount": {
                "value": 0.01,
                "currency_code": "USD"
              }
            },
            "metric": {
              "name": "Storage GB-Hours",
              "code": "storage_gb_hours",
              "aggregation_type": "SUM"
            }
          }
        ]
      }
    ],
    "meta": {
      "current_page": 1,
      "total_count": 12,
      "total_pages": 2
    }
  }
  ```
</CodeGroup>

A successful call returns a `200 OK` response with past usage summaries.