Applies to: Orders API | Catalog API
Learn how to create an order, add line items, and track fulfillment.
You can create Order
objects by calling the CreateOrder endpoint. Order
objects can be created with any combination of line items, fulfillments, taxes, and discounts. They can also be created empty and updated with elements over time.
Sellers can view orders in the Square Dashboard; however, Square pushes orders to the Square Dashboard only if the orders meet specific conditions. For more information, see View orders in the Square Dashboard or Square products.
You have two options for creating line items:
- Create a line item using a
catalog_id
, which is strongly recommended. - Create line items ad hoc without referencing existing catalog items.
The following CreateOrder request creates an order using catalog items. The request specifies one line item with an optional modifier.
To test the scenario, you need an item with one or more variations (such as small and large) and an item modifier (such as sugar and milk) in your item library. For more information, see Build a Simple Catalog.
In addition to adding your access token, update this example request by providing catalog_object_id
values from your item library (for both the line item and modifier) and your location_id
.
Create order
A line item can have one or more modifiers. In the preceding example, the order contains a line item with a quantity of 1. The line item can have a modifier, which has its own quantity field.
For example, suppose a restaurant offers hamburgers. When a customer orders one, the restaurant records the order by creating an Order
object with a line item (Hamburger). If the buyer wants a cheeseburger instead (a hamburger with cheese), the line item includes a modifier (cheese), with a quantity of 1.
If the customer wants extra cheese, the modifier quantity could be 2 or more. Conversely, if the customer doesn't want any cheese, you wouldn't add the modifiers
list at all.
If the catalog item variation referenced by the line item has a measurement_unit_id
when the order is created, a quantity_unit
property is added to the line item. quantity_unit
tells you how the item is sold on the order. For example, the item may be sold by the ounce, in which case the order.line_items[].quantity
attribute indicates how many fractions of an ounce are sold on the order. A quantity of 1.50
would mean that one and a half ounces were sold.
Note
Starting on August 15, 2024, orders created in the Square Point of Sale or other Square products can have a fractional Order.line_items[].quantity
value with no value for the quantity_unit
property. The Orders API continues to enforce the requirement to provide a quantity_unit
for fractional quantities in a CreateOrder
or CalculateOrder
request.
In the following example, the line item is sold by the ounce and could be as small as 1/1000th of an ounce (0.001
).
{
"quantity_unit": {
"measurement_unit": {
"weight_unit": "IMPERIAL_WEIGHT_OUNCE",
"type": "TYPE_WEIGHT"
},
"precision": 3,
"catalog_object_id": "QTSYO4OCO6RIV2UWZOP6BRLV",
"catalog_version": 1724952893872
}
}
If you call CreateOrder
or CalculateOrder
with a variation sold by fractional units, Square calculates the line item total as base price multiplied by the quantity as a decimal.
In this request, the catalog object HXSNEZN7N3NBGJX2XJ2Z6R5Q
is liquid photo chemicals used to process black and white film. This specialty chemical is sold for $2.34 an ounce and the buyer has ordered one ounce.
Create order
The following CreateOrder
request creates an order with one ad hoc line item (hamburger) and one modifier (cheese):
Create order
Did you know?
If you create ad hoc line items, you can't apply catalog rule-based discounts to those line items.
If an order is taxable — either a tax on the order total, or on individual line items — it needs to have taxing and discount details. Before calling CalculateOrder, be sure that you have added tax and discount details to the order. For more information, see Apply Taxes and Discounts.
To create a pickup order, you need to add a fulfillments
object to your order.
The following sample request creates a pickup order for a small coffee:
Create order
Note that this request specifies the sandbox environment ( https://connect.squareupsandbox.com/v2/orders
).
An order appears in the Square Dashboard (or Square products, such as Square Point of Sale) if both the following conditions are true:
- The order includes fulfillment.
- The order is paid.
If you're using a sandbox test account to validate your code, the order appears in the Square Dashboard for the account you are testing with. For more information, see Square Sandbox.
The CalculateOrder endpoint enables applications to preview prices without creating an order. For example, Square Virtual Terminal uses this endpoint in the application flow to show a purchase total to the buyer without creating an actual order.
Purchase total previews are also useful when applications integrate advanced pricing components, such as rewards and discounts. For example, an eCommerce application might integrate the Square loyalty program to offer buyer loyalty discounts. The application can use the CalculateOrder
endpoint to show buyers a preview of applying loyalty points to their orders without locking loyalty points until the buyers are ready to pay for the orders.
In the CalculateOrder
request, provide the following:
- An order - The order you provide can be an existing order or an order that hasn't been created.
- Proposed rewards - The rewards to apply.
The endpoint returns a view of the order to be created with the specified discount applied. Applications can then show the order as a preview to help the buyer make a decision.
The CreateOrder endpoint by default sets the state
of the order it creates to OPEN
. An OPEN
state indicates that the order can be fulfilled and payment can be processed.
In some application scenarios, such as an eCommerce cart building application, buyers add items to the cart only to later abandon the order. In such scenarios, applications can create temporary orders by explicitly setting the order state
to DRAFT
in a CreateOrder
request.
{
"order": {
"line_items": …,
"state": "DRAFT"
}
}
Orders in the DRAFT
state cannot be fulfilled or paid. For example, Square products or the Payments API cannot process payments for a DRAFT
order. When the buyer is ready to make the purchase, the application can call UpdateOrder to set the order state
to OPEN
so that the order can be fulfilled or payment can be processed.
{
"order": {
"id": …,
"version": …,
"state": "OPEN"
}
}
Note that applications can use UpdateOrder
to change the state
and fulfill the order at the same time.
The Orders API doesn't provide an endpoint to delete an order. However, Square reserves the right to delete DRAFT
orders that haven't been updated in 30 days.
Applications can use the order state
as a search filter in SearchOrders
to retrieve only orders that can be fulfilled (where the state
is OPEN
) as shown:
Search orders
In summary, a DRAFT
order differs from an OPEN
order as follows:
- A
DRAFT
order cannot be fulfilled. You can create fulfillments, but they cannot progress beyond the initialPROPOSED
fulfillment state. - A
DRAFT
order cannot be paid. That is, aDRAFT
order doesn't have tenders added. - There's no guarantee you can retrieve a
DRAFT
order 30 days after creation. - A
DRAFT
order doesn't appear in Sales Summary reports in the Square Dashboard.
If your application is using the Subscriptions API to create and manage subscriptions, you will be using draft orders to create order templates that model the order that is created with each period of a subscription.
The CloneOrder endpoint enables applications to reorder without having to create an order from scratch. In the request, you provide the ID of an existing order to clone.
You can clone any existing order regardless of its state
, but the cloned order is initially DRAFT
. The clone is like any other order created using the CreateOrder
endpoint. It follows the normal order lifecycle and can be modified like any other order.
When cloning an existing order, CloneOrder
copies only the applicable fields in the new order, such as:
location_id
customer_id
line_items
(except for Square-computed fields)taxes
discounts
service_charges
pricing_options
Orders also have other fields that are specific to individual orders, such as fulfillments
, tenders
, metadata
, reference_id
, rewards
, and the timestamp fields. These field values aren't copied.
For more information and an example, see CloneOrder.