---
title: "Get past usage for a customer"
method: GET
path: "/customers/{external_customer_id}/past_usage"
tags: ["Customers"]
---

# Get past usage for a customer

`GET /customers/{external_customer_id}/past_usage`

## Request

- Base URL: `https://api-m.sandbox.paypal.com`
- URL: `https://api-m.sandbox.paypal.com/customers/{external_customer_id}/past_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/customers/:external_customer_id/past_usage/get.ts> (a function with typed inputs; its response is checked against the schema)

Retrieves historical usage information for a specific customer across previous billing periods

## Path parameters

- `external_customer_id` string, required

## Query parameters

- `page` integer
- `per_page` integer
- `subscription_id` string, required

## Response `200`

Returns the past usage for the specified customer.

- CustomerPastUsage
  - `usage_periods` CustomerUsage[], required
    - `from_datetime` string, date-time, required: Starting date of billing period, in the ISO 8601 datetime format in Universal Time (UTC).
    - `to_datetime` string, date-time, required: Ending date of the billing period, in the ISO 8601 datetime format in Universal Time (UTC).
    - `issuing_date` string, date, required: Date in ISO 8601 format (YYYY-MM-DD).
    - `invoice_id` string: Unique invoice Id.
    - `total_amount` Amount, required
      - `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.
    - `taxes_amount` Amount, required
      - `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.
    - `charges_usage` CustomerChargeUsage[], required: Array of charges that comprise the current usage. It contains detailed information about individual charge items associated with the usage.
      - `units` string, required: The number of units utilized for a specific charge item.
      - `events_count` integer, required: The total count of usage events that have been recorded for a particular charge during the specified time period.
      - `amount` Amount, required
        - `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.
      - `charge` UsageBasedCharge, required
        - `id` string, required: Unique identifier of the charge
        - `metric_id` string, required: Unique identifier of the metric
        - `charge_model` 'STANDARD' | 'GRADUATED' | 'PACKAGE' | 'PERCENTAGE' | 'VOLUME': The pricing model applied to this charge
        - `properties` object: Pricing thresholds that determine the charges
        - `taxes` TaxResponse[]: List of tax entities configured for the usage based charge.
          - `name` string, required: Name of the tax
          - `rate` string: The percentage rate of the tax applied to transactions. A decimal amount from 0.01 to 100.00 inclusive, always with exactly two decimal places, no leading zeros except 0.xx.
          - `description` string: Detailed description of the tax for internal reference
          - `code` string: Unique code used to identify the tax. Must contain only alphanumeric characters, underscores, and hyphens.
          - `id` string, uuid: Unique identifier of the tax
          - `created_at` string, date-time: The effective start date of the subscription; can be past, current, or future. Date must be provided in ISO 8601 format
        - `min_amount` 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.
      - `metric` CustomerUsageMetric, required: Represents a metric used for customer usage. It includes the name, code, and aggregation type of the metric.
        - `name` string, required: Name of the metric used for this charge.
        - `code` string, required: Unique code identifying the metric used for this charge.
        - `aggregation_type` 'COUNT' | 'SUM' | 'MAX' | 'COUNT_DISTINCT' | 'LATEST', nullable, required: Aggregation type for the metric
  - `meta` PaginationMetadata, required
    - `total_count` integer
    - `total_pages` integer
    - `current_page` integer

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