How It Works

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:

1. Specify a catalog item ID - If you've already set up your catalog, you can provide a valid catalog_object_id in the OrderLineItem. This automatically populates the item with product details from the Catalog API. It also automatically updates your inventory when the Order is closed or charged.

2. Define the line item ad hoc - If you don't have a catalog_object_id to reference, you can define the OrderLineItem details 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:

1. SHIPMENT - A shipping carrier ships the fulfillment to a recipient.
2. PICKUP - A recipient picks up the fulfillment at a physical location.
3. DELIVERY - A courier delivers the fulfillment to the recipient.

For more information, see Manage Order Fulfillments.

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:

1. 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.

2. 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.

3. Taxes - A tax is defined by an OrderLineItemTax object in the taxes array of the Order. You can scope an OrderLineItemTax so 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 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.

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:

1. The application gathers information about the order and builds an Order object.
2. The application sends the Order to the CreateOrder endpoint.
3. The CreateOrder endpoint determines the initial item totals, discounts, service charges, and taxes.
4. The CreateOrder endpoint returns the updated Order to the application.

All order details are available through the BatchRetrieveOrders and SearchOrders endpoints.

Fulfillment orders only appear in the Square Dashboard after they're charged. Note that fulfillment orders must have delay_capture set to true.

• Create Orders
• Pay for Orders
• Order Price Adjustments
• Order Service Charges
• Order Discounts
• Order Taxes