Orders API Overview

The Orders API lets you build applications 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. It can also create fulfillment orders and send them to the Square Point of Sale application for fulfillment.

Link to section

Orders components

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 an OrderLineItemModifier that 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).

• OrderLineItemDiscount and OrderLineItemTax. A price modifier that can be applied at the order or line item level. Taxes and discounts can be configured as Catalog objects 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. Order objects 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.

Link to section

Integrating with the Orders API

The Orders API integrates seamlessly with other Square APIs and resources to expand the functionality of your application.

Link to section

Square Point of Sale

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 to section

Payments

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.

Link to section

Catalog

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

Use the Catalog API to build a catalog and unlock the full range of capabilities of the Orders API. For more information, see Create Orders.

Link to section

Customers

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.

Link to section

Customer assignments for orders and payments

You should be aware of the following considerations regarding customer assignments:

• In the Seller Dashboard, a transaction activity is based on the customer_id of the order and other related settings, but the customer_id of 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_id field in your CreateOrder request.

  In addition, omitting the customer_id field on the Order object 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 Payment or Order object retrieved using Square APIs.

• Orders made from a Square Online store might not include a customer_id when 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_ids query filter in your SearchOrders request. To obtain these IDs, subscribe to customer.created webhook events and check whether the notifications contain the event_context.merge field. 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.

Link to section

Webhooks

A webhook is a subscription that notifies you when a Square event occurs. The Orders API supports the following events:

For more information about using webhooks, see Square Webhooks Overview. For a list of webhook events you can subscribe to, see V2 Webhook Events Reference.

Link to section

Related topics

• Create Orders

• Pay for Orders

• Video: Manage orders with the Orders API