Tips API: Sample Use Cases and Flows

This article shares some possible use cases you could support, as well as a sample flow that supports each use case. This can be a helpful jumping off point for your planning.

Add a tip to an order

You could add a customer tip for the staff to an eCommerce order.

To add a tip to an order:

1. Use searchOrders() to identify unpaid orders. Provide { "paymentStatus": { "$in": ["NOT_PAID", "PARTIALLY_PAID"]}} in the filter. Save the returned order IDs, included line items, priceSummary.subTotal.formattedAmount, and all additional details that you want to display to the business owners later in the flow.
2. Check which of the retrieved orders doesn't include a tip by calling getTipByOrderID for each of them. If an order has no tip, the call fails with a TIP_NOT_FOUND error.
3. Display a list of all orders without tip to the business owners and let them choose the order for which order they want to add a tip. Save the relevant order ID.
4. Retrieve the relevant tip settings with queryTipSettings(). For example, you could use the default setting or filter by paymentTerminalId.
5. Display the tip settings presets and the order's priceSummary.subTotal.formattedAmount to the business owner. Save the business owner's tip choice.
6. Call previewTip(). Provide price for all the order's line items and save the returned tip.
7. Apply the tip including its distributions to the eCommerce order with setTipOnOrder(). Pass the order ID and the complete tip object from the previous step.

Manage a tip's distributions

You could let business owners adjust a staff member's share and add a distribution for another staff.

To adjust tip distributions:

1. Use searchOrders() to identify unpaid orders. Provide { "paymentStatus": { "$in": ["NOT_PAID", "PARTIALLY_PAID"]}} in the filter. Save the returned order IDs, included line items, priceSummary.subTotal.formattedAmount, and all additional details that you want to display to the business owners later in the flow.
2. Check which of the retrieved orders includes a tip by calling getTipByOrderID for each of them. If an order has a tip, the relevant tip is returned. If an order has no tip, the call fails with a TIP_NOT_FOUND error. Save all returned tip objects including their distributions.
3. Display a list of all orders with tip to the business owners and let them choose the order for which order they want to adjust the distributions. Save the relevant order ID.
4. Use listTippableStaff() to retrieve a list of all staff who are eligible to receive tips.
5. Display information about all staff who is eligible to receive a share of the tip to the business owners and let them choose who also receives a share of the tip. Save the relevant staff.id and the distribution amount they receive.
6. Call setTipOnOrder() to update the tip. Pass the adjusted, the new and all unchanged distributions.

Create a tip dashboard

You could display a dashboard to the business owners that allows them to manage tips by staff member.

To create a tip dashboard:

1. Call listTippableStaff() to retrieve all staff eligible to receive tips. Display the list to the business owners. When a business owner clicks on a specific staff member to view details, save that staff member's staff.id.
2. Optional: Allow the business owner to set a time range to retrieve tip details for that period.
3. Use searchOrders() and filter by your desired time range. Save the IDs of the returned orders.
4. Call queryTipDistributions(), filtering by staff.id and the list of order IDs. Be sure to save the orderId for each distribution.
5. Optional: Use sumDistributionAmounts() with the same filter as in the previous step to calculate the total tip amount for the selected staff member.
   Alternatively, you can calculate the total amount on your servers.
6. Display all tip distributions and the total tip amount for the staff member to the business owners.
7. When the business owner clicks on a specific distribution, use getOrder to display the corresponding order details, such as line items.