Billing meters

A billing meter defines what usage a merchant reports and how XPay combines that usage during an invoice cycle.

Create the meter before creating its pricing model. Use the XPay API reference for complete request and response schemas.

Meter operations#

Create a meter#

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

{
  "name": "Nexa Cloud API requests",
  "id": "api_requests",
  "active": true,
  "aggregation_type": "count",
  "aggregation_field": "request_count"
}

The response returns the created meter in data:

{
  "success": true,
  "responseStatus": "OK",
  "message": "Request processed successfully.",
  "data": {
    "id": "api_requests",
    "name": "Nexa Cloud API requests",
    "active": true,
    "aggregation_type": "count",
    "aggregation_field": "request_count"
  }
}

The response is shortened to the fields used in the usage-based billing flow.

Required fields:

• name: Merchant-facing meter name.
• aggregation_type: How XPay combines event values.
• aggregation_field: Payload field that carries the reported value.

The id is optional. XPay generates a meter ID when it is omitted.

Aggregation types#

Choose one meter for each value that must be aggregated independently. For example, Nexa Cloud uses:

• api_requests to count completed API requests.
• compute_minutes to add the duration of completed compute jobs.
• active_instances to use the highest number of simultaneously active service instances.
• stored_gigabytes to use the latest reported storage snapshot.

Combining these values in one meter would be ambiguous because each requires a different aggregation rule.

Optional taxes#

A meter can define taxes that apply to its calculated charge:

{
  "taxes": [
    {
      "key": "sales_tax",
      "value": 15,
      "type": "percentage",
      "inclusive": false
    }
  ]
}

Each tax key must be unique.

For a PKR 500.00 component with the 15% non-inclusive tax above, the tax is PKR 75.00 and the component total is PKR 575.00. XPay calculates multiple non-inclusive percentage taxes from the same pre-tax component amount.

Update a meter#

The update operation supports name, active, and filters. It doesn't change the meter's aggregation_type or aggregation_field.

Deactivate a meter#

Before deactivation, decide how to handle subscriptions and plans that depend on the meter.

{
  "subscription": {
    "next_action": "pause"
  },
  "plan": {
    "active": false
  }
}

The documented subscription actions are pause and cancel. Deactivating the related plans prevents them from being used for new usage-based subscriptions.

An active meter must be deactivated before it can be deleted.