> ## 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. # Get current usage for a customer > Retrieves the current billing period usage information for a specific customer ## OpenAPI ````yaml /api-reference/ubb_openapi_inline.json get /customers/{external_customer_id}/current_usage openapi: 3.0.1 info: title: Usage Based Billing API version: 1.0.0 description: An Orchestrator for Usage Based Billing and Payments servers: - url: https://api-m.sandbox.paypal.com/v1/commerce/billing security: - BearerAuth: - read - write tags: - name: Alerts description: API endpoints for managing subscription alerts - name: Events description: API endpoints for managing events - name: Metrics description: API endpoints for metrics and usage data - name: Merchant Activation description: API endpoint for merchant activation - name: Credit Notes description: API endpoints for credit notes management - name: Customers description: API endpoints for customer management - name: Invoices description: API endpoints for invoice management - name: Plans description: API endpoints for subscription plans - name: Subscriptions description: API endpoints for subscriptions - name: Wallets description: API endpoints for wallet management - name: Taxes description: API endpoints for tax management - name: Billing Entities description: API endpoints for billing entities - name: Features description: API endpoints for managing features and privileges - name: Entitlements description: API endpoints for managing plan and subscription entitlements paths: /customers/{external_customer_id}/current_usage: get: tags: - Customers summary: Get current usage for a customer description: >- Retrieves the current billing period usage information for a specific customer operationId: GetCustomersCurrentUsage parameters: - $ref: '#/components/parameters/external_customer_id' - in: query name: subscription_id schema: $ref: '#/components/schemas/SubscriptionExternalId' required: true description: Filter by subscription ID. responses: '200': description: Returns the current usage for the specified customer. content: application/json: schema: $ref: '#/components/schemas/CustomerUsage' example: 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 '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' components: parameters: external_customer_id: name: external_customer_id in: path required: true description: The unique external identifier of the customer schema: type: string example: 9c402857-a71e-4ea2-bcf9-57d3a41bc6ba schemas: SubscriptionExternalId: type: string description: >- The subscription external unique identifier supplied by client. Must contain only alphanumeric characters, underscores, and hyphens. pattern: ^[a-zA-Z0-9_-]*$ example: SUB_1752779018503 CustomerUsage: type: object required: - from_datetime - to_datetime - issuing_date - total_amount - taxes_amount - charges_usage properties: from_datetime: allOf: - $ref: '#/components/schemas/DateTimeWithZone' - description: >- Starting date of billing period, in the ISO 8601 datetime format in Universal Time (UTC). example: '2022-07-01T00:00:00Z' to_datetime: allOf: - $ref: '#/components/schemas/DateTimeWithZone' - description: >- Ending date of the billing period, in the ISO 8601 datetime format in Universal Time (UTC). example: '2022-07-31T23:59:59Z' issuing_date: allOf: - $ref: '#/components/schemas/Date' description: The date of creation of the invoice. example: '2022-08-01' invoice_id: type: string example: 1a901a90-1a90-1a90-1a90-1a901a901a90 description: Unique invoice Id. total_amount: allOf: - $ref: '#/components/schemas/Amount' description: >- The total amount for the current usage period, including all charges and taxes. example: value: 55 currency_code: USD taxes_amount: allOf: - $ref: '#/components/schemas/Amount' description: The total amount of taxes applied to the current usage period. example: value: 5 currency_code: USD charges_usage: type: array description: >- Array of charges that comprise the current usage. It contains detailed information about individual charge items associated with the usage. items: $ref: '#/components/schemas/CustomerChargeUsage' DateTimeWithZone: type: string format: date-time description: Date and time in ISO 8601 format. example: '2023-10-01T12:00:00Z' Date: type: string format: date description: Date in ISO 8601 format (YYYY-MM-DD). example: '2023-10-01' 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)$ Amount: allOf: - $ref: '#/components/schemas/AmountNoCurrency' - type: object required: - currency_code properties: currency_code: $ref: '#/components/schemas/Currency' CustomerChargeUsage: type: object required: - units - events_count - amount - charge - metric properties: units: type: string pattern: ^[0-9]+.?[0-9]*$ example: '1.0' description: The number of units utilized for a specific charge item. events_count: type: integer example: 10 description: >- The total count of usage events that have been recorded for a particular charge during the specified time period. amount: allOf: - $ref: '#/components/schemas/Amount' charge: allOf: - $ref: '#/components/schemas/UsageBasedCharge' metric: allOf: - $ref: '#/components/schemas/CustomerUsageMetric' Error: type: object properties: name: type: string debug_id: type: string message: type: string details: type: array items: $ref: '#/components/schemas/ErrorDetail' AmountNoCurrency: type: object required: - value properties: value: type: number format: decimal description: >- The amount value in the corresponding currency unit (e.g., two decimals for USD, no decimals for JPY). example: 120.35 minimum: 0 nullable: false default: 0 Currency: type: string description: Currency code in ISO 4217 format. example: USD minLength: 3 maxLength: 3 pattern: ^[A-Z]{3}$ UsageBasedCharge: type: object required: - id - metric_id properties: id: type: string description: Unique identifier of the charge example: 1a901a90-1a90-1a90-1a90-1a901a901a90 metric_id: type: string description: Unique identifier of the metric charge_model: $ref: '#/components/schemas/ChargeModel' description: Defines the pricing model to calculate the charge properties: type: object description: Pricing thresholds that determine the charges taxes: type: array description: List of tax entities configured for the usage based charge. items: $ref: '#/components/schemas/TaxResponse' min_amount: allOf: - $ref: '#/components/schemas/Amount' CustomerUsageMetric: title: CustomerUsageMetric description: >- Represents a metric used for customer usage. It includes the name, code, and aggregation type of the metric. type: object required: - name - code - aggregation_type properties: name: type: string description: Name of the metric used for this charge. code: type: string description: Unique code identifying the metric used for this charge. aggregation_type: $ref: '#/components/schemas/MetricAggregationType' ErrorDetail: type: object properties: field: type: string value: type: string location: type: string issue: type: string description: type: string ChargeModel: type: string description: The pricing model applied to this charge enum: - STANDARD - GRADUATED - PACKAGE - PERCENTAGE - VOLUME x-enum-varnames: - STANDARD - GRADUATED - PACKAGE - PERCENTAGE - VOLUME x-enum-descriptions: - Standard pricing model where a fixed amount is charged per unit - >- Graduated pricing model where the price per unit decreases as the quantity increases - >- Package pricing model where a fixed price is charged for a set of units - >- Percentage pricing model where a percentage of a base amount is charged - >- Volume-based pricing model where the price varies based on the total volume consumed example: GRADUATED default: STANDARD TaxResponse: description: >- Represents a customizable tax rate that can be applied to invoices and fees type: object allOf: - $ref: '#/components/schemas/TaxBase' - type: object properties: code: $ref: '#/components/schemas/TaxCode' id: type: string format: uuid description: Unique identifier of the tax example: 1a901a90-1a90-1a90-1a90-1a901a901a90 created_at: allOf: - $ref: '#/components/schemas/DateTimeWithZone' - description: >- The effective start date of the subscription; can be past, current, or future. Date must be provided in ISO 8601 format example: '2025-06-01T00:00:00Z' MetricAggregationType: type: string nullable: true enum: - COUNT - SUM - MAX - COUNT_DISTINCT - LATEST x-enum-varnames: - COUNT - SUM - MAX - COUNT_DISTINCT - LATEST x-enum-descriptions: - Count the number of events - Sum the values of a numeric field - Find the maximum value of a numeric field - Count the number of distinct values - Use the latest value description: Aggregation type for the metric example: SUM TaxBase: description: Base schema for tax request/response objects type: object required: - name properties: name: type: string description: Name of the tax example: TVA rate: type: string pattern: >- ^(?!0+(?:\.0+)?$)(?:0?\.\d{1,2}|[1-9]\d?(?:\.\d{1,2})?|100(?:\.0{1,2})?)$ description: >- 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. example: '20.00' description: type: string description: Detailed description of the tax for internal reference example: French standard VAT TaxCode: type: string description: >- Unique code used to identify the tax. Must contain only alphanumeric characters, underscores, and hyphens. pattern: ^[a-zA-Z0-9_-]*$ example: standard_vat responses: Forbidden: description: Authorization failed due to insufficient permissions. content: application/json: schema: $ref: '#/components/schemas/Error' example: 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. NotFound: description: Resource Not Found. content: application/json: schema: $ref: '#/components/schemas/Error' InternalServerError: description: Internal Server Error - An unexpected error occurred content: application/json: schema: $ref: '#/components/schemas/Error' example: name: INTERNAL_SERVER_ERROR message: An internal server error has occurred. debug_id: 90957fca61718 securitySchemes: BearerAuth: type: oauth2 description: >- Use the /v1/oauth2/token endpoint to obtain an access token and pass it as a Bearer token in the Authorization header. flows: clientCredentials: tokenUrl: https://api-m.sandbox.paypal.com/v1/oauth2/token scopes: read: Read access write: Write access ````