Applies to: Orders API | Catalog API| Loyalty API | Payments API | Web Payments SDK
Learn how the Orders, Catalog, Payment API, and Web Payment SDK can power an order-ahead application.
Square offers an order-ahead sample application project that you can download, configure with your Square credentials, build, and run. For more information, see Order-Ahead Sample Application.
Suppose you're building an order-ahead application for a coffee shop that uses Square for its payment processing. Customers can visit the shop's browser page to order and pay for drinks ahead of time. This allows the staff to start preparing the customer's order and have it ready for pickup when the customer arrives.
Assuming the coffee shop has built a catalog with the Catalog API, your order-ahead application uses Square APIs to:
- Create an order for the customer using catalog items.
- Notify the seller through Order Manager in Square Point of Sale.
- Apply a tax and discount.
- Capture and associate a payment with the order.
- Track the order's fulfillment state and update the customer through the order-ahead application.
The buyer starts the process by opening a coffee shop menu page on their browser. The page is built with catalog items returned to your application by the SearchCatalogItems endpoint. To ensure that the SearchCatalogItems endpoint returns the coffee items to fill the coffee menu, these items should be grouped under the CatalogCategory that the shop created for coffee items. For more information about building a menu in a browser page, see Order-Ahead Sample Application.
The buyer orders one small coffee using the order-ahead application, pays using the application, and picks up the order at the coffee shop.
To facilitate this process, your application calls CreateOrder to create an order for the buyer. The following example references the catalog object IDs for the coffee item and the size modifier:
The following example request adds the coffee as a line item and asks for a catalog sales tax to be applied to the coffee:
Create order
Referencing catalog IDs enables you to pull seller-defined data from Square-defined details into your order, such as an item name and price. If inventory is tracked for catalog items, adding their IDs to an order lets Square update item inventory when the order is fulfilled. For more information, see Create Orders.
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.
The following example UpdateOrder request references the ID of the order that was created in the previous step. Because the Orders API supports sparse updates, your update request only needs to include the sub-resource that you're adding or changing in an order. In this case, the request is adding a Fulfillment resource to the order.
Update order
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 coffee. You have both the automatically applied tax and the discount defined in your catalog.
The order-ahead application applies the discount to the order by populating the order-level discounts field with references to the catalog object IDs. The discount scope is set to LINE_ITEM and applies only to the cookie line item.
The following example shows that a catalog discount is being added to the order and applied to the coffee line item. The OrderLineItemDiscount is added to the order and the OrderLineItem is updated to add the applied_discounts property that references the order discount.
Update order
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 accepts the buyer's payment card using the Web Payments SDK and then creates a Payment object using the Payments API and references the order ID.
Create payment
The seller who uses your application might have an active Square loyalty program and the buyer's purchase might give them new reward points. Retrieve the seller's loyalty program and, if their program is active, add the earned loyalty points to the buyer's loyalty account. All you need is the loyalty account ID and the order ID to add the points for the buyer. For more information, see Accumulate loyalty points from a purchase.
When the order is paid for, it appears in Square Point of Sale, where it can print a receipt if the seller has configured it to do so.
The coffee shop staff then marks the order as in-progress in Order Manager in Square Point of Sale 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 staff marks the order as fulfilled.