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.
Important
If you use the Square Orders API with a non-Square payments provider, Square charges a transaction fee. For more information, see Orders API fee structure.
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 anOrderLineItemModifier
that represents an available size or color. Items and modifiers can be built fromCatalog
objects or they can be defined ad hoc (at the time of creation).OrderLineItemDiscount
andOrderLineItemTax
. A price modifier that can be applied at the order or line item level. Taxes and discounts can be configured asCatalog
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.
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 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.
Did you know?
Orders can also be built from ad hoc line items defined when the Order
object is created. You only 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.
Important
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, a transaction activity is based on the
customer_id
of the order and other related settings, but thecustomer_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 thecustomer_id
field in yourCreateOrder
request.In addition, omitting the
customer_id
field on theOrder
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
orOrder
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 yourSearchOrders
request. To obtain these IDs, subscribe tocustomer.created
webhook events and check whether the notifications contain theevent_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:
Event | Permission | Description |
---|---|---|
order.created | ORDERS_READ | An Order was created. |
order.fulfillment.updated | ORDERS_READ | An OrderFulfillment was created or updated. |
order.updated | ORDERS_READ | An Order was updated. |
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.
If you need more assistance, contact Developer Support or ask for help in the Developer Forums.