Meter events

A meter event reports usage for one subscription and one billing meter.

Submit events from the merchant backend after the usage-based subscription has been created.

Create a meter event#

POST {{base_url}}/public/v1/meter/{meter_id}/event

{
  "operation": "ADD",
  "event_id": "merchant-event-1001",
  "timestamp": "{{current_or_future_iso_8601_timestamp}}",
  "payload": {
    "subscription_id": "{{subscription_id}}",
    "aggregation_field": "request_count",
    "value": 1
  }
}

The response returns the accepted event in data, including the meter ID from the request path:

{
  "success": true,
  "responseStatus": "OK",
  "message": "Request processed successfully.",
  "data": {
    "operation": "ADD",
    "event_id": "merchant-event-1001",
    "meter_id": "api_requests",
    "timestamp": "2026-08-01T00:00:00.000Z",
    "payload": {
      "subscription_id": "xpay_subs_{{subscription_id}}",
      "aggregation_field": "request_count",
      "value": 1
    }
  }
}

Request fields#

Event eligibility#

XPay accepts a meter event only when:

• The meter exists and is active.
• The subscription exists and is eligible to receive usage.
• The subscription isn't inactive, paused, or cancelled.
• The subscription's plan is active and usage-based.
• A pricing model on the plan contains the meter.
• aggregation_field matches the meter.
• The timestamp isn't earlier than the current time.

ADD#

Use ADD to report usage. For count, each event adds one to the count. For value-based meters such as sum, the event adds payload.value.

fixed-retainer meters don't accept events because their billed quantity is defined by the meter and pricing model.

REMOVE#

REMOVE decreases the usage total for the ongoing invoice cycle.

It is available only when:

• The meter aggregation type is sum or count.
• The associated pricing model component uses standard or percentage pricing.
• The result doesn't reduce incurred usage below zero.

For count, one REMOVE event subtracts one count. For sum, XPay subtracts payload.value.

Retrieve meter events#

GET {{base_url}}/public/v1/meter/{meter_id}/event

Use this operation to retrieve available stored meter-event records. Don't use it as proof that an uncertain meter-event submission was accepted. Use the generated invoice's pricing_model_breakdown to reconcile aggregate billed usage and amounts.