Graduated (marginal) pricing API

Prices each successive band of quantity at its own tier rate like tax brackets, returning a per-tier breakdown and blended effective unit price. Answers 'What does graduated/marginal tier pricing cost for 120 units?', 'How is the bill split across bands?'.

Price$0.02per request

MethodPOST

Route/v1/commerce/graduated-pricing

StatusLive

MIME typeapplication/json

Rate limit120/minute

Cache0s public

commercepricinggraduatedmarginaltieredbracketsusagebilling

API URLhttps://x402.hexl.dev/v1/commerce/graduated-pricing

Integration docs

Example request

{
  "quantity": 120,
  "tiers": [
    {
      "upTo": 50,
      "price": 10
    },
    {
      "upTo": 100,
      "price": 8
    },
    {
      "upTo": null,
      "price": 6
    }
  ]
}

Example response

{
  "model": "graduated (marginal) — each band billed at its own rate",
  "quantity": 120,
  "breakdown": [
    {
      "tierIndex": 0,
      "range": "1–50",
      "units": 50,
      "unitPrice": 10,
      "flatFee": 0,
      "cost": 500
    },
    {
      "tierIndex": 1,
      "range": "51–100",
      "units": 50,
      "unitPrice": 8,
      "flatFee": 0,
      "cost": 400
    },
    {
      "tierIndex": 2,
      "range": "101–∞",
      "units": 20,
      "unitPrice": 6,
      "flatFee": 0,
      "cost": 120
    }
  ],
  "flatFeesTotal": 0,
  "total": 1020,
  "effectiveUnitPrice": 8.5,
  "interpretation": "Bracketed across 3 tier(s); blended effective $8.5/unit."
}

Input schema

{
  "type": "object",
  "required": [
    "quantity",
    "tiers"
  ],
  "properties": {
    "quantity": {
      "type": "number",
      "examples": [
        120
      ]
    },
    "tiers": {
      "type": "array",
      "examples": [
        [
          {
            "upTo": 50,
            "price": 10
          },
          {
            "upTo": 100,
            "price": 8
          },
          {
            "upTo": null,
            "price": 6
          }
        ]
      ]
    }
  }
}

Output schema

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