Each order is represented by an Order object. An Order provides detailed information about a commerce-related event, such as a sale, a fulfillment, a return or an 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 (sizes, colors, etc.) from the Catalog API.
retrieve detailed payment data from the Payments API.
Link to section
Line items
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 have already set up your catalog, you can provide a valid catalog_object_id in the OrderLineItem. This will automatically populate the item with product details from the Catalog API. It will also automatically update your inventory when the Order is closed or charged.
Define the line item ad hoc. If you don't have a catalog_object_id to reference, you can define the OrderLineItem details manually.
Link to section
Fulfillments
A Fulfillment lets you track additional details that are required to close the order. Within an Order, the fulfillments array contains all of the Fulfillment objects for the order.
There are three types of Fulfillment:
SHIPMENT - a shipping carrier will ship the fulfillment to a recipient.
PICKUP - a recipient will pick up the fulfillment at a physical location.
DELIVERY - a courier will deliver the fulfillment to the recipient.
If you use the Orders API to create a fulfillment order, the order will appear 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).
Link to section
Price adjustments
You can specify one or more price adjustments, to modify the total cost of an order or of 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 discounts array of the Order. You can scope an OrderLineItemDiscount so 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_charges array of the Order. An OrderServiceCharge can 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 taxes array of the Order. You can scope an OrderLineItemTax so that it can apply to the entire order, or to one or more line items.
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 one another. For example, supposes that 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, then the Orders API generates unique values for them and returns them in the API responses.
Note
ID fields are limited to 60 characters and are limited to letters, numbers, hyphens, underscores, and periods.
Link to section
Order creation process flow
Orders can be created by Square products such as the Square Point of Sale or Reader SDK integration. They can also be created manually, using the CreateOrder endpoint.
At a high level, your app can manually create an order using the following steps:
The app gathers information about the order, and builds an Order object.
The app sends the Order to the
Create Order endpoint.
The Create Order endpoint determines the initial item totals, discounts, service charges and taxes.
The Create Order endpoint returns the updated Order to the app.
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.
Link to section
Discounts, service charges, and taxes
The Orders API calculates and applies any discounts, service charges and taxes that may 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 of the line item subtotals.
Link to section
Rounding rules
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)
Link to section
Example use case
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.
Link to section
Initial item totals
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:
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 it can be based on a fixed amount (for example, $3.50 off).
A discount can be applied to an individual item, or it can be applied to the entire order.
These can be combined into four basic discount types:
Item-level percentage discounts
Order-level percentage discounts
Order-level fixed-amount discounts
Item-level fixed-amount discounts
The Orders API calculates and applies the discounts in the order shown above. You can specify multiple discounts of each type per order.
Link to section
1. Item-level percentage discount
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:
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.
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 of the line item subtotals.
The following CalculateOrder request defines the discount (NATL-PUPPY-12-PCT) to be applied to all of the items:
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.
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 of the line item subtotals.
The following CalculateOrder request defines the discount (ANNI-SALE-5-USD) to be applied to all of the items:
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 then to the appropriate items:
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.
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 either 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 on 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:
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.
