Skip to main content
GET
/
customers
/
{external_customer_id}
/
current_usage
Get current usage for a customer
curl --request GET \
  --url https://api-m.sandbox.paypal.com/v1/commerce/billing/customers/{external_customer_id}/current_usage \
  --header 'Authorization: Bearer <token>'
{
  "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
  },
  "taxes_amount": {
    "currency_code": "USD",
    "value": 2.75
  },
  "charges_usage": [
    {
      "units": "150.0",
      "events_count": 3050,
      "amount": {
        "currency_code": "USD",
        "value": 75
      },
      "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
      },
      "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
      },
      "charge": {
        "id": "1a901b42-1b42-1b42-1b42-1a901b421b42",
        "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"
      }
    }
  ]
}

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_customer_id
string
required

The unique external identifier of the customer

Query Parameters

​
subscription_id
string
required

Filter by subscription ID. The subscription external unique identifier supplied by client. Must contain only alphanumeric characters, underscores, and hyphens.

Example:

"SUB_1752779018503"

Response

Returns the current usage for the specified customer.

​
from_datetime
string<date-time>
required

Starting date of billing period, in the ISO 8601 datetime format in Universal Time (UTC).

Example:

"2022-07-01T00:00:00Z"

​
to_datetime
string<date-time>
required

Ending date of the billing period, in the ISO 8601 datetime format in Universal Time (UTC).

Example:

"2022-07-31T23:59:59Z"

​
issuing_date
string<date>
required

The date of creation of the invoice.

Example:

"2022-08-01"

​
total_amount
object
required

The total amount for the current usage period, including all charges and taxes.

Example:
{ "value": 55, "currency_code": "USD" }
​
taxes_amount
object
required

The total amount of taxes applied to the current usage period.

Example:
{ "value": 5, "currency_code": "USD" }
​
charges_usage
object[]
required

Array of charges that comprise the current usage. It contains detailed information about individual charge items associated with the usage.

​
invoice_id
string

Unique invoice Id.

Example:

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