Applies to: Orders API | Catalog API
Learn how to adjust prices on an order with taxes, discounts, and service charges using the Orders API.
You can set parameters in a CreateOrder request that tells Square to adjust the line item price for any item in an order. The API calculates these adjustments and applies them as discounts, service charges, or taxes. Price adjustments are scoped as follows:
- Item level - The price adjustment is applied specifically to an applicable line item.
- Order level - The price adjustment is distributed across all the line item subtotals.
If your application shows the buyer what they will pay for an order when placed, you need to calculate the order before you actually create it. The Orders API provides the CalculateOrder endpoint that takes the same request body as CreateOrder. To preview Square's calculation before you actually create an order, provide the same request body that you will use for CreateOrder. In the CalculateOrder response, you can see that line item prices now show any discounts, taxes, or service charges that Square applied. You can set these adjustment parameters directly in an order request or, in some cases, you can refer to catalog taxes or discounts configured by a seller. When you call CreateOrder with the same request body, an order is actually created with those calculated values.
The Orders API performs its adjustment calculations using Bankers' Rounding, also known as Rounding Half to Even. Under Common Rounding rules (Round Half Up), half-values round up to the next closest integer. However, under Bankers' Rounding, half-values round to the closest even integer. This has the effect of rounding even numbers down, while leaving odd numbers unchanged.
The following table shows examples of values rounded to two decimal places using Common Rounding and Bankers' Rounding:
| Value | Common Rounding | Bankers' Rounding |
|---|---|---|
| 0.505 | 0.51 | 0.50 (0 is the closest even and 1 is odd. Round down to .50) |
| 0.715 | 0.72 | (2 is the closest even and 1 is odd. Round up two 2) |
| 0.085 | 0.09 | 0.08 (8 is the closest even and 9 is odd. Round down to 8) |
Bankers' Rounding is a rounding mode in which non-tie decimals (> 0 and ≠ 5) are rounded up or down to the nearest integer and ties (= 5) are rounded to the nearest even integer. For example, non-ties to two decimal places: 3.222 -> 3.22 and –3.228 -> –3.23. Ties to two decimal places: 3.225 -> 3.22 and –3.235 -> –3.24.
To illustrate how the Orders API calculates totals, consider an online order from Raphael's Puppy-Care Emporium. The order consists of the following items:
- Two boxes of chicken-flavored dog biscuits, at $15.00 per box.
- A handmade sweater for dogs (blue color), at $50.00.
- Three packages of beef-flavored chewy rawhide, at $12.00 per package.
The following examples use the CalculateOrder endpoint to demonstrate each step in the process.
The first step is to calculate the initial total for each item, which is the base price of the item multiplied by the quantity.
| Quantity | Description | Base price | Item total |
|---|---|---|---|
| 2 | Dog Biscuits - Chicken Flavor | $15.00 | $30.00 |
| 1 | Handmade Sweater - Blue | $50.00 | $50.00 |
| 3 | Chewy Rawhide - Beef Flavor | $12.00 | $36.00 |
The subtotal for the order is the sum of all the item totals: $30.00 + $50.00 + $36.00 = $116.00.
The following CalculateOrder request shows the items in the order and the totals calculated by the Orders API:
Calculate order
To learn about how discounts are applied to this example order, see Order Discounts. If your application will support service charges, see Order Service Charges to walk through applying service charges to this example order. To learn about applying taxes to the example order, see Order Taxes.