Accurate Order Amounts: Calculations and Using Tax Subtotals

This guide provides a comprehensive overview of how to accurately calculate order amounts, including gross_amount, net_amount, and tax_amount, from the line item to the overall order level. It also details the use of tax subtotals for enhanced validation, compliance, and integration robustness.

Core Principles of Amount Calculation

Understanding the foundational formulas for calculating amounts at both the line item and order levels is crucial for avoiding validation errors when integrating with our endpoints.

Definitions

  • line_item.unit_price: Price per unit, excluding tax.
  • line_item.quantity: Number of units.
  • line_item.discount_amount: Line item level discount, excluding tax. Note: Discounts are not applied at the unit level.
  • line_item.net_amount: Amount after discounts and before taxes.
  • line_item.tax_amount: net_amount multiplied by the tax_rate.
  • line_item.gross_amount: tax_amount added to the net_amount.

Line Item Level Calculations

  • line_item.net_amount = line_item.quantity * line_item.unit_price - line_item.discount_amount
  • line_item.tax_amount = line_item.net_amount * line_item.tax_rate
  • line_item.gross_amount = line_item.net_amount + line_item.tax_amount

Order Level Calculations

  • order.net_amount = SUM(line_item.net_amount) (i.e., SUM(line_item.quantity * line_item.unit_price - line_item.discount_amount))
  • order.tax_amount = SUM(line_item.tax_amount) (i.e., SUM(line_item.net_amount * line_item.tax_rate))
  • order.gross_amount = SUM(line_item.gross_amount) (i.e., SUM(line_item.net_amount + line_item.tax_amount))

Important Note: Calculating amounts based on gross amounts as the foundation, instead of the unit price, can lead to rounding errors and subsequent validation issues.

The Role and Benefits of Tax Subtotals

Tax subtotals provide a structured breakdown of taxes within an order, categorized by tax rate, the total tax amount for that rate, and the total taxable amount (the sum of net amounts for items sharing that tax rate). Utilizing tax subtotals offers several advantages:

  • Enhanced Validation: Orders incorporating tax subtotals are more straightforward to verify, reducing the likelihood of rejection due to calculation errors.
  • Compliance Adherence: They help in meeting regulatory requirements by clearly itemizing tax components.
  • Future-Proof Integration: Adopting tax subtotals ensures your integration remains robust and adaptable to potential future enhancements in our tax calculation and validation mechanisms.
  • Improved Transparency: Clearly see how much tax is applied at each distinct tax rate.
  • Simplified Troubleshooting: Quickly identify and resolve discrepancies or missing tax information.

Calculation Rules and Validation with Tax Subtotals

When tax_subtotals are included in an order (this is generally recommended, regardless of region), specific calculation and validation rules apply:
  • line_item.net_amount = line_item.unit_price * line_item.quantity - line_item.discount_amount
    • Deviation Tolerance: 0.02
  • order.tax_subtotals.tax_amount = SUM(line_item.tax_amount for a given tax_rate) which is effectively SUM(line_item.net_amount * line_item.tax_rate) for all line items sharing the same tax_rate, with the result rounded to 2 decimal places.
    • Deviation Tolerance: 1.00 for the sum at the tax_subtotal level.
  • order.tax_subtotals.taxable_amount = SUM(line_item.net_amount for a given tax_rate)

Order Validation Checker Tool

Use the interactive tool below to validate your order JSON, see a breakdown of tax subtotals, and generate the correct subtotal structure for your API requests.

How to use this tool

  1. Paste your order JSON into the designated area (or use one of the provided examples).
  2. The tool will instantly display a breakdown of the tax subtotals and perform a validation check against the expected calculations.
  3. You can then copy the generated tax_subtotals array for direct use in your API requests.

Order Validation Checker

Choose an example or validate your own order schema for tax subtotals and order math.

Order JSON Example

Tip: If you don't have a sample order readily available, use the example buttons within the tool to generate one instantly. All calculations and validation logic employed by the checker mirror what the API expects.