Apply coupon (pct/fixed/BOGO) API

Applies a percent (optionally capped), fixed-amount, or BOGO (buy X get Y at Z% off) coupon to a cart subtotal, enforcing minimum spend and a $0 floor. Answers 'What does a 15% coupon capped at $25 give me?', 'How much off with buy-one-get-one-free?'.

Price$0.02per request

MethodPOST

Route/v1/commerce/coupon-apply

StatusLive

MIME typeapplication/json

Rate limit120/minute

Cache0s public

commercecoupondiscountbogopromo-codevouchercartcheckout

API URLhttps://x402.hexl.dev/v1/commerce/coupon-apply

Integration docs

Example request

{
  "subtotal": 200,
  "type": "percent",
  "value": 15,
  "maxDiscount": 25
}

Example response

{
  "couponType": "percent",
  "eligible": true,
  "minSpend": 0,
  "subtotal": 200,
  "discount": 25,
  "total": 175,
  "effectiveDiscountPct": 12.5,
  "detail": {
    "capped": true,
    "percent": 15
  },
  "interpretation": "Coupon applied: $25 off (12.5%) -> pay $175."
}

Input schema

{
  "type": "object",
  "required": [
    "subtotal",
    "type",
    "value"
  ],
  "properties": {
    "subtotal": {
      "type": "number",
      "examples": [
        200
      ]
    },
    "type": {
      "type": "string",
      "enum": [
        "percent",
        "fixed",
        "bogo"
      ],
      "examples": [
        "percent"
      ]
    },
    "value": {
      "type": "number",
      "examples": [
        15
      ]
    },
    "maxDiscount": {
      "type": "number",
      "examples": [
        25
      ]
    }
  }
}

Output schema

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