curatedapi
Browse the docs

Guides

Finance

Excel functions

Late payments

E-invoices

Accounting

Number checks

VAT and GST

Billing and pricing

Money and currencies

Dates and time

Math

Unit conversion

Everyday

Health

Stacked discount API

Final price after several percentage and fixed-amount discounts, applied in order like Stripe's stacked coupons, with an optional cap.

POST https://api.curatedapi.com/v1/calc/billing/discounts

Applies a list of discounts to a price, one after another. A percentage discount takes that percentage of the price left after the earlier discounts, so order matters: 20% then 5 off is not the same as 5 off then 20%. This is how Stripe applies several coupons to a subscription. With additive stacking, every percentage is taken from the original price instead, so 20% and 10% make 30% off. Each discount is rounded to the cent when it is applied, the price never goes below 0, and max_total_discount caps the combined discount.

Formula

for each discount in order: off = round(p% × price left) or min(amount, price left); price left −= off; the combined discount is at most max_total_discount
  • A percentage discount is rounded to the cent when it is applied, the way it appears as a discount line. A subtotal, fixed amount or cap with more decimals is rounded first, with an AMOUNTS_ROUNDED warning, so the steps, total and total_discount always add up to the subtotal.
  • A discount larger than the price left takes it to 0 and the rest is not used, as with Stripe coupons (an amount_off of 200 on a 100 invoice gives 0, not a credit).
  • Taxes are not included: Stripe applies discounts before tax, so compute tax on the total.
  • Amounts are rounded to the cent (2 decimals) half up by default, the usual commercial rule and the one Stripe Tax uses. Set options.decimals for currencies with other minor units (0 for JPY, 3 for KWD) and options.rounding for another rule.

Inputs

Send numbers as strings to keep every digit. options sets precision and rounding (see numbers and rounding).

InputTypeDescription
subtotal required decimal (string) The price before discounts. Allowed: >= 0 and <= 1000000000000000. Unit: currency.
discounts required list of string The discounts in the order they apply: a percentage such as "20%" or an amount off such as "5" (in the subtotal's currency). 1 to 20 items.
stacking sequential | additive
default sequential
How percentage discounts combine. Options: sequential: each discount applies to the price left after the earlier ones (Stripe's stacked coupons); additive: each percentage is taken from the original subtotal
max_total_discount decimal (string) Optional cap on the combined discount, like Stripe's "percent off up to maximum" coupon. Allowed: >= 0 and <= 1000000000000000. Unit: currency.
options.rounding half_even | half_up | half_down | up | down | ceiling | floor Rounding mode applied once to each result. Default half_up.
options.decimals integer Round results to this many digits after the decimal point.

Result

Under result in the answer, next to exactness, precision, inputs, formula, references and warnings.

ResultTypeDescription
totaldecimal (string)The price after all discounts (never below 0). Unit: currency.
total_discountdecimal (string)subtotal − total. Unit: currency.
stepslist of objectEach discount in order.

Examples

100 with 20% off, then 5 off

Requestcurl
curl https://api.curatedapi.com/v1/calc/billing/discounts \
  -H "Authorization: Bearer $CURATEDAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subtotal": "100",
    "discounts": ["20%", "5"]
  }'
200 OKResponse
{
  "calculator": "billing/discounts@1",
  "result": {
    "total": "75.00",
    "total_discount": "25.00",
    "steps": [
      {
        "step": 1,
        "discount": "20%",
        "amount_off": "20.00",
        "price_after": "80.00"
      },
      {
        "step": 2,
        "discount": "5",
        "amount_off": "5.00",
        "price_after": "75.00"
      }
    ]
  },
  "exactness": {
    "total": "exact",
    "total_discount": "exact"
  },
  "precision": {
    "rounding": "half_up",
    "decimals": 2
  },
  "inputs": {
    "subtotal": "100",
    "discounts": [
      "20%",
      "5"
    ],
    "stacking": "sequential"
  },
  "formula": "for each discount in order: off = round(p% × price left) or min(amount, price left); price left −= off; the combined discount is at most max_total_discount",
  "references": [
    {
      "title": "Stripe: Stackable coupons and promotion codes (order of percent_off and amount_off matters)",
      "url": "https://docs.stripe.com/billing/subscriptions/coupons"
    },
    {
      "title": "Stripe API: Create a coupon (amount_off larger than the subtotal gives 0)",
      "url": "https://docs.stripe.com/api/coupons/create"
    },
    {
      "title": "Stripe: Percent off up to maximum (20% off up to 50 USD)",
      "url": "https://docs.stripe.com/billing/scripts/stripe-authored/discount-calculation"
    }
  ],
  "warnings": []
}

100 with 5 off, then 20% off

Requestcurl
curl https://api.curatedapi.com/v1/calc/billing/discounts \
  -H "Authorization: Bearer $CURATEDAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subtotal": "100",
    "discounts": ["5", "20%"]
  }'
200 OKResponse
{
  "calculator": "billing/discounts@1",
  "result": {
    "total": "76.00",
    "total_discount": "24.00",
    "steps": [
      {
        "step": 1,
        "discount": "5",
        "amount_off": "5.00",
        "price_after": "95.00"
      },
      {
        "step": 2,
        "discount": "20%",
        "amount_off": "19.00",
        "price_after": "76.00"
      }
    ]
  },
  "exactness": {
    "total": "exact",
    "total_discount": "exact"
  },
  "precision": {
    "rounding": "half_up",
    "decimals": 2
  },
  "inputs": {
    "subtotal": "100",
    "discounts": [
      "5",
      "20%"
    ],
    "stacking": "sequential"
  },
  "formula": "for each discount in order: off = round(p% × price left) or min(amount, price left); price left −= off; the combined discount is at most max_total_discount",
  "references": [
    {
      "title": "Stripe: Stackable coupons and promotion codes (order of percent_off and amount_off matters)",
      "url": "https://docs.stripe.com/billing/subscriptions/coupons"
    },
    {
      "title": "Stripe API: Create a coupon (amount_off larger than the subtotal gives 0)",
      "url": "https://docs.stripe.com/api/coupons/create"
    },
    {
      "title": "Stripe: Percent off up to maximum (20% off up to 50 USD)",
      "url": "https://docs.stripe.com/billing/scripts/stripe-authored/discount-calculation"
    }
  ],
  "warnings": []
}

Stripe example: 20% off up to 50 on 400

Requestcurl
curl https://api.curatedapi.com/v1/calc/billing/discounts \
  -H "Authorization: Bearer $CURATEDAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subtotal": "400",
    "discounts": ["20%"],
    "max_total_discount": "50"
  }'
200 OKResponse
{
  "calculator": "billing/discounts@1",
  "result": {
    "total": "350.00",
    "total_discount": "50.00",
    "steps": [
      {
        "step": 1,
        "discount": "20%",
        "amount_off": "50.00",
        "price_after": "350.00"
      }
    ]
  },
  "exactness": {
    "total": "exact",
    "total_discount": "exact"
  },
  "precision": {
    "rounding": "half_up",
    "decimals": 2
  },
  "inputs": {
    "subtotal": "400",
    "discounts": [
      "20%"
    ],
    "stacking": "sequential",
    "max_total_discount": "50"
  },
  "formula": "for each discount in order: off = round(p% × price left) or min(amount, price left); price left −= off; the combined discount is at most max_total_discount",
  "references": [
    {
      "title": "Stripe: Stackable coupons and promotion codes (order of percent_off and amount_off matters)",
      "url": "https://docs.stripe.com/billing/subscriptions/coupons"
    },
    {
      "title": "Stripe API: Create a coupon (amount_off larger than the subtotal gives 0)",
      "url": "https://docs.stripe.com/api/coupons/create"
    },
    {
      "title": "Stripe: Percent off up to maximum (20% off up to 50 USD)",
      "url": "https://docs.stripe.com/billing/scripts/stripe-authored/discount-calculation"
    }
  ],
  "warnings": [
    {
      "code": "DISCOUNT_CAPPED",
      "message": "The discounts are capped at 50.00 in total."
    }
  ]
}

References

Results follow each calculator's documented rules and the sources listed. They are not financial, tax or legal advice. Check that the rules fit your case before you rely on a result. See the terms.

Errors share one format; see errors. Billing, retries and batches work the same for every endpoint.