Usage aggregation and invoice generation

XPay converts accepted meter events into invoice amounts by applying each meter's aggregation rule and each pricing model attached to the subscription's plan.

Billing flow#

1. The merchant sends meter events for an eligible subscription.
2. XPay applies each event to the ongoing invoice cycle.
3. XPay aggregates usage separately for each meter.
4. XPay evaluates every pricing model attached to the plan.
5. XPay creates the invoice and records the calculation in pricing_model_breakdown.
6. XPay attempts payment with the subscription's payment token.
7. XPay sends subscription and invoice payment events.

XPay uses the aggregation rule defined by each Billing meters. It evaluates every attached pricing model separately, then records each result in the invoice. See Usage-based pricing models for how component charges and multiple models affect the total.

Invoice breakdown#

The generated invoice's pricing_model_breakdown contains the usage and calculated amounts for each pricing model.

Each pricing model entry can include:

For three Nexa Cloud API-request events priced at PKR 5.00 per request with a 15% non-inclusive tax, a shortened breakdown can look like:

{
  "pricing_model_breakdown": [
    {
      "pricing_model_id": "api-request-pricing",
      "pricing_model_name": "Nexa Cloud API request pricing",
      "charge_type": "standard",
      "base_amount": 0,
      "usage_amount": 17.25,
      "total_amount": 17.25,
      "components": [
        {
          "meter_id": "api_requests",
          "meter_name": "Nexa Cloud API requests",
          "aggregation_type": "count",
          "pricing_type": "standard",
          "usage": 3,
          "amount_without_taxes": 15,
          "amount": 17.25,
          "standard_or_percentage": {
            "amount": 5
          },
          "taxes": [
            {
              "key": "sales_tax",
              "value": 15,
              "type": "percentage",
              "inclusive": false
            }
          ]
        }
      ],
      "meters_used": [
        "api_requests"
      ]
    }
  ]
}

Payment outcome#

• A successful payment sets the invoice to paid and keeps or returns the subscription to paid.
• A failed payment changes the subscription to inactive and triggers the configured Failed payments and retries.
• Manually paying an invoice through Invoices and recurring payments returns an eligible subscription to paid.

Store the invoice and subscription states separately, even when one payment outcome updates both.