Handling Discounts with TaxCloud

When applying discounts in your checkout flow, it’s essential to process them correctly before sending cart data to TaxCloud. Incorrect handling can result in tax miscalculations, overcharging or undercharging customers, and compliance issues.

If you want to apply both line-item and order-level discounts in a way that ensures accurate tax calculations, this guide will help you. See the Best Practices section for critical notes for successful discount handling.

TaxCloud does not accept discounts as a separate field. Instead, all prices sent to TaxCloud should already reflect any discounts applied. You must ensure that all discount calculations are performed before submitting data to TaxCloud’s API.

Line Item Discounts

A line-item discount applies directly to a specific item in the cart. For example, a coupon that gives 20% off a single product. The key rule is: apply the discount to the item’s price before sending it to TaxCloud.

Steps to Apply Line Item Discounts

1. Reduce the item’s price by the discount amount or percentage.
2. Send the adjusted price in the lineItems array in your API request.
3. TaxCloud will calculate tax based on this new (discounted) price.

Example Request

If a product originally costs $10 and has a 20% discount, the price submitted to TaxCloud should be $8:

1
{
2
    "itemID": "SKU123",
3
    "price": 8.00,  // Original price was $10, after 20% discount
4
    "quantity": 1,
5
    "TIC": 0
6
}

This ensures that tax is applied correctly to the post-discount amount.

Order-Level Discounts

Order-level discounts apply to the entire cart rather than individual items. These discounts must be distributed correctly across all items to avoid tax miscalculations.

NOTE

Order-level discounts should typically be applied only to item subtotals. Shipping costs should not be discounted unless that is explicitly intended by your pricing logic.

The approach differs based on whether the discount is percentage-based or dollar-based.

Scenario A: Percentage-Based Order Discounts

If the discount is given as a percentage (e.g., “10% off the total order”), apply the same percentage reduction to each item’s price before submitting to TaxCloud.

Steps to Apply Percentage-Based Order Discounts

1. Retrieve the discount percentage.
2. Apply this percentage reduction to each line item’s price.
3. Submit the adjusted item prices to TaxCloud.

Example Calculation

If a 10% discount is applied to a $50 item, the new price should be calculated as:

1
discounted_price = item_price * (1 - discount_percentage)

For a $50 item with a 10% discount:

1
discounted_price = 50 * (1 - 0.10) = 45

TaxCloud will calculate tax based on this adjusted price.

Scenario B: Dollar-Based Order Discounts

If the discount is a fixed dollar amount (e.g., “$10 off the total order”), it must be converted into a percentage to ensure proper distribution across all items.

Steps to Apply Dollar-Based Order Discounts

1. Exclude shipping when calculating the order subtotal.
2. Compute the discount percentage as:

1
percent_discount = discount_dollars/ order_subtotal_excl_shipping

3. Apply this percentage discount to each item’s price.

Best Practices

Follow these best practices to ensure accurate tax calculations when applying discounts:

1. Apply line-item discounts first before calculating order-level discounts.
2. Always submit prices with the discount pre-applied. TaxCloud does not accept a separate discount field.
3. Exclude shipping when computing the discount percentage for dollar-based order discounts.
4. Ensure no prices go negative after discounting.
5. Apply discounts regardless of an item’s taxability, since TaxCloud will handle exemption logic separately.

Handling Multiple Discounts

If both line-item and order-level discounts are applied, follow this sequence:

1. Apply line-item discounts first.
2. Compute the order subtotal excluding shipping.
3. Calculate the order-level discount percentage.
4. Apply that percentage reduction to each item.
5. Submit the final adjusted prices to TaxCloud.

This ensures that all discounts are accounted for before tax is calculated.

Common Pitfalls to Avoid

Avoid these mistakes when implementing discount calculations:

• Incorrectly applying dollar-based discounts to a single item instead of distributing them proportionally across all items.
• Including shipping costs when computing the discount percentage for order-level discounts.
• Sending pre-discounted prices without considering taxability rules, leading to incorrect tax amounts.
• Allowing negative item prices after discounts, which could cause validation errors in TaxCloud.

Handling discounts properly ensures accurate tax calculations and compliance with sales tax regulations. By following the outlined steps, developers can seamlessly integrate discount logic into their TaxCloud API requests while preventing common errors.

If you have questions about discount implementation, please contact support.