What It Does
Create, track, and manage orders in your web and mobile applications.
The Orders API integrates parts of the Square ecosystem to track and manage the lifecycle of a purchase. The API can record purchase items, calculate totals, confirm payments, track an order's progress through fulfillment, and update a catalog inventory.
With the Orders API, you can build web and mobile applications that use orders to manage purchase item information, track order fulfillment, integrate customer data, and link payments. You can also create fulfillment orders and send them to the Square Point of Sale application for fulfillment.
The Orders API works with the following key data types:
Order. The top-level container for order information. Order objects include fields for line item details, fulfillment details, and order summary data, including the location ID credited with the order and the total amount of taxes collected.
OrderLineItem. Represents a purchase item (for example, a coffee or T-shirt). Each line item has a
OrderLineItemModifierthat represents an available size or color. Items and modifiers can be built from Catalog objects or they can be defined ad hoc (at the time of creation).
OrderLineItemTax. A price modifier that can be applied at the order or line item level. Taxes and discounts can be configured as
Catalogobjects and referenced in the order or they can be created ad hoc.
OrderFulfillment. Contains details about how to fulfill this order, such as the customer name or the time at which the customer should pick up the order.
Orderobjects made with fulfillments are pushed to the Seller Dashboard when charged, so sellers can manage order fulfillment in the Square Point of Sale application.
OrderSource. Tracks the digital or physical source of the order. Orders can be searched or retrieved by the source.
For more information, see Orders objects and data types.
The Orders API integrates seamlessly with other Square APIs and resources to expand the functionality of your application.
Orders with fulfillment that have been fully paid are pushed to the Square Point of Sale application, so that sellers can manage fulfillment with the Square Point of Sale application. The Orders API currently supports two types of fulfillment orders: Pickup and Shipment. For more information, see Add fulfillment details.
Link your payments to
Order objects to itemize sales and apply price modifiers such as taxes, discounts, and service charges. You can also use the Orders API to retrieve any payment activity associated with a sale, whether from the Square Point of Sale application, invoices, or an integration build with the Payments API and Orders API.
For more information, see Pay for Orders.
Line items, line item modifiers, taxes, and discounts can all be defined as catalog objects. The Orders API reaches its full range of capabilities when orders are built using Square catalog objects.
Key advantages to using catalog items include:
Orders that reference catalog IDs for taxes and discounts are automatically calculated and applied these price modifiers.
Orders that reference catalog line items use details defined in the catalog, such as the item name and price.
When these orders are closed, Square updates the inventory for those items.
Did you know?
Orders can also be built from ad hoc line items defined at the time of
Order object creation. You need to supply an item name and price.
Order objects can reference a customer profile. You can later use
SearchOrders to search orders by customer. For more information about making customer profiles, see Keep Records of Customer Profiles.
The Orders API integration with the Customers API is in beta. For more information about known beta issues, see the changelog.
You should be aware of the following considerations regarding customer assignments:
In the Seller Dashboard, transaction activity is based on the
customer_idof the order and other related settings, but the
customer_idof the payment is ignored. For example, if the order does not have a customer assignment, the transaction's Paid by field might not display the customer who is assigned to the payment. To reliably link transactions to customers in the Seller Dashboard, make sure to specify the
customer_idfield in your
In addition, omitting the
customer_idfield on the
Orderobject might result in the creation of new instant profiles that are linked to the payment.
If a customer ID is added to a payment in the Seller Dashboard, the ID is not available in the corresponding
Orderobject retrieved using Square APIs.
Orders made from a Square Online store might not include a
customer_idwhen retrieved from the Orders API, so you should not rely on this field for your integration.
Sellers can merge duplicate customer profiles that represent the same customer. The merge operation deletes the existing customer profiles and creates a new aggregated customer profile with a new ID. Currently, searching for orders using the new customer ID does not return any orders that were made using a previous customer ID.
As a workaround, you should store all previous customer IDs and provide them in the
customer_idsquery filter in your
SearchOrdersrequest. To obtain these IDs, subscribe to
customer.createdwebhook events and check whether the notifications contain the
event_context.mergefield. This field is included when the customer profile is created from a merge operation and contains the IDs of all affected customer profiles. For more information, see Notifications for customer profile merge events.