Order Validation & Calculations
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. Accurate order validation is critical to prevent API errors, ensure correct invoicing, and streamline payouts.
We'll also explain the importance of Tax Subtotals and provide an interactive tool to help you validate your order JSON before sending it to the Order API.
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
| Field | Description |
|---|---|
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 (not applied at 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
net_amount = (quantity × unit_price) - discount_amount
tax_amount = net_amount × tax_rate
gross_amount = net_amount + tax_amount
Order Level Calculations
order.net_amount = SUM(line_item.net_amount)
order.tax_amount = SUM(line_item.tax_amount)
order.gross_amount = SUM(line_item.gross_amount)
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, categorised by tax rate, the total tax amount for that rate, and the total taxable amount.
- Enhanced Validation: Orders with tax subtotals are more straightforward to verify
- Compliance Adherence: Helps meet regulatory requirements by clearly itemising tax components
- Future-Proof Integration: Ensures robustness and adaptability to future enhancements
- Improved Transparency: Clearly see how much tax is applied at each distinct tax rate
- Simplified Troubleshooting: Quickly identify and resolve discrepancies
Calculation Rules and Validation with Tax Subtotals
When tax_subtotals are included in an order (recommended for all regions):
| Calculation | Formula | Tolerance |
|---|---|---|
| Line item net amount | unit_price × quantity - discount_amount | ±0.02 |
| Tax subtotal tax amount | SUM(line_item.tax_amount) for a given tax_rate | ±1.00 |
| Tax subtotal 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
- Select an example or click "Validate your own order schema" to paste custom JSON
- The tool will instantly display a breakdown of the tax subtotals and perform validation
- Copy the generated
tax_subtotalsarray for direct use in your API requests
If you don't have a sample order readily available, use the example buttons to generate one instantly. All calculations and validation logic employed by the checker mirror what the API expects.