Usage-based pricing models

A pricing model converts a meter's aggregated usage into an invoice amount. Create all referenced billing meters before creating the pricing model.

Pricing model operations#

Use the XPay API reference for the complete schema.

XPay monetary amounts use major currency units and support up to two decimal places. For example, 5 with PKR represents PKR 5.00, and 5.50 represents PKR 5.50. Percentage values can include decimals, such as 2.5 for 2.5%.

Common fields#

A non-composite pricing model contains exactly one component, and its pricing_type matches the top-level charge_type.

All creation examples on this page use POST {{base_url}}/public/v1/pricing/model.

Choose a pricing type#

Standard pricing#

Standard pricing multiplies aggregated usage by a unit amount.

{
  "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
      }
    }
  ]
}

The response returns the created pricing model in data:

{
  "success": true,
  "responseStatus": "OK",
  "message": "Request processed successfully.",
  "data": {
    "id": "api-request-pricing",
    "name": "Nexa Cloud API request pricing",
    "type": "one-time",
    "charge_type": "standard",
    "currency": "PKR",
    "components": [
      {
        "meter_id": "api_requests",
        "pricing_type": "standard",
        "pricing_schema": {
          "amount": 5
        }
      }
    ]
  }
}

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

For aggregated usage of 100, the usage charge is 100 × 5 = PKR 500.

Tiered pricing#

Tiered pricing splits total usage across tiers. XPay prices the units in each tier at that tier's rate, then adds the tier results. This is sometimes described as graduated pricing.

{
  "name": "Nexa Cloud tiered request pricing",
  "type": "one-time",
  "charge_type": "tiered",
  "currency": "PKR",
  "components": [
    {
      "meter_id": "{{meter_id}}",
      "pricing_type": "tiered",
      "pricing_schema": [
        {
          "lowerLimit": 1,
          "upperLimit": 100,
          "pricePerUnit": 10
        },
        {
          "lowerLimit": 101,
          "upperLimit": "Infinity",
          "pricePerUnit": 8
        }
      ]
    }
  ]
}

Tier bounds are inclusive. The first tier starts at 1, tiers have no gaps, and the final tier uses "Infinity". When a tier includes flatFee, XPay applies it when usage first enters that tier.

For usage of 150, the first 100 units cost PKR 10.00 each and the remaining 50 units cost PKR 8.00 each:

(100 × 10) + (50 × 8) = PKR 1,400.00

Volume pricing#

Volume pricing selects one tier from total usage and applies the selected tier's unit price to every unit. It does not price each tier separately.

{
  "name": "Nexa Cloud volume request pricing",
  "type": "one-time",
  "charge_type": "volume",
  "currency": "PKR",
  "components": [
    {
      "meter_id": "{{meter_id}}",
      "pricing_type": "volume",
      "pricing_schema": [
        {
          "lowerLimit": 1,
          "upperLimit": 100,
          "pricePerUnit": 10
        },
        {
          "lowerLimit": 101,
          "upperLimit": "Infinity",
          "pricePerUnit": 8
        }
      ]
    }
  ]
}

For usage of 150, the second tier applies to all 150 units:

150 × 8 = PKR 1,200.00

Because a volume tier can apply a lower unit amount to every unit, crossing a tier boundary can reduce the total charge. Review the values immediately below and above each boundary before publishing a volume model.

Compare tiered and volume pricing#

The two examples above use the same tiers so the difference is visible:

Use tiered pricing when each range should retain its own rate. Use volume pricing when the customer's total usage should determine one rate for the entire quantity.

Add flat fees to tiers#

Each tier can also include flatFee:

• With tiered pricing, XPay applies a tier's flat fee when usage first enters that tier. If the first tier has a PKR 100.00 flat fee and the second has a PKR 50.00 flat fee, 150 units cost (100 × 10) + 100 + (50 × 8) + 50 = PKR 1,550.00.
• With volume pricing, XPay applies only the selected tier's flat fee. If the second tier has a PKR 50.00 flat fee, 150 units cost (150 × 8) + 50 = PKR 1,250.00.

Omit flatFee when a tier should contain only a per-unit charge.

Percentage pricing#

Percentage pricing applies a percentage to the meter's aggregated value and then adds an optional flat fee.

{
  "name": "Nexa Cloud transaction-value pricing",
  "type": "one-time",
  "charge_type": "percentage",
  "currency": "PKR",
  "components": [
    {
      "meter_id": "{{meter_id}}",
      "pricing_type": "percentage",
      "pricing_schema": {
        "percentage": 2.5,
        "flatFee": 100
      }
    }
  ]
}

For an aggregated value of 200,000, the result is (200,000 × 2.5%) + 100 = PKR 5,100.

Fixed-retainer pricing#

Fixed-retainer pricing charges a configured amount without meter events.

{
  "name": "Nexa Cloud platform retainer",
  "type": "recurring",
  "charge_type": "fixed-retainer",
  "currency": "PKR",
  "components": [
    {
      "meter_id": "{{fixed_retainer_meter_id}}",
      "pricing_type": "fixed-retainer",
      "pricing_schema": {
        "amount": 10000
      }
    }
  ]
}

The referenced meter must use aggregation_type: "fixed-retainer".

For a PKR 10,000.00 retainer, XPay uses a fixed quantity of 1, so the charge is 1 × 10,000 = PKR 10,000.00. The merchant doesn't send meter events for this component.

Composite pricing#

A composite pricing model contains exactly two components, each referencing a different meter and pricing type.

• combination_operator: "AND" adds both component charges.
• combination_operator: "OR" selects one component charge.
• With OR, or_strategy: "higher" selects the larger charge and "lower" selects the smaller charge.

{
  "name": "Nexa Cloud API or platform minimum",
  "type": "one-time",
  "charge_type": "composite",
  "currency": "PKR",
  "combination_operator": "OR",
  "or_strategy": "higher",
  "components": [
    {
      "meter_id": "{{request_meter_id}}",
      "pricing_type": "standard",
      "pricing_schema": {
        "amount": 5
      }
    },
    {
      "meter_id": "{{retainer_meter_id}}",
      "pricing_type": "fixed-retainer",
      "pricing_schema": {
        "amount": 10000
      }
    }
  ]
}

Suppose Nexa Cloud reports 1,500 API requests:

• The standard component is 1,500 × 5 = PKR 7,500.00.
• The fixed-retainer component is PKR 10,000.00.
• With OR and higher, XPay selects PKR 10,000.00.
• With OR and lower, XPay selects PKR 7,500.00.

To charge both components, use combination_operator: "AND" and omit or_strategy. For the same 1,500 requests, AND produces 7,500 + 10,000 = PKR 17,500.00.

Calculation rules#

• XPay rounds calculated amounts to two decimal places.
• baseAmount is added once to the pricing model total after XPay calculates the usage components.
• recurring pricing models carry their billed component values into subsequent invoice cycles.
• one-time pricing models price usage received for the applicable invoice cycle.
• recurring isn't available with top-level tiered or volume pricing, or with tiered or volume components in a recurring composite model.

See Usage aggregation and invoice generation for the pricing_model_breakdown fields used to reconcile billed usage and amounts.

Delete a pricing model#

Before deleting a pricing model, choose how XPay handles dependent subscriptions:

{
  "subscription": {
    "next_action": "pause"
  }
}

The documented subscription actions are pause and cancel. Deleting a pricing model also makes related plans unavailable to new usage-based subscriptions. Retrieve affected subscriptions and plans after the request and update the merchant's customer access records.