Applies to: Orders API | Catalog API
Learn how the Orders API can power an order-ahead application.
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're 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 when the customer arrives.
Your order-ahead application can use the Orders API to:
- 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.
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 create an order for your customer. The following example references the catalog object IDs for the coffee item and the size modifier:
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 the order
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.
As this order moves through fulfillment states, the Orders API automatically updates the status field.
For more information about creating fulfillment orders, see Create a draft order.
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.
For more information about applying taxes and discounts, see Apply Taxes and Discounts.
The Orders API automatically calculates the order total including taxes and discounts. The order-ahead application then processes a payment for the order. After the order is paid, the stock is automatically updated.
The order-ahead application creates a Payment object using the Payments API and references the order ID.
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.