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 following are some of the key data elements for the Orders API:

• Orders. An order is a top-level container representing a request to purchase goods or services from a business. Every order includes fields for line item details, fulfillment details, and order summary data, such as the location ID credited with the order and the total amount of taxes collected.

• Line items. Individual items that are purchased as part of the order (for example, an order for a sandwich and two cups of tea). Each line item can have one or more modifiers to represent an available size or color (for example, a chicken sandwich with extra mustard). Line items and modifiers can be built from Catalog API objects or created ad hoc (at the time of creation).

• Price adjustments. An order (or individual line items) might be eligible for discounts or subject to service charges and taxes. The Orders API calculates and applies any price adjustments at the order or line item level. Price adjustments can be configured as Catalog API objects or created ad hoc.

• Fulfillment information. Additional details about how to fulfill this type of order, such as the customer name or the time at which the customer should pick up the order. Every order that has fulfillment information is pushed to the Seller Dashboard when charged, so that sellers can manage order fulfillment in the Square Point of Sale application.

• Order source. 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 supports three types of fulfillment orders: Pickup, Shipment, and Delivery. 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 Manage Customer Profiles.

Link to section

Customer assignments for orders and payments

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

• Linking orders and payments to customers helps provide a more seamless experience for Square sellers and their customers. When possible, you should specify the customer_id when you create a payment or an order. If you do not have the customer ID, use information collected from the customer to call SearchCustomers to find a matching customer profile. If one cannot be found, call CreateCustomer to create a new profile using the information collected from the customer.

  If your application does not collect any information from the customer, you can omit the customer_id and rely on Square's inference to find the best matching customer profile or to create an instant profile to associate with the payment. Note that this process is asynchronous and might take some time before customer_id is added to the payment. If Square cannot find a matching customer profile and cannot create an instant profile, the customer_id field of the payment remains unset. In this case, the transaction is not associated with a customer in Square products, such as Square Point of Sale and the Seller Dashboard.

• Orders made from a Square Online store might not be immediately associated with a customer. When a new buyer places an order from a Square Online store, Square attempts to create an instant profile in the seller's Customer Directory and then assign the profile to the order. This process is asynchronous and might take some time to update the customer information when viewed on the Transactions page in Square Point of Sale or the Seller Dashboard. The delay does not occur if the buyer is a returning customer.

  Similarly, these orders might not include a customer_id when retrieved using the Orders API. Instead of relying on this field for your integration, consider using the customer_id field of the corresponding payment, which is more likely to be populated. If this field is not specified when the payment is created, Square attempts to set it by finding a matching customer profile or creating an instant profile.

• 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