Take a deeper look at the Orders API.
Each order is represented by an Order object. An Order provides detailed information about a commerce-related event, such as a sale, fulfillment, return, or exchange.
An Order also provides access to additional data that can be found in other Square APIs. For example, you can use the fields within an Order to:
- Determine the customer's name and address from the Customers API.
- Look up item variations (such as sizes or colors) from the Catalog API.
- Retrieve detailed payment data from the Payments API.
An OrderLineItem contains details about an item, such as its name, quantity, base price, and price adjustments (discounts, service charges, and taxes). Within an Order, the line_items array contains the OrderLineItem objects for that order.
There are two ways to define an OrderLineItem:
Specify a catalog item ID - If you've already set up your catalog, you can provide a valid
catalog_object_idin theOrderLineItem. This automatically populates the item with product details from the Catalog API. It also automatically updates your inventory when theOrderis closed or charged.Define the line item ad hoc - If you don't have a
catalog_object_idto reference, you can define theOrderLineItemdetails manually.
A Fulfillment lets you track additional details that are required to close the order. Within an Order, the fulfillments array contains all the Fulfillment objects for the order.
There are three types of Fulfillment:
SHIPMENT- A shipping carrier ships the fulfillment to a recipient.PICKUP- A recipient picks up the fulfillment at a physical location.DELIVERY- A courier delivers the fulfillment to the recipient.
For more information, see Manage Order Fulfillments.
Note
If you use the Orders API to create a fulfillment order, the order appears in the Square Point of Sale application after it is charged. The order payment must be approved with delayed capture. For more information, see Using the Orders API (PayOrder endpoint).
You can specify one or more price adjustments to modify the total cost of an order or individual line items. Price adjustments are defined at the Order level. They can then be applied to the order as a whole or to individual items in the order.
There are three types of price adjustments:
Discounts - A discount is defined by an OrderLineItemDiscount object in the
discountsarray of theOrder. You can scope anOrderLineItemDiscountso that it can apply to the entire order or to one or more line items.Service charges - A service charge is defined by an OrderServiceCharge object in the
service_chargesarray of theOrder. AnOrderServiceChargecan be based on the total amount of the order or apportioned based on the individual items in the order.Taxes - A tax is defined by an OrderLineItemTax object in the
taxesarray of theOrder. You can scope anOrderLineItemTaxso that it can apply to the entire order or to one or more line items.
For more information, see Discounts, service charges, and taxes.
Every Order object has a read-only id field, which contains a system-generated unique identifier for the order (for example, 7j32iSjnCZFuTwFA06Jy5fDKb0GZY).
The embedded objects within an Order have uid fields (unique IDs) to distinguish individual objects from each other. For example, suppose an order's taxes array contains two elements for sales taxes: one for the city and one for the state. You could set the uid for the first element to CITYTAX and the uid for the second element to STATETAX.
If you don't provide values for the unique ID fields, the Orders API generates unique values for them and returns them in the API responses.
Note
ID fields are limited to 60 characters and limited to letters, numbers, hyphens, underscores, and periods.
Orders can be created by Square products such as Square Point of Sale or the Reader SDK integration. Orders can also be created manually using the CreateOrder endpoint.
At a high level, your application can manually create an order using the following steps:
- The application gathers information about the order and builds an Order object.
- The application sends the
Orderto the CreateOrder endpoint. - The
CreateOrderendpoint determines the initial item totals, discounts, service charges, and taxes. - The
CreateOrderendpoint returns the updatedOrderto the application.
Important
Managing the order state is critical to ensure that customers are properly charged. When an Order object is created, Square takes a snapshot of the state of the objects included and uses that snapshot to process the transaction. Even if the price of the item changes before the transaction completes, the Orders API uses that original price to calculate the total.
You should create Order objects immediately before processing the transaction. Otherwise, you need to create a new Order object to capture any changes that occur.
The Orders API calculates and applies any discounts, service charges, and taxes that might be applicable. It does this by performing price adjustments on the line items in the order. These price adjustments are scoped as follows:
- Item level - The price adjustment is applied directly to the applicable line item.
- Order level - The price adjustment is distributed across all the line-item subtotals.
The Orders API performs its 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 (rounded down from 0.51) |
| 0.715 | 0.72 | 0.72 (unchanged from Common Rounding) |
| 0.085 | 0.09 | 0.08 (rounded down from 0.09) |
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. This shows how the Orders API arrives at its calculations, without having to actually create any orders.
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
In the response, the gross_sales_money elements reflect the item totals, while net_amount_due_money reflects the subtotal for the order ($116.00).
{ "order": { ... "line_items": [ { ... "quantity": "2", "name": "Dog Biscuits - Chicken Flavor", "base_price_money": { "amount": 1500, "currency": "USD" }, "gross_sales_money": { "amount": 3000, "currency": "USD" }, ... }, { ... "quantity": "1", "name": "Handmade Sweater - Blue", "base_price_money": { "amount": 5000, "currency": "USD" }, "gross_sales_money": { "amount": 5000, "currency": "USD" }, ... }, { ... "quantity": "3", "name": "Chewy Rawhide - Beef Flavor", "base_price_money": { "amount": 1200, "currency": "USD" }, "gross_sales_money": { "amount": 3600, "currency": "USD" }, ... } ], ... "total_money": { "amount": 11600, "currency": "USD" }, ... "net_amount_due_money": { "amount": 11600, "currency": "USD" } } }
After calculating the item totals, the Orders API considers any applicable discounts:
- A discount can be based on a percentage (for example, 10% off) or based on a fixed amount (for example, $3.50 off).
- A discount can be applied to an individual item or applied to the entire order.
These can be combined into four basic discount types:
- Item-level percentage discounts
- Order-level percentage discounts
- Item-level fixed-amount discounts
- Order-level fixed-amount discounts
The Orders API calculates and applies the discounts in the order previous shown. You can specify multiple discounts of each type per order.
Chicken-flavored dog biscuits have been discontinued, so this item receives a 7% discount. The following CalculateOrder request defines the discount (DISCONTINUED-7-PCT) and applies it to the item in question:
Calculate order
In the response, the total_discount_money for the item is $2.10, which is 7% of the gross_sales_money for the dog biscuits. The item total is therefore adjusted from $30.00 to $27.90, which lowers net_amount_due_money from $116.00 to $113.90.
{ "order": { ... "line_items": [ { ... "quantity": "2", "name": "Dog Biscuits - Chicken Flavor", "base_price_money": { "amount": 1500, "currency": "USD" }, "gross_sales_money": { "amount": 3000, "currency": "USD" }, ... "total_discount_money": { "amount": 210, "currency": "USD" }, "total_money": { "amount": 2790, "currency": "USD" }, ... "applied_discounts": [ { ... "discount_uid": "DISCONTINUED-7-PCT", "applied_money": { "amount": 210, "currency": "USD" } } ], ... }, ... ], "discounts": [ { "uid": "DISCONTINUED-7-PCT", "name": "Discontinued - 7% off", "percentage": "7", "applied_money": { "amount": 210, "currency": "USD" }, "type": "FIXED_PERCENTAGE", "scope": "LINE_ITEM" } ], ... "total_discount_money": { "amount": 210, "currency": "USD" }, ... "total_money": { "amount": 11390, "currency": "USD" }, ... "net_amounts": { "total_money": { "amount": 11390, "currency": "USD" }, ... "discount_money": { "amount": 210, "currency": "USD" }, ... }, "net_amount_due_money": { "amount": 11390, "currency": "USD" } } }
Today is National Puppy Day, so the entire order receives a 12% discount. The Orders API calculates and applies order-level discounts as line-item price adjustments, so it evenly distributes the discount across all the line item subtotals.
The following CalculateOrder request defines the discount (NATL-PUPPY-12-PCT) to be applied to all the items:
Calculate order
In the response, the 12% discount is shown as total_discount_money. This figure is then deducted from gross_sales_money, resulting in total_money for the item.
The total discount_money for the order is $13.92. When subtracted from the $116.00 item total, the resulting net_amount_due_money is $102.08.
{ "order": { ... "line_items": [ { ... "quantity": "2", "name": "Dog Biscuits - Chicken Flavor", "base_price_money": { "amount": 1500, "currency": "USD" }, "gross_sales_money": { "amount": 3000, "currency": "USD" }, ... "total_discount_money": { "amount": 360, "currency": "USD" }, "total_money": { "amount": 2640, "currency": "USD" }, ... "applied_discounts": [ { ... "discount_uid": "NATIONAL PUPPY DAY - 12 PERCENT OFF", "applied_money": { "amount": 360, "currency": "USD" } } ], ... }, { ... "quantity": "1", "name": "Handmade Sweater - Blue", "base_price_money": { "amount": 5000, "currency": "USD" }, "gross_sales_money": { "amount": 5000, "currency": "USD" }, ... "total_discount_money": { "amount": 600, "currency": "USD" }, "total_money": { "amount": 4400, "currency": "USD" }, ... "applied_discounts": [ { ... "discount_uid": "NATIONAL PUPPY DAY - 12 PERCENT OFF", "applied_money": { "amount": 600, "currency": "USD" } } ], ... }, { ... "quantity": "3", "name": "Chewy Rawhide - Beef Flavor", "base_price_money": { "amount": 1200, "currency": "USD" }, "gross_sales_money": { "amount": 3600, "currency": "USD" }, ... "total_discount_money": { "amount": 432, "currency": "USD" }, "total_money": { "amount": 3168, "currency": "USD" }, ... "applied_discounts": [ { ... "discount_uid": "NATIONAL PUPPY DAY - 12 PERCENT OFF", "applied_money": { "amount": 432, "currency": "USD" } } ], ... } ], "discounts": [ { "uid": "NATIONAL PUPPY DAY - 12 PERCENT OFF", "name": "National Puppy Day - 12% off", "percentage": "12", "applied_money": { "amount": 1392, "currency": "USD" }, "type": "FIXED_PERCENTAGE", "scope": "ORDER" } ], ... "total_discount_money": { "amount": 1392, "currency": "USD" }, ... "total_money": { "amount": 10208, "currency": "USD" }, ... "net_amounts": { "total_money": { "amount": 10208, "currency": "USD" }, ... "discount_money": { "amount": 1392, "currency": "USD" }, ... }, "net_amount_due_money": { "amount": 10208, "currency": "USD" } } }
To thank customers for their business, a Puppy Appreciation Discount is applied to dog treats. Customers save $3.00 on chicken-flavor dog biscuits and $11.00 on beef-flavor chewy rawhide.
The following CalculateOrder request defines two discounts (APPREC-3-USD and APPREC-11-USD) and applies them to the appropriate items:
Calculate order
In the response, $3.00 is deducted from the dog biscuits and $11.00 is deducted from the rawhide. The total discount_money for the order is $14.00 When subtracted from the $116.00 item total, the resulting net_amount_due_money is $102.00.
{ "order": { ... "line_items": [ { ... "quantity": "2", "name": "Dog Biscuits - Chicken Flavor", "base_price_money": { "amount": 1500, "currency": "USD" }, "gross_sales_money": { "amount": 3000, "currency": "USD" }, ... "total_discount_money": { "amount": 300, "currency": "USD" }, "total_money": { "amount": 2700, "currency": "USD" }, ... "applied_discounts": [ { ... "discount_uid": "APPREC-3-USD", "applied_money": { "amount": 300, "currency": "USD" } } ], ... }, { ... "quantity": "1", "name": "Handmade Sweater - Blue", "base_price_money": { "amount": 5000, "currency": "USD" }, "gross_sales_money": { "amount": 5000, "currency": "USD" }, ... "total_discount_money": { "amount": 0, "currency": "USD" }, "total_money": { "amount": 5000, "currency": "USD" }, ... }, { ... "quantity": "3", "name": "Chewy Rawhide - Beef Flavor", "base_price_money": { "amount": 1200, "currency": "USD" }, "gross_sales_money": { "amount": 3600, "currency": "USD" }, ... "total_discount_money": { "amount": 1100, "currency": "USD" }, "total_money": { "amount": 2500, "currency": "USD" }, ... "applied_discounts": [ { ... "discount_uid": "APPREC-11-USD", "applied_money": { "amount": 1100, "currency": "USD" } } ], ... } ], "discounts": [ { "uid": "APPREC-3-USD", "name": "Customer Appreciation Discount - $3 off", "amount_money": { "amount": 300, "currency": "USD" }, "applied_money": { "amount": 300, "currency": "USD" }, "type": "FIXED_AMOUNT", "scope": "LINE_ITEM" }, { "uid": "APPREC-11-USD", "name": "Customer Appreciation Discount - $11 off", "amount_money": { "amount": 1100, "currency": "USD" }, "applied_money": { "amount": 1100, "currency": "USD" }, "type": "FIXED_AMOUNT", "scope": "LINE_ITEM" } ], ... "total_discount_money": { "amount": 1400, "currency": "USD" }, ... "total_money": { "amount": 10200, "currency": "USD" }, ... "net_amounts": { "total_money": { "amount": 10200, "currency": "USD" }, ... "discount_money": { "amount": 1400, "currency": "USD" }, ... }, "net_amount_due_money": { "amount": 10200, "currency": "USD" } } }
To celebrate the storewide Anniversary Sale, a discount of $5.00 is applied to the entire order. The Orders API calculates and applies order-level discounts as line-item price adjustments, so it evenly distributes the discount across all the line item subtotals.
The following CalculateOrder request defines the discount (ANNI-SALE-5-USD) to be applied to all the items:
Calculate order
In the response, the $5.00 discount is distributed across the item totals, in proportion to the $116.00 subtotal for the order.
| Item | Item total | % of $116.00 | Contribution to discount |
|---|---|---|---|
| Biscuits | $30.00 | 25.86% | $1.29 |
| Sweater | $50.00 | 43.10% | $2.16 |
| Rawhide | $36.00 | 31.03% | $1.55 |
The total discount_money for the order is $5.00. When subtracted from the $116.00 item total, the resulting net_amount_due_money is $111.00.
{ "order": { ... "line_items": [ { ... "quantity": "2", "name": "Dog Biscuits - Chicken Flavor", "base_price_money": { "amount": 1500, "currency": "USD" }, "gross_sales_money": { "amount": 3000, "currency": "USD" }, ... "total_discount_money": { "amount": 129, "currency": "USD" }, "total_money": { "amount": 2871, "currency": "USD" }, ... "applied_discounts": [ { ... "discount_uid": "GLOBAL-SALES-5-DOLLARS-OFF", "applied_money": { "amount": 129, "currency": "USD" } } ], ... }, { ... "quantity": "1", "name": "Handmade Sweater - Blue", "base_price_money": { "amount": 5000, "currency": "USD" }, "gross_sales_money": { "amount": 5000, "currency": "USD" }, ... "total_discount_money": { "amount": 216, "currency": "USD" }, "total_money": { "amount": 4784, "currency": "USD" }, ... "applied_discounts": [ { ... "discount_uid": "GLOBAL-SALES-5-DOLLARS-OFF", "applied_money": { "amount": 216, "currency": "USD" } } ], ... }, { ... "quantity": "3", "name": "Chewy Rawhide - Beef Flavor", "base_price_money": { "amount": 1200, "currency": "USD" }, "gross_sales_money": { "amount": 3600, "currency": "USD" }, ... "total_discount_money": { "amount": 155, "currency": "USD" }, "total_money": { "amount": 3445, "currency": "USD" }, ... "applied_discounts": [ { ... "discount_uid": "GLOBAL-SALES-5-DOLLARS-OFF", "applied_money": { "amount": 155, "currency": "USD" } } ], "item_type": "ITEM" } ], "discounts": [ { "uid": "GLOBAL-SALES-5-DOLLARS-OFF", "name": "Global Sales - $5 off", "amount_money": { "amount": 500, "currency": "USD" }, "applied_money": { "amount": 500, "currency": "USD" }, "type": "FIXED_AMOUNT", "scope": "ORDER" } ], ... "total_discount_money": { "amount": 500, "currency": "USD" }, ... "total_money": { "amount": 11100, "currency": "USD" }, ... "net_amounts": { "total_money": { "amount": 11100, "currency": "USD" }, ... "discount_money": { "amount": 500, "currency": "USD" }, ... }, "net_amount_due_money": { "amount": 11100, "currency": "USD" } } }
After calculating and applying any discounts, the next step is to calculate and apply service charges to an order:
A service charge can be based on the total amount of the order. This can be applied before or after taxes.
A service charge can be apportioned based on the individual items in the order. It can be based on a percentage or a fixed amount. Apportioned service charges are always applied before taxes.
The time at which the service charge calculation takes place is called the calculation phase. The Orders API supports four basic calculation phases for any service charge:
- Subtotal phase - The service charge is calculated after discounts, but before taxes. This is the most common scenario for service charges.
- Total phase - The service charge is calculated after all discounts and taxes.
- Apportioned percentage phase - The service charge is calculated after discounts, but before any amount-based apportioned service charges and taxes.
- Apportioned amount phase - The service charge is calculated after any discounts and percentage-based apportioned service charges and before taxes.
Raphael's Puppy-Care Emporium has established a fund to help encourage pet adoption and is adding a service charge for this. The service charge is to be applied after discounts, but before taxes.
The following CalculateOrder request defines this service charge (PET-ADOPT-1.5-PCT) and applies it to the order:
Calculate order
In the response, the 1.5% service_charge_money ($1.74) is added to the $116.00 total so the net_amount_due_money is $117.74.
{ "order": { ... "line_items": [ { ... "quantity": "2", "name": "Dog Biscuits - Chicken Flavor", "base_price_money": { "amount": 1500, "currency": "USD" }, "gross_sales_money": { "amount": 3000, "currency": "USD" }, ... "total_money": { "amount": 3000, "currency": "USD" }, ... }, { ... "quantity": "1", "name": "Handmade Sweater - Blue", "base_price_money": { "amount": 5000, "currency": "USD" }, "gross_sales_money": { "amount": 5000, "currency": "USD" }, ... "total_money": { "amount": 5000, "currency": "USD" }, ... }, { ... "quantity": "3", "name": "Chewy Rawhide - Beef Flavor", "base_price_money": { "amount": 1200, "currency": "USD" }, "gross_sales_money": { "amount": 3600, "currency": "USD" }, ... "total_money": { "amount": 3600, "currency": "USD" }, ... } ], ... "total_money": { "amount": 11774, "currency": "USD" }, "service_charges": [ { ... "name": "PET-ADOPT-1.5-PCT", "percentage": "1.5", "applied_money": { "amount": 174, "currency": "USD" }, "calculation_phase": "SUBTOTAL_PHASE", ... "total_money": { "amount": 174, "currency": "USD" }, ... } ], "total_service_charge_money": { "amount": 174, "currency": "USD" }, "net_amounts": { "total_money": { "amount": 11774, "currency": "USD" }, ... "service_charge_money": { "amount": 174, "currency": "USD" } }, "net_amount_due_money": { "amount": 11774, "currency": "USD" } } }
The final calculations for the order involve taxes. There are two categories:
- Item-level taxes - Calculated and applied to one or more individual items.
- Order-level - Calculated for the entire order and then distributed proportionally to each item.
The Orders API processes item-level taxes first, followed by order-level taxes.
Note
In the Orders API, you must define every tax in terms of a percentage. In other words, for every tax in the taxes array of an Order, you must specify a value for the percentage parameter.
The state government has approved the following taxes, which must now be collected:
- A 5% fair trade tax, applicable to any handmade goods.
- An 8.5 sales tax on every order.
The following CalculateOrder request defines these two taxes (FAIR-TRADE-5-PCT and STATE-SALES-8.5-PCT) and applies each one appropriately:
Calculate order
In the response, the fair trade tax is applied only to the handmade sweater. The state sales tax is calculated for the order total and distributed proportionally across all of the items.
{ "order": { ... "line_items": [ { ... "quantity": "2", "name": "Dog Biscuits - Chicken Flavor", "base_price_money": { "amount": 1500, "currency": "USD" }, "gross_sales_money": { "amount": 3000, "currency": "USD" }, "total_tax_money": { "amount": 255, "currency": "USD" }, ... "total_money": { "amount": 3255, "currency": "USD" }, ... "applied_taxes": [ { ... "tax_uid": "STATE-SALES-8.5-PCT", "applied_money": { "amount": 255, "currency": "USD" } } ], ... }, { ... "quantity": "1", "name": "Handmade Sweater - Blue", "base_price_money": { "amount": 5000, "currency": "USD" }, "gross_sales_money": { "amount": 5000, "currency": "USD" }, "total_tax_money": { "amount": 675, "currency": "USD" }, ... "total_money": { "amount": 5675, "currency": "USD" }, ... "applied_taxes": [ { ... "tax_uid": "FAIR-TRADE-5-PCT", "applied_money": { "amount": 250, "currency": "USD" } }, { ... "tax_uid": "STATE-SALES-8.5-PCT", "applied_money": { "amount": 425, "currency": "USD" } } ], ... }, { ... "quantity": "3", "name": "Chewy Rawhide - Beef Flavor", "base_price_money": { "amount": 1200, "currency": "USD" }, "gross_sales_money": { "amount": 3600, "currency": "USD" }, "total_tax_money": { "amount": 306, "currency": "USD" }, ... "total_money": { "amount": 3906, "currency": "USD" }, ... "applied_taxes": [ { ... "tax_uid": "STATE-SALES-8.5-PCT", "applied_money": { "amount": 306, "currency": "USD" } } ], ... } ], "taxes": [ { "uid": "STATE-SALES-8.5-PCT", "name": "State sales tax - 8.5%", "percentage": "8.5", "type": "ADDITIVE", "applied_money": { "amount": 986, "currency": "USD" }, "scope": "ORDER" }, { "uid": "FAIR-TRADE-5-PCT", "name": "Fair Trade Tax - 5%", "percentage": "5", "type": "ADDITIVE", "applied_money": { "amount": 250, "currency": "USD" }, "scope": "LINE_ITEM" } ], ... "total_tax_money": { "amount": 1236, "currency": "USD" }, ... "total_money": { "amount": 12836, "currency": "USD" }, ... "net_amounts": { "total_money": { "amount": 12836, "currency": "USD" }, "tax_money": { "amount": 1236, "currency": "USD" }, ... }, "net_amount_due_money": { "amount": 12836, "currency": "USD" } } }
All order details are available through the BatchRetrieveOrders and SearchOrders endpoints.
Fulfillment orders only appear in the Seller Dashboard after they're charged. Note that fulfillment orders must have delay_capture set to true.