Orders API

Create Orders

You can create Order objects by calling the CreateOrder endpoint. Orders 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.

Create line items Permalink Get a link to this section

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.

Option 1: Get the catalog_object_id for your line item Permalink Get a link to this section

The following sample cURL command creates an order using catalog items:

  1. Replace COFFEE_ITEM_ID with your catalog item ID and SMALL_MODIFIER_ID with your catalog item variation ID.

  2. Generate a unique string for your idempotency key.

  3. Send a POST request to the CreateOrder endpoint (/v2/orders).

    For more information about line items, see the Orders API Technical Reference.

    Create Order
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16
    • 17
    • 18
    • 19
    • 20
    • 21
    • 22
    curl https://connect.squareupsandbox.com/v2/orders \
  -X POST \
  -H 'Square-Version: 2021-04-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": "{COFFEE_ITEM_ID}",
          "modifiers": [
            {
              "catalog_object_id": "{SMALL_MODIFIER_ID}"
            }
          ],
          "quantity": "1"
        }
      ]
    }
  }'
    Try in API Explorer

Option 2: Define a line item ad hoc Permalink Get a link to this section

The following sample cURL command creates an order with a line item:

  1. Replace name and quantity.

  2. Set base_price_money with a money object representing your cost. For more information, see Working With Monetary Amounts.

  3. Generate a unique string for your idempotency key.

  4. Send a POST request to the CreateOrder endpoint (/v2/orders).

    The following shows a sample JSON body for a cURL command that creates an order using an ad hoc line item:

    Create Order
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16
    • 17
    • 18
    • 19
    • 20
    • 21
    curl https://connect.squareupsandbox.com/v2/orders \
  -X POST \
  -H 'Square-Version: 2021-04-21' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "order": {
      "location_id": "X9XWRESTK1CZ1",
      "line_items": [
        {
          "name": "Small Coffee",
          "quantity": "1",
          "base_price_money": {
            "amount": 500,
            "currency": "USD"
          }
        }
      ]
    }
  }'
    Try in API Explorer

    For more information about line items, see the Orders API Technical Reference.

Add fulfillment details Permalink Get a link to this section

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

This 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: 2021-04-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

View orders in the Seller Dashboard Permalink Get a link to this section

An order appears in the Seller Dashboard 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.

Calculate Order Permalink Get a link to this section

While 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.

Related topics Permalink Get a link to this section