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

# Record metric usage due to events

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

An event is an action your customer takes while using your product or service. For example, making an API call, uploading a file, or using storage space are all events. Each event uses some amount of a metric. This metric usage affects your billing. You need to record each event's metric usage with PayPal. PayPal uses this data to track usage and calculate charges. This process of recording usage is called metering.

An event connects the following entities:

* The metric that measures what you charge for (API calls, storage GB).
* The customer's subscription that determines their pricing plan and billing cycle.
* The actual metric usage that an event consumes. PayPal aggregates this data to calculate charges.

## Prerequisites

* Create and
  <a href="/limited-release/usage-based-billing/set-up-billing-process/create-metrics" target="_blank" rel="noopener noreferrer">set up all metrics</a>
  that define how events are aggregated for billing.
* <a href="/limited-release/usage-based-billing/set-up-billing-process/register-customers" target="_blank" rel="noopener noreferrer">Register the customers</a>
  to whom you want to track usage events.
* <a href="/limited-release/usage-based-billing/set-up-billing-process/create-subscriptions" target="_blank" rel="noopener noreferrer">Create subscriptions</a>
  that link customers to your pricing plans.

## 1. Send usage events to PayPal

You can send usage events using one of the following methods:

### Send multiple events

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 POST call to the `/v1/commerce/billing/events` endpoint. Include the following parameters:

| <span style={{textAlign: 'left', display: 'block'}}>Parameter</span>                                                                                                                                                        | <span style={{textAlign: 'left', display: 'block'}}>Action</span>                                                                                                                                                                                                                                                                        |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `transaction_id`<br /><span style={{color: 'red', fontSize: 'smaller'}}>Required</span>, <span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>                                                                | Set a unique identifier for this event. Ensure values are unique across all events.                                                                                                                                                                                                                                                      |
| `metric_code`<br /><span style={{color: 'red', fontSize: 'smaller'}}>Required</span>, <span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>                                                                   | Set to the `code` returned when you <a href="/limited-release/usage-based-billing/set-up-billing-process/create-metrics" target="_blank" rel="noopener noreferrer">created the metric</a>.                                                                                                                                               |
| `external_subscription_id`<br /><span style={{color: 'red', fontSize: 'smaller'}}>Required</span>, <span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>                                                      | Set to the `external_id` returned when you <a href="/limited-release/usage-based-billing/set-up-billing-process/create-subscriptions" target="_blank" rel="noopener noreferrer">created the subscription</a>.                                                                                                                            |
| `timestamp`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>                                                                                                                                        | Set the ISO 8601 timestamp when the event occurred. If not provided, PayPal uses the current time.                                                                                                                                                                                                                                       |
| `properties`<br /><span style={{color: 'red', fontSize: 'smaller'}}>Required for `SUM`, `MAX`, `COUNT_DISTINCT`, and `LATEST` aggregation types</span>, <span style={{color: '#95a5a6', fontSize: 'smaller'}}>object</span> | Provide key-value pairs for event properties and usage amounts. The property key (for example, `gb` or `minutes`) must match the `aggregation_field` from your <a href="/limited-release/usage-based-billing/set-up-billing-process/create-metrics#4-create-metrics" target="_blank" rel="noopener noreferrer">metric configuration</a>. |

For information on all parameters, see <a href="/reference/api/rest/events/create-a-new-usage-event" target="_blank" rel="noopener noreferrer">API reference</a>.

<Warning>
  Include your billing tier ID in the request header to enable higher rate limits for high-volume event processing.
</Warning>

<CodeGroup>
  ```shell lines title="Sample request" theme={null}
  curl -X POST 'https://api-m.sandbox.paypal.com/v1/commerce/billing/events' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>' \
  -H 'X-Billing-Tier-Id: <BILLING-TIER-ID>' \
  -d '{
    "transaction_id": "event_1753818829",
    "external_subscription_id": "d2d628e8-e7fb-412f-b09c-7f70ee58b50a",
    "metric_code": "91624203-791a-4639-8c86-4693948b3a41",
    "timestamp": "2025-07-29T12:53:49.076-07:00",
    "properties": {
      "gb": 10
    }
  }'
  ```

  ```json lines title="Sample response" theme={null}
  {
      "transaction_id": "event_1753818829",
      "metric_code": "91624203-791a-4639-8c86-4693948b3a41",
      "external_subscription_id": "d2d628e8-e7fb-412f-b09c-7f70ee58b50a",
      "timestamp": "2025-07-29T12:53:49.076-07:00",
      "properties": {
          "gb": 10
      },
      "id": "d80447f2-0f34-4612-86ae-152160dc66c5",
      "created_at": "2025-07-29T12:53:49-07:00"
  }
  ```
</CodeGroup>

A successful call returns a `201 Created` response with the event ID.

### Send a batch of events

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 POST call to the `/v1/commerce/billing/events/batch` endpoint. You can send up to 100 events in a single batch request. Include the following parameters:

| <span style={{textAlign: 'left', display: 'block'}}>Parameter</span>                                                                                                                                                               | <span style={{textAlign: 'left', display: 'block'}}>Action</span>                                                                                                                                                                                                                                                                        |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `events`<br /><span style={{color: 'red', fontSize: 'smaller'}}>Required</span>, <span style={{color: '#95a5a6', fontSize: 'smaller'}}>array</span>                                                                                | Provide an array of event objects (up to 100 events per batch).                                                                                                                                                                                                                                                                          |
| `events.transaction_id`<br /><span style={{color: 'red', fontSize: 'smaller'}}>Required</span>, <span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>                                                                | Set a unique identifier for each event. Ensure values are unique across all events.                                                                                                                                                                                                                                                      |
| `events.metric_code`<br /><span style={{color: 'red', fontSize: 'smaller'}}>Required</span>, <span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>                                                                   | Set to the `code` returned when you <a href="/limited-release/usage-based-billing/set-up-billing-process/create-metrics" target="_blank" rel="noopener noreferrer">created the metric</a>.                                                                                                                                               |
| `events.external_subscription_id`<br /><span style={{color: 'red', fontSize: 'smaller'}}>Required</span>, <span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>                                                      | Set to the `external_id` returned when you <a href="/limited-release/usage-based-billing/set-up-billing-process/create-subscriptions" target="_blank" rel="noopener noreferrer">created the subscription</a>.                                                                                                                            |
| `events.timestamp`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>                                                                                                                                        | Set the ISO 8601 timestamp when the event occurred. If not provided, PayPal uses the current time.                                                                                                                                                                                                                                       |
| `events.properties`<br /><span style={{color: 'red', fontSize: 'smaller'}}>Required for `SUM`, `MAX`, `COUNT_DISTINCT`, and `LATEST` aggregation types</span>, <span style={{color: '#95a5a6', fontSize: 'smaller'}}>object</span> | Provide key-value pairs for event properties and usage amounts. The property key (for example, `gb` or `minutes`) must match the `aggregation_field` from your <a href="/limited-release/usage-based-billing/set-up-billing-process/create-metrics#4-create-metrics" target="_blank" rel="noopener noreferrer">metric configuration</a>. |

For information on all parameters, see <a href="/reference/api/rest/events/create-multiple-usage-events-in-batch" target="_blank" rel="noopener noreferrer">API reference</a>.

<CodeGroup>
  ```shell lines expandable title="Sample request" theme={null}
  curl -X POST 'https://api-m.sandbox.paypal.com/v1/commerce/billing/events/batch' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>' \
  -d '{
    "events": [
      {
        "transaction_id": "event_t1_1753838783",
        "external_subscription_id": "91624203-791a-4639-8c86-4693948b3a41",
        "metric_code": "Billable_Metrics_1753827008",
        "timestamp": "2023-01-01T00:00:00Z",
        "properties": {
          "gb": 10
        }
      },
      {
        "transaction_id": "event_t2_1753838783",
        "external_subscription_id": "91624203-791a-4639-8c86-4693948b3a41",
        "metric_code": "Billable_Metrics_1753827008",
        "timestamp": "2023-01-01T00:00:00Z",
        "properties": {
          "gb": 10
        }
      }
    ]
  }'
  ```

  ```json lines title="Sample response" theme={null}
  {
      "status": "ACCEPTED",
      "results": {
          "success_count": 2,
          "error_count": 0
      }
  }
  ```
</CodeGroup>

A successful call returns a `201 Created` response with the status confirmation.

After you record events and meter usage, PayPal converts this metered data into charges for your customers and bills them. See <a href="/limited-release/usage-based-billing/meter-bill/understand-billing" target="_blank" rel="noopener noreferrer">Understand billing</a>.

## 2. Optional: Audit usage events

You can retrieve and audit the usage events recorded with PayPal to:

* Ensure billing accuracy.
* Resolve customer disputes.
* Validate that all events were saved correctly.
* Ensure that the events recorded match your own tracking systems.

For information on how to do this, see <a href="/limited-release/usage-based-billing/manage-entities/audit-usage-events" target="_blank" rel="noopener noreferrer">Audit usage events</a>.