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"
      }
    }
  ]
}

{
  "name": "NOT_AUTHORIZED",
  "message": "Authorization failed due to insufficient permissions.",
  "debug_id": "565f78f101498",
  "details": [
    {
      "issue": "PERMISSION_DENIED",
      "description": "You do not have permission to access or perform operations on this resource."
    }
  ]
}

{
  "name": "<string>",
  "debug_id": "<string>",
  "message": "<string>",
  "details": [
    {
      "field": "<string>",
      "value": "<string>",
      "location": "<string>",
      "issue": "<string>",
      "description": "<string>"
    }
  ]
}

{
  "name": "INTERNAL_SERVER_ERROR",
  "message": "An internal server error has occurred.",
  "debug_id": "90957fca61718"
}

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"
      }
    }
  ]
}

{
  "name": "NOT_AUTHORIZED",
  "message": "Authorization failed due to insufficient permissions.",
  "debug_id": "565f78f101498",
  "details": [
    {
      "issue": "PERMISSION_DENIED",
      "description": "You do not have permission to access or perform operations on this resource."
    }
  ]
}

{
  "name": "<string>",
  "debug_id": "<string>",
  "message": "<string>",
  "details": [
    {
      "field": "<string>",
      "value": "<string>",
      "location": "<string>",
      "issue": "<string>",
      "description": "<string>"
    }
  ]
}

{
  "name": "INTERNAL_SERVER_ERROR",
  "message": "An internal server error has occurred.",
  "debug_id": "90957fca61718"
}

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.

Pattern: ^[a-zA-Z0-9_-]*$

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.

Pattern:

^(?:[1-9]\d{3}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|02-(?:0[1-9]|1\d|2[0-8]))|(?:(?:\d{2}(?:0[48]|[2468][048]|[13579][26]))|(?:[02468][048]00|[13579][26]00))-02-29)$

Example:

"2022-08-01"

total_amount

object

required

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

Show child attributes

Example:

{ "value": 55, "currency_code": "USD" }

taxes_amount

object

required

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

Show child attributes

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.

Show child attributes

invoice_id

string

Unique invoice Id.

Example:

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

⌘I