Usage-based billing quickstart

Create a metered Nexa Cloud subscription, report three API requests, and reconcile a PKR 15.00 usage charge.

What you'll create#

This quickstart creates:

• An api_requests meter that counts accepted events.
• Standard pricing of PKR 5.00 per request.
• A monthly usage-based plan.
• A draft subscription with collect_advance: false.
• Three meter events and an expected usage charge of PKR 15.00.

1. Prepare the usage-based billing inputs#

Before starting, Products that represents the billed service and obtain a reusable payment token through the XPay Element. Use Collect a payment token with XPay Element and Integrate XPay webhooks for the payment flow.

2. Create a billing meter#

Choose an aggregation type that matches the merchant's usage model.

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

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

Store the returned meter ID.

{
  "success": true,
  "data": {
    "id": "api_requests",
    "aggregation_type": "count",
    "aggregation_field": "request_count",
    "active": true
  }
}

The response is shortened. See Billing meters for the meter fields and supported aggregation types.

3. Create a pricing model#

Create a pricing model that references the meter. This example charges a fixed amount for each counted request:

POST {{base_url}}/public/v1/pricing/model

{
  "name": "Nexa Cloud API request pricing",
  "id": "api-request-pricing",
  "type": "one-time",
  "charge_type": "standard",
  "currency": "PKR",
  "components": [
    {
      "meter_id": "{{meter_id}}",
      "pricing_type": "standard",
      "pricing_schema": {
        "amount": 5
      }
    }
  ]
}

Store the returned pricing model ID.

{
  "success": true,
  "data": {
    "id": "api-request-pricing",
    "charge_type": "standard",
    "type": "one-time",
    "currency": "PKR"
  }
}

The response is shortened. See Usage-based pricing models for calculation rules and the full example used by these guides.

4. Create a usage-based plan#

Create or select the product that represents the billed service, then create the recurring plan using the following required fields:

POST {{base_url}}/public/v1/plan

{
  "name": "Nexa Cloud monthly usage",
  "interval": "month",
  "every": 1,
  "billing_cycle": "usage",
  "billing_cycle_anchor_config": {
    "day_of_month": 1
  },
  "product": [
    {
      "product_id": "{{product_id}}",
      "quantity": 1
    }
  ],
  "is_usage_based": true,
  "pricing_models": [
    "{{pricing_model_id}}"
  ]
}

Store the returned plan ID:

{
  "success": true,
  "data": {
    "plan_id": "xpay_plan_{{plan_id}}",
    "name": "Nexa Cloud monthly usage",
    "interval": "month",
    "every": 1,
    "is_usage_based": true,
    "pricing_models": [
      "api-request-pricing"
    ]
  }
}

The response is shortened. Use the XPay API reference for optional plan fields and the canonical response schema.

5. Use the payment token#

Set payment.token to the reusable token returned by the payment flow at token.id.

6. Create the subscription#

Create the subscription using the usage-based plan ID and the payment token received through the webhook:

POST {{base_url}}/public/v1/subscription

{
  "plan_id": "{{plan_id}}",
  "payment": {
    "token": "{{payment_token_from_webhook}}"
  },
  "start_date": "{{iso_8601_start_date}}",
  "timezone": "Asia/Karachi",
  "collect_advance": false
}

Usage-based subscriptions don't support advance collection.

Store the returned subscription ID before accepting usage events for the customer.

{
  "success": true,
  "data": {
    "subscription_id": "xpay_subs_{{subscription_id}}",
    "plan_id": "xpay_plan_{{plan_id}}",
    "state": "draft",
    "is_usage_based": true,
    "collect_advance": false,
    "scheduled_invoices": [
      {
        "invoice_id": "xpay_invoice_{{invoice_id}}",
        "date": "2026-08-01T00:00:00.000Z"
      }
    ]
  }
}

The response is shortened. See Create a usage-based subscription for the complete creation behavior.

7. Send a meter event#

Assign one stable event_id to each logical usage event. The meter-event endpoint doesn't deduplicate submissions, so follow Prevent duplicate meter events before retrying an uncertain request.

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

Send three ADD events with different stable event IDs. With count aggregation and PKR 5.00 standard pricing, the expected quantity is 3 and the usage charge is PKR 15.00.

XPay returns event_id, but the meter-event endpoint doesn't enforce uniqueness. Follow Prevent duplicate meter events to prevent repeated submissions for the same logical usage.

{
  "success": true,
  "data": {
    "operation": "ADD",
    "event_id": "merchant-event-1001",
    "meter_id": "api_requests",
    "payload": {
      "subscription_id": "xpay_subs_{{subscription_id}}",
      "aggregation_field": "request_count",
      "value": 1
    }
  }
}

The response is shortened. See Meter events for the event contract.

Use a current or future event timestamp. See Meter events for the complete eligibility rules.

8. Reconcile usage and invoices#

Store each request and response with its merchant-provided event_id. See Usage aggregation and invoice generation to reconcile aggregate billed usage and amounts from the generated invoice's pricing_model_breakdown.

Use Usage-based billing webhooks to process invoice payment success and failure.

Next steps#

• Review Meter events for the event payload, operations, and timestamp eligibility rules.
• Review Prevent duplicate meter events before retrying uncertain event requests.
• Review Usage aggregation and invoice generation to reconcile billed usage from invoice breakdowns.