Orders API

Order-Ahead Application Use Case

This topic walks you through an example of how the Orders API can power an order-ahead application.

Overview Permalink Get a link to this section

Did you know?

Square also offers an order-ahead sample application that you can download and configure with your Square credentials. For more information, see Order-Ahead Sample Application.

Suppose you are building an order-ahead application for CoffeeCool, a coffee shop that uses Square for its payments processing. CoffeeCool customers can download the application to order and pay for drinks ahead of time. This way, the CoffeeCool staff can start preparing the customer's order and have it ready for pickup with the customer arrives.

Your order-ahead application can use the Orders API to do the following:

  • Create an order for the customer using catalog items.

  • Notify the seller through the Order Manager on Square Point of Sale.

  • Apply a tax and discount, and then capture and associate a payment with the order.

  • Track the order's fulfillment state and update the customer through the order-ahead application.

Create an order Permalink Get a link to this section

The customer starts the process by ordering one small coffee and one chocolate chip cookie using your order-ahead application. The customer chooses to pay using the application and pick up the order at CoffeeCool's location.

To track this, your application calls the CreateOrder endpoint to make an order for your customer. The following example references the catalog object IDs for the coffee item and the size modifier:

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
curl https://connect.squareupsandbox.com/v2/orders \
  -X POST \
  -H 'Square-Version: 2020-11-18' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "UNIQUE_ID",
    "order": {
      "line_items": [
        {
          "catalog_object_id": "COFFEE_ITEM_ID",
          "modifiers": [
            {
              "catalog_object_id": "SMALL_MODIFIER_ID"
            }
          ]
        },
        {
          "catalog_object_id": "COOKIE_ITEM_ID",
          "modifiers": [
            {
              "catalog_object_id": "CHOCOLATE_MODIFIER_ID"
            }
          ]
        }
      ]
    }
  }'

Referencing catalog IDs enables you to pull seller-defined data from Square-defined details into your order, such as an item name and price. For more information, see Create Orders.

Add fulfillment information to create a pickup order Permalink Get a link to this section

Next, your order-ahead application adds a fulfillment object to define and track the fulfillment status and details. The fulfillment type is defined as PICKUP because the customer has chosen to pick up the order at the location.

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
  • 39
  • 40
  • 41
curl https://connect.squareupsandbox.com/v2/orders \
  -X POST \
  -H 'Square-Version: 2020-11-18' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "UNIQUE_ID",
    "order": {
      "line_items": [
        {
          "catalog_object_id": "COFFEE_ITEM_ID",
          "modifiers": [
            {
              "catalog_object_id": "SMALL_MODIFIER_ID"
            }
          ]
        },
        {
          "catalog_object_id": "COOKIE_ITEM_ID",
          "modifiers": [
            {
              "catalog_object_id": "CHOCOLATE_MODIFIER_ID"
            }
          ]
        }
      ],
      "fulfillments": [
        {
          "type": "PICKUP",
          "status": "PROPOSED",
          "pickup_details": {
            "recipient": {
              "customer_id": "CUSTOMER_ID",
              "display_name": "Jaiden Urie"
            },
            "pickup_at": "TIMESTAMP"
          }
        }
      ]
    }
  }'

As this order moves through fulfillment states, the Orders API automatically updates the status field.

For more information about creating fulfillment orders, see Create Orders.

Apply a tax and discount Permalink Get a link to this section

Before paying for the order, the customer supplies a coupon for a discount on the cookie. You also need to apply a state sales tax before checkout. You have both the tax and discount defined in your catalog.

The order-ahead application applies the tax and discount to the order by populating the order-level taxes and discounts fields with references to the catalog object IDs. The scope of the tax is set to ORDER so it applies to the entire order. The discount scope is set to LINE_ITEM and applies only to the cookie 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
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
  • 36
  • 37
  • 38
  • 39
  • 40
  • 41
  • 42
  • 43
  • 44
  • 45
  • 46
  • 47
  • 48
  • 49
  • 50
  • 51
  • 52
  • 53
  • 54
  • 55
  • 56
  • 57
  • 58
  • 59
  • 60
curl https://connect.squareupsandbox.com/v2/orders \
  -X POST \
  -H 'Square-Version: 2020-11-18' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "UNIQUE_ID",
    "order": {
      "line_items": [
        {
          "catalog_object_id": "COFFEE_ITEM_CATALOG_ID",
          "modifiers": [
            {
              "catalog_object_id": "SMALL_MODIFIER_CATALOG_ID"
            }
          ]
        },
        {
          "catalog_object_id": "COOKIE_ITEM_CATALOG_ID",
          "modifiers": [
            {
              "catalog_object_id": "CHOCOLATE_MODIFIER_CATALOG_ID"
            }
          ],
          "applied_discounts": [
            {
              "uid": "COOKIE_DISCOUNT",
              "discount_uid": "COOKIE_DISCOUNT_ID"
            }
          ]
        }
      ],
      "fulfillments": [
        {
          "type": "PICKUP",
          "status": "PROPOSED",
          "pickup_details": {
            "recipient": {
              "customer_id": "CUSTOMER_ID",
              "display_name": "Jaiden Urie"
            },
            "pickup_at": "TIMESTAMP"
          }
        }
      ],
      "taxes": [
        {
          "catalog_object_id": "STATE_SALES_TAX",
          "scope": "ORDER"
        }
      ],
      "discounts": [
        {
          "uid": "COOKIE_DISCOUNT_ID",
          "catalog_object_id": "COOKIE_DISCOUNT_CATALOG_ID",
          "scope": "LINE_ITEM"
        }
      ]
    }
  }'

For more information about applying taxes and discounts, see Create Orders.

Pay for the order Permalink Get a link to this section

The Orders API automatically calculates the order total including taxes and discounts. The order-ahead application then processes a payment for the order.

The order-ahead application creates a payment object using the Payments API and references the order ID:

Create Payment
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
curl https://connect.squareupsandbox.com/v2/payments \
  -X POST \
  -H 'Square-Version: 2020-11-18' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "RANDOM_STRING",
    "amount_money": {
      "amount": 200,
      "currency": "USD"
    },
    "source_id": "PAYMENT_SOURCE_ID",
    "reference_id": "123456",
    "order_id": "ORDER_ID"
  }'

Close the order Permalink Get a link to this section

When the order is paid for, it appears in the Square Point of Sale application, where it can print a receipt if the seller has configured it to do so.

The CoffeeCool staff then marks the order as in-progress on the Order Manager in the Point of Sale application and begins to prepare the coffee. This updates the fulfillment state in the order, so the application can show the customer that the order is in progress.

When the customer picks up the coffee, the CoffeeCool staff can mark the order as fulfilled. If CoffeeCool is tracking inventory for these catalog items, the stock is automatically updated.

Related topics Permalink Get a link to this section