Orders API

Applies to: Orders API | Catalog API | Customers API

Learn about the Orders API and how to track and manage the lifecycle of a purchase.

The Orders 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.

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 CatalogItemVariation and CatalogModifier 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's name or the time at which the customer should pick up the order. Every order that has fulfillment information is pushed to the Square 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.

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 supports three types of fulfillment orders: Pickup, Shipment, and Delivery. For more information, see Add fulfillment details.

The Orders API can also get orders that are originated and completed on the Square Point of Sale application. Such an order might have the Order.source field set to SQUARE_POS. Any associated payments will have the Payment.application_details.square_product field set to SQUARE_POS. If an order is created while Point of Sale is in Offline mode, the created_at timestamp is set to the time that a Square server received the create request from Point of Sale.

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 item variations and other catalog objects include:

• Orders that reference catalog IDs for taxes and discounts are automatically calculated and applied to these price modifiers.
• Orders with ad-hoc items can still get the correct tax amounts when letting Square automatically apply taxes by using a seller-defined CatalogTax.
• 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.

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.

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 don't 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 doesn't 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 the 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 isn't associated with a customer in Square products, such as Square Point of Sale and the Square 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 Square Dashboard. The delay doesn't 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 isn't 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 doesn't 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.

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.

• Create Orders
• Pay for Orders
• Video: Manage Orders with the Orders API