Usage-based metered billing API

Bills metered usage across graduated rate tiers above an included free allowance, adding an optional base platform fee and returning a per-tier breakdown and blended rate. Answers 'What is my usage bill across tiers?', 'How much do I owe after the included allowance?'.

Price$0.02per request

MethodPOST

Route/v1/commerce/metered-billing

StatusLive

MIME typeapplication/json

Rate limit120/minute

Cache0s public

commercesubscriptionmeteredusage-basedsaastieredoveragebilling

API URLhttps://x402.hexl.dev/v1/commerce/metered-billing

Integration docs

Example request

{
  "usage": 15000,
  "includedUnits": 1000,
  "basePlatformFee": 50,
  "tiers": [
    {
      "upTo": 10000,
      "price": 0.01
    },
    {
      "upTo": null,
      "price": 0.005
    }
  ]
}

Example response

{
  "usage": 15000,
  "includedUnits": 1000,
  "billableUnits": 14000,
  "basePlatformFee": 50,
  "tierBreakdown": [
    {
      "tierIndex": 0,
      "range": "1–10000",
      "units": 10000,
      "unitPrice": 0.01,
      "cost": 100
    },
    {
      "tierIndex": 1,
      "range": "10001–∞",
      "units": 4000,
      "unitPrice": 0.005,
      "cost": 20
    }
  ],
  "usageCost": 120,
  "total": 170,
  "blendedRatePerBillableUnit": 0.0086,
  "interpretation": "15000 used, 1000 included free; 14000 billable -> $120 usage + $50 base = $170."
}

Input schema

{
  "type": "object",
  "required": [
    "usage",
    "tiers"
  ],
  "properties": {
    "usage": {
      "type": "number",
      "examples": [
        15000
      ]
    },
    "includedUnits": {
      "type": "number",
      "examples": [
        1000
      ]
    },
    "tiers": {
      "type": "array",
      "examples": [
        [
          {
            "upTo": 10000,
            "price": 0.01
          },
          {
            "upTo": null,
            "price": 0.005
          }
        ]
      ]
    },
    "basePlatformFee": {
      "type": "number",
      "examples": [
        50
      ]
    }
  }
}

Output schema

{
  "type": "object",
  "additionalProperties": true
}