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
- Version 1
- MCP tool
calc_billing_discounts - Try it in the browser
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).
| Input | Type | Description |
|---|---|---|
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.
| Result | Type | Description |
|---|---|---|
total | decimal (string) | The price after all discounts (never below 0). Unit: currency. |
total_discount | decimal (string) | subtotal − total. Unit: currency. |
steps | list of object | Each discount in order. |
Examples
100 with 20% off, then 5 off
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"]
}'
{
"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
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%"]
}'
{
"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
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"
}'
{
"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
- Stripe: Stackable coupons and promotion codes (order of percent_off and amount_off matters)
- Stripe API: Create a coupon (amount_off larger than the subtotal gives 0)
- Stripe: Percent off up to maximum (20% off up to 50 USD)
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.