About the Tips API

The Tips API allows app developers to manage tips for eCommerce orders. You can also preview tips and how they would be distributed to staff members before an order is created.

With the Tips API, your app can:

• Preview tips
• Apply or remove tips from eCommerce orders
• Retrieve tips and their distributions

See also:

• Tip Settings API
• Tippable Staff API

Before you begin

It's important to note the following points before starting to code:

• Ensure that the site owner has installed Wix Tips on their site.
• Each tip is applied to an eCommerce order as a single additionalFee. The tip's ID is stored in the additionalFee.code field of the order.
• You can charge customers in separate transactions for individual tip distributions. After a tip distribution has an associated transaction, its amount can't be modified in the future.
• Currently, only Bookings staff members and site collaborators can receive tip distributions.

Sample Use Cases

• Add a tip to an order.
• Manage a tip's distributions.
• Create a tip dashboard.

Terminology

• Tip: Details the tip amount, how it’s distributed among staff, and the associated order’s line item subtotal.
• Tip distribution: How the total tip is divided among staff. The business receives the undistributed tip amount.
• Tip settings: Configure how tips are previewed, applied, and distributed. Refer to the Tip Settings API for more information.
• Staff: Team members who receive a portion of the tip. Currently, only Bookings staff members and site collaborators can receive tip distributions. Refer to the Tippable Staff API for more information.
• eCommerce order: Contains information about purchased items, price and tax summaries, shipping, and billing details, any applied discounts, and the status of payment and fulfillment. Refer to the eCommerce Orders API for more information.

For a comprehensive glossary of Wix Bookings terms, see Terminology.

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.