Orders API

Order-Ahead App Usecase

Backend
Orders API

This document will walk you through an example of how the Orders API can power an order-ahead app.

Did you know?

We also offer an order-ahead sample application that you can download and configure with your Square credentials. See the Order-Ahead Sample App.

Suppose you are building an order-ahead app for CoffeeCool, a coffee shop that uses Square for its payments processing. CoffeeCool customers can download the app 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 app 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, then capture and associate a payment with the Order.

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

Create an Order
Permalink Get a link to this section

The customer kicks off the process by ordering one small coffee and one chocolate chip cookie using your order-ahead app. The customer chooses to pay using the app and pick their order up at CoffeeCool’s location.

To track this, your app will call the CreateOrder endpoint to make an order for your customer. The example below references the catalog object IDs for the coffee item and the size modifier.

{
  "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 merchant-defined data from Square defined details into your order, such as item name and price. Read more about how to create an order.

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

Next, your order-ahead app will add a fulfillment object to also define and track fulfillment status and details. The fulfillment type is defined as “PICKUP” since the customer has chosen to pick up their order at the location.

{
  "idempotency_key": "UNIQUE_ID",
  "order": {
    "line_items": [
    ...
    ],
    "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 will automatically update the status field.

Read more about creating fulfillment 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 app 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 will apply to the entire order. The discount scope is set to LINE_ITEM and applies only to the cookie line item.

{
  "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": [
      ...
    ],
    "taxes": [
      {
        "catalog_object_id": "STATE_SALES_TAX",
        "scope": "ORDER"
      }
    ],
    "discounts": [
      {
        "uid": "COOKIE_DISCOUNT_ID",
        "catalog_object_id": "COOKIE_DISCOUNT_CATALOG_ID",
        "scope": "LINE_ITEM"
      }
    ]
  }
}' \

Read more about how to apply taxes and discounts

Pay for the order
Permalink Get a link to this section

The Orders API will automatically calculate the order total including taxes and discounts. Then, the order-ahead app will process a payment for the order.

The order-ahead app would create a payment object using the Payments API and reference the order ID.

{
    "idempotency_key": "RANDOM_STRING",
    "amount_money": {
      "amount": 200,
      "currency": "USD"
    },
    "source_id": "PAYMENT_SOURCE_ID",
    "reference_id": "123456",
}

Close the order
Permalink Get a link to this section

Once the order is paid for, it will appear in the Square Point of Sale app, where it may print a receipt for the staff if the seller has configured it to do so.

The CoffeeCool staff then marks the order as in-progress on the Order Manager in Point of Sale and begins to prepare the coffee. This will update the fulfillment state in the order, so the app can show the customer that their 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, their stock will be automatically deprecated.

Next Steps

Use the build guides below to integrate with the Orders API