Handling Discounts with TaxCloud

TaxCloud’s API provides native support for discounts at both the line-item and order level. You can apply discounts directly through the API, there’s no need to pre-calculate discounted prices in your integration code.

Migration Note: If you previously handled discounts by submitting pre-discounted prices or using negative line items, see Migrating from Manual Discount Handling at the end of this guide.

How Discounts Work

TaxCloud applies discounts before calculating tax, distributes order-level discounts proportionally across eligible items, and preserves original prices for audit and refund purposes.

Discount Types

TaxCloud supports two levels of discounts, each available as either a percentage or a fixed dollar amount.

Line-Item Discounts

A line-item discount applies to a specific item in the cart or order. Use this when a coupon or promotion targets a particular product.

Percentage discount: Reduces the item’s price by a percentage. Percentage values are expressed as decimals from 0 to 1 (e.g., 0.20 for 20%).

1
{
2
  "lineItems": [
3
    {
4
      "itemID": "SKU-1001",
5
      "price": 50.00,
6
      "quantity": 2,
7
      "TIC": "00000",
8
      "discount": {
9
        "type": "percentage",
10
        "value": 0.20
11
      }
12
    }
13
  ]
14
}

In this example, each unit’s price is reduced from $50.00 to $40.00 before tax is calculated.

Fixed amount discount: Reduces the item’s price by a specific dollar amount per unit.

1
{
2
  "lineItems": [
3
    {
4
      "itemID": "SKU-1001",
5
      "price": 50.00,
6
      "quantity": 2,
7
      "TIC": "00000",
8
      "discount": {
9
        "type": "amount",
10
        "value": 10.00
11
      }
12
    }
13
  ]
14
}

Here, each unit’s price is reduced from $50.00 to $40.00.

Multiple discounts on the same item: If the same item has multiple line-item discounts, they are applied sequentially. Each discount operates on the result of the previous one.

$
Item: $100.00
$
First discount: 10% → $100.00 × 0.90 = $90.00
$
Second discount: 20% → $90.00 × 0.80 = $72.00

Order-Level Discounts

An order-level discount applies to the entire order. TaxCloud distributes the discount proportionally across all eligible line items based on their share of the order subtotal. Shipping and excise tax items are excluded from both the subtotal calculation and the discount application.

Percentage discount on the order:

1
{
2
  "lineItems": [
3
    {
4
      "itemID": "SKU-1001",
5
      "price": 80.00,
6
      "quantity": 1,
7
      "TIC": "00000"
8
    },
9
    {
10
      "itemID": "SKU-1002",
11
      "price": 20.00,
12
      "quantity": 1,
13
      "TIC": "00000"
14
    },
15
    {
16
      "itemID": "SHIPPING",
17
      "price": 10.00,
18
      "quantity": 1,
19
      "TIC": "11010"
20
    }
21
  ],
22
  "discount": {
23
    "type": "percentage",
24
    "value": 0.10
25
  }
26
}

The 10% discount applies to the two product items ($80 and $20), but not to the shipping item (TIC 11010). The $80 item is reduced to $72.00, and the $20 item is reduced to $18.00. Shipping remains at $10.00.

Fixed amount discount on the order:

1
{
2
    "lineItems": [
3
    {
4
      "itemID": "SKU-1001",
5
      "price": 80.00,
6
      "quantity": 1,
7
      "TIC": "00000"
8
    },
9
10
     {
11
      "itemID": "SKU-1002",
12
      "price": 20.00,
13
      "quantity": 1,
14
      "TIC": "00000"
15
    }
16
  ],
17
18
  "discount": {
19
    "type": "amount",
20
    "value": 15.00
21
  }
22
}

A $15 order-level discount is distributed proportionally across eligible items. If the eligible subtotal is $100, an item priced at $80 receives $12.00 of the discount (80% of $15), and an item priced at $20 receives $3.00 (20% of $15).

Discount exceeding subtotal: If an order-level amount discount exceeds the eligible subtotal, it is capped at 100%. All eligible items are reduced to $0.00; no error is returned.

Combining Line-Item and Order-Level Discounts

You can apply both line-item and order-level discounts on the same request. When both are present:

1. Line-item discounts are applied first, reducing each item’s price individually.
2. The order-level discount is then calculated based on the post-line-item-discount subtotal of eligible items.
3. The order-level discount is applied to all eligible items, including those that already received line-item discounts.

1
{
2
  "lineItems": [
3
    {
4
      "itemID": "SKU-1001",
5
      "price": 100.00,
6
      "quantity": 1,
7
      "TIC": "00000",
8
      "discount": {
9
        "type": "percentage",
10
        "value": 0.10
11
      }
12
    },
13
    {
14
      "itemID": "SKU-1002",
15
      "price": 50.00,
16
      "quantity": 1,
17
      "TIC": "00000"
18
    }
19
  ],
20
  "discount": {
21
    "type": "amount",
22
    "value": 10.00
23
  }
24
}

How the Discounts Were Applied

How the order discount was split: Since SKU-1001 ($90) and SKU-1002 ($50) together make up $140, each item absorbs a proportional share of the $10.00 order discount — 64.3% and 35.7% respectively.

Exclusion Rules

Not all items are eligible for every type of discount. TaxCloud enforces the following rules automatically to ensure tax compliance.

Shipping and Handling (Order-Level Exclusion)

Items with the following TICs are excluded from order-level discounts but can receive line-item discounts (on the assumption that a line-item discount on shipping is intentional). These items are also excluded from the subtotal calculation used to distribute order-level amount discounts.

If you need to discount shipping, apply a line-item discount directly to the shipping line item.

Excise Tax Items (All Discounts Excluded)

Items with the following TICs are excluded from both line-item and order-level discounts. If you include a discount on an excise tax line item, TaxCloud will ignore the discount and calculate tax on the full price.

Colorado Retail Delivery Fee: Note that it is non-refundable.

Understanding the Response

When your request is processed, each line item in the response includes both originalPrice and price fields. These are always present, regardless of whether a discount was applied.

1
{
2
  "items": [
3
    {
4
      "itemID": "SKU-1001",
5
      "originalPrice": 100.00,
6
      "price": 83.57,
7
      "quantity": 1,
8
      "tax": 5.85,
9
      "TIC": "00000"
10
    }
11
  ]
12
}

• originalPrice — The price submitted in your request, before any discounts. If no discount applies, this will match price.
• price — The final price after any discounts have been applied. This is the amount tax is calculated on.

The original items in your request are never modified. The response returns a new representation with these fields always populated.

Discounts and Refunds

When processing a refund on a discounted order, TaxCloud uses the discounted price (not the original price) to calculate the refund amount. You do not need to re-apply discount logic when submitting refund requests, this is handled automatically.

Key refund behaviors with discounts:

• Refunds reflect discounted prices. If a 10% discount reduced a $100 item to $90, refunding 1 unit returns $90.
• Order-level discounts are distributed proportionally. Each unit receives its proportional share of the discount, and refunds return that proportional amount.
• Multiple partial refunds work correctly. Each partial refund uses the discounted unit price, and the sum of all partial refunds matches the total discounted order amount.
• Stacked discounts use the final price. If both line-item and order-level discounts were applied (e.g., $100 → $90 → $72), the refund uses the final $72.
• Shipping can be refunded at full price. Shipping items are excluded from discounts but can still be refunded at their original price.
• 100% discounts refund at $0. If an item was fully discounted, the refund amount is $0.

For details on processing returns, see Processing Returns.

Validation and Error Handling

TaxCloud validates discount inputs and returns clear error messages when issues are detected.

Validation Errors

The API will return an error in the following cases:

Capping Behavior

In some cases, TaxCloud adjusts the discount rather than returning an error:

• Order-level amount exceeds subtotal: The discount is capped at 100% of the eligible subtotal. All eligible items are set to $0.00.
• 100% percentage discount: Valid. All eligible items are set to $0.00.

Migrating from Manual Discount Handling

If your integration previously handled discounts by pre-calculating discounted prices before sending them to TaxCloud, or by using negative line items as implicit discounts, here’s what you need to know from the January 2026 release:

Negative Line Items Are No Longer Supported

The API now enforces a minimum price of 0 on all line items. Requests containing negative prices will be rejected with a validation error. If you previously used negative line items to represent order-level discounts, you should replace them with the discount field on the order.

Before (no longer supported):

1
{
2
  "lineItems": [
3
    { "itemID": "SKU-1001", "price": 100.00, "quantity": 1, "TIC": "00000" },
4
    { "itemID": "DISCOUNT", "price": -10.00, "quantity": 1, "TIC": "00000" }
5
  ]
6
}

After (use the discount field):

1
{
2
  "lineItems": [
3
    { "itemID": "SKU-1001", "price": 100.00, "quantity": 1, "TIC": "00000" }
4
  ],
5
  "discount": {
6
    "type": "amount",
7
    "value": 10.00
8
  }
9
}

Pre-Calculated Discounts Still Work

If you prefer to continue pre-calculating discounted prices in your integration code and submitting the reduced price directly, that approach still works. Simply send the already-discounted price in the price field without using the discount fields. However, the originalPrice field will not be populated in the response, and you will be responsible for maintaining your own pre-discount price records.

Using the native discount fields is recommended because:

• TaxCloud automatically handles TIC-based exclusion rules
• Original prices are preserved for audit trails
• Refund calculations are handled correctly without additional logic on your side
• Discount distribution for order-level discounts uses banker’s rounding for precision

Best Practices

• Use the native discount fields rather than pre-calculating discounted prices, especially for order-level discounts where proportional distribution and TIC exclusions apply.
• Apply line-item discounts for shipping if you need to discount shipping costs. Order-level discounts automatically skip shipping items.
• Don’t worry about excise tax exclusions, TaxCloud enforces these automatically. If you accidentally include a discount on an excise tax item, it will be ignored.
• Check the originalPrice field in the response if you need to display or record the pre-discount price for customer receipts or accounting.
• No special handling needed for refunds — submit the refund normally and TaxCloud will use the correct discounted amounts.
• Be aware of rounding on very small prices. Banker’s rounding on items priced at $0.01 or $0.02 can cause small discounts to round away. This is expected behavior.
• Handle the all-excluded error case if your orders could potentially contain only shipping or excise tax items. Applying an order-level discount when no eligible items exist returns an error.

Rounding and Precision

All discount calculations are performed with high precision, and final prices are rounded to 2 decimal places (cents) using banker’s rounding (round half to even).

Banker’s rounding differs from standard rounding when a value falls exactly on the halfway point. Instead of always rounding up, it rounds to the nearest even number, which reduces cumulative rounding bias across many transactions.

Examples:

Minimum price rules:

• Prices that round to $0.00 are allowed when the result comes from a legitimate discount calculation (e.g., a 50% discount on a $0.01 item) or from a 100% discount.
• In rare cases, a very small discount may effectively disappear due to rounding. For example, a 40% discount on a $0.01 item calculates to $0.006, which rounds back up to $0.01.