Tips API: Sample Use Cases and Flows

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

Add a tip to an order

Your app could allow business owners to add a customer tip for their staff to an eCommerce order.

To add a tip to an order:

1. Use Search Orders 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 Get Tip By Order ID 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 Query Tip Settings. 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 Preview Tip. 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 Set Tip On Order. Pass the order ID and the complete tip object from the previous step.

Manage a tip's distributions

Your app can let business owners adjust a staff member's share and add a distribution for another staff.

To adjust tip distributions:

1. Use Search Orders 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 Get Tip By Order ID 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 List Tippable Staff 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 Set Tip On Order to update the tip. Pass the adjusted, the new and all unchanged distributions.

Create a tip dashboard

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

To create a tip dashboard:

1. Call List Tippable Staff 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 Search Orders and filter by your desired time range. Save the IDs of the returned orders.
4. Call Query Tip Distributions, filtering by staff.id and the list of order IDs. Be sure to save the orderId for each distribution.
5. Optional: Use Sum Distribution Amounts 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 Get Order to display the corresponding order details, such as line items.

Manage a tip in your custom checkout

Your app can allow customers to add or update a tip as when you're using custom checkout. Keep in mind that Wix Tips allows customers to manage tips out-of-the-box, when the business is using the standard eCommerce checkout.

To manage a tip in your custom checkout:

1. Use Get Checkout and save the purchaseFlowId.
2. Use Query Tip Settings to confirm that customers are allowed to tip by checking allowCustomerTip and save the tip choice presets.
3. Call Get Tip Choice and provide the saved purchaseFlowId to check if the customer has already chosen a tip.
4. Based on the customer's selection, use Update Tip Choice to set or update the tip amount.
5. Once the customer completes the checkout, use Update Checkout to recalculate the checkout details. This automatically applies an additionalFee associated with the tip choice to the relevant eCommerce order.
6. Complete the checkout flow with the updated tip information using Create Order.