Learn how to create an order, add line items, and track fulfillment.
Orders API

Create Orders

You can create Order objects by calling the CreateOrder endpoint. Order objects can be created with any combination of line items, fulfillment objects, taxes, and discounts. They can also be created empty and updated with elements over time.

Sellers can view orders in the Seller Dashboard; however, note that Square pushes orders to the Seller Dashboard only if the orders meet specific conditions. For more information, see View orders in the Seller Dashboard or Square products.

Link to section
Create line items

You have two options for making line items:

  • You can make orders using catalog_ids, which is strongly recommended.

  • You can create line items ad hoc without referencing existing catalog items.

Link to section
Option 1: Define a line item for a catalog object

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 (such as coffee) with one or more variations (such as small and large) and an item modifier (such as sugar and milk) in your catalog. For more information, see Build a Simple Catalog.

In addition to your credentials (access token), update the request by providing catalog_object_id values (for both the line item and modifier) and a location_id.

Create Order
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
curl https://connect.squareupsandbox.com/v2/orders \
  -X POST \
  -H 'Square-Version: 2022-09-21' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "order": {
      "location_id": "{LOCATION_ID}",
      "line_items": [
        {
          "catalog_object_id": "{ITEM_VARIATION_ID}",
          "modifiers": [
            {
              "catalog_object_id": "{MODIFIER_ID}",
              "quantity": "1"
            }
          ],
          "quantity": "1"
        }
      ]
    }
  }'
Try in API Explorer

Each line item can have one or more modifiers. The preceding example specifies one modifier. The modifier quantity can be 0 or more. For example, suppose a restaurant offers a cheeseburger on the menu. When a buyer orders this item, the restaurant records the purchase by creating an Order object with a line item (burger). The line item includes a line item modifier: the name is cheese and the quantity is 1. The buyer has the option to order extra cheese (or no cheese). If the buyer chooses the extra cheese option, the modifier quantity increases to 2. If the buyer does not want any cheese, the modifier quantity is set to 0.

Link to section
Option 2: Define a line item ad hoc

The following CreateOrder request creates an order with one ad hoc line item (burger) with one modifier (extra cheese):

Create Order
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
curl https://connect.squareupsandbox.com/v2/orders \
  -X POST \
  -H 'Square-Version: 2022-09-21' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "order": {
      "location_id": "{LOCATION_ID}",
      "line_items": [
        {
          "quantity": "1",
          "base_price_money": {
            "amount": 1200,
            "currency": "USD"
          },
          "name": "Burger",
          "modifiers": [
            {
              "base_price_money": {
                "amount": 50,
                "currency": "USD"
              },
              "quantity": "1",
              "name": "extra cheese"
            }
          ]
        }
      ]
    }
  }'
Try in API Explorer

As explained in the preceding section, a line item can optionally have one or modifiers.

Link to section
Add fulfillment details

To create a pickup order, you need to configure an OrderFulfillment object and set it in your order.

The following sample command creates a pickup order for a small coffee:

Create Order
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
  • 36
  • 37
  • 38
curl https://connect.squareupsandbox.com/v2/orders \
  -X POST \
  -H 'Square-Version: 2022-09-21' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "order": {
      "location_id": "X9XWRESTK1CZ1",
      "line_items": [
        {
          "catalog_object_id": "{COFFEE_ITEM_ID}",
          "modifiers": [
            {
              "catalog_object_id": "{SMALL_MODIFIER_ID}"
            }
          ],
          "quantity": "1"
        }
      ],
      "fulfillments": [
        {
          "type": "PICKUP",
          "state": "PROPOSED",
          "pickup_details": {
            "recipient": {
              "display_name": "Jaiden Urie"
            },
            "expires_at": "2019-02-14T20:21:54.859Z",
            "auto_complete_duration": "P0DT1H0S",
            "schedule_type": "SCHEDULED",
            "pickup_at": "2019-02-14T19:21:54.859Z",
            "note": "Pour over coffee"
          }
        }
      ]
    }
  }'
Try in API Explorer

Link to section
View orders in the Seller Dashboard or Square products

An order appears in the Seller Dashboard (or Square products, such as Square POS) if both the following conditions are true:

  • The order includes fulfillment.

  • The order is paid.

If you are testing in the Square Sandbox, the order appears in the Seller Dashboard in Sandbox mode, but not in Production mode. For more information, see Sandbox Seller Dashboard.

Link to section
Calculate an order

While the CreateOrder endpoint creates an order (persists the order), 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 pricing to the buyer without creating an order. The order is created only after the buyer proceeds to checkout. You can integrate CalculateOrder in your applications. For more information about Virtual Terminal, see Get Started with Virtual Terminal.

Pricing 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 order. For example, see Deferred reward creation.

In the CalculateOrder request, you provide the following:

  • A complete order. The order you provide can be an existing order or an order that has not been created.

  • Proposed rewards. The rewards to apply.

The endpoint creates a copy of the order (not persisted) with the specified discount applied. Applications can then show the order as a preview to help the buyer make a decision.

Link to section
Create a draft order

In the current implementation, 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.

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
{
  "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.

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
{
  "order": {
    "id": …,
    "version": …,
    "state": "OPEN"
  }
}

Note that applications can use UpdateOrder to both change the state and fulfill the order at the same time.

In the current implementation, the Orders API does not provide an endpoint to delete an order. However, Square reserves the right to delete DRAFT orders that have not 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 (state is OPEN) as shown:

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
curl https://connect.squareupsandbox.com/v2/orders/search \
  -X POST \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "filter": {
        "state_filter": {
          "states": [
            "OPEN"
          ]
        }
      }
    },
    "location_ids": [
      "{LOCATION_ID}"
    ]
  }'

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 initial PROPOSED fulfillment state.

  • A DRAFT order cannot be paid. That is, a DRAFT order does not have tenders added.

  • There is no guarantee you can retrieve a DRAFT order 30 days after creation.

  • A DRAFT order does not appear in Sales Summary reports in the Seller Dashboard.

Link to section
Clone an order

The CloneOrder endpoint enables applications to easily reorder without having to create an order from scratch. In the request, you provide an existing order number to clone.

You can clone any existing order regardless of the order state, but a cloned order has DRAFT as the initial state. The cloned order is like any other order created using the CreateOrder endpoint. The order follows the normal order lifecycle and can be modified like any other order.

When cloning an existing order, the endpoint copies only the applicable fields in the new order, such as:

  • merchant_id

  • location_id

  • customer_id

  • line_items (except for server-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 are not copied.

For more information and an example, see CloneOrder.

Link to section
Related topics

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.

On this page