Introduction
The Service Fees API allows you to manage your service fee rules and apply them to orders.
With the Service Fees API, you can:
- Create and manage rules for service fees.
- Implement custom pricing and fee structures for restaurant orders.
- Adjust service fees automatically based on certain rules or conditions.
Before you begin
It's important to note the following point before starting to code:
- This API requires Wix Restaurants Orders (New) to be installed on the site calling the API. If you are using this API in an app, add Wix Restaurants Orders (New) as an app dependency.
Terminology
- Order: Information about an order that is placed by a customer. It contains necessary information to calculate service fees. The order has not yet been placed, it is in the pre-checkout stage.
- Condition: Evaluates a specific field in the order.
- Condition Tree: Contains two conditions and an operator.
- Rule: Defines the fee that is applied when specific conditions (also defined by the rule) are met.
Setup
To use the ServiceFeesCalculate API, install the @wix/restaurants
package using npm or Yarn:
1npm install @wix/restaurants
or
1yarn add @wix/restaurants
Then import { serviceFeesCalculate }
from @wix/restaurants
:
1import { serviceFeesCalculate } from '@wix/restaurants'
Constructing a Rule
A rule has two main parts: conditions and a fee. When calculateServiceFees()
is called, it assesses each rule in relation to the specified order. When a rule is assessed, if the conditions are met, the fee is included in the API's response.
Conditions
Conditions can be either a single condition or a condition tree.
A single condition evaluates a specific field in the order. For example, it could check if the value of the field is greater than a certain number.
A condition tree contains two conditions and an operator. The conditions can each be either a single condition or a condition tree. There are two operator values:
"AND"
: Both conditions must be met for the condition tree to be considered met."OR"
: At least one of the conditions must be met for the condition tree to be considered met.
Condition tree example
Conditions
For the service fee to be applied, we would need to satisfy these conditions:
- The price subtotal is greater than
50
AND - Either:
- Delivery type is
"DELIVERY"
OR - Order is made in the mobile app
- Delivery type is
Example: Conditions are met
We have the following values:
- Subtotal is
70
- Delivery type is
"DELIVERY"
- Order is
"WEBSITE"
In this case, the conditions are met, because the subtotal is greater than 50
and the delivery type is "DELIVERY"
. It doesn't matter that the platform isn't "MOBILE_APP"
because we only need that OR delivery type to be "DELIVERY"
.
Example: Conditions are not met
We have the following values:
- Subtotal is
30
- Delivery type is
"DELIVERY"
- Order is
"MOBILE_APP"
In this case, the conditions are not met, because even though the delivery type is "DELIVERY"
and the platform is "MOBILE_APP"
, the subtotal is not greater than 50
.
Fee
A fee is either a fixed amount or a percentage of the order's subtotal. It can also include tax.
If the conditions are met, the fee is calculated and applied when calculateServiceFees()
is called.
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
The bulkCreateRules()
function returns a Promise that resolves to the created rules.
To create only one rule, use the createRule()
function.
function bulkCreateRules(rules: Array<Rule>, options: BulkCreateRulesOptions): Promise<BulkCreateRulesResponse>
Rules to create.
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
The bulkDeleteRules()
function returns a Promise that resolves to the deleted rules.
To delete only one rule, use the deleteRule()
function.
function bulkDeleteRules(ruleIds: Array<string>): Promise<BulkDeleteRulesResponse>
IDs of the rules to delete.
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
The bulkUpdateRules()
function returns a Promise that resolves to the updated rules.
Each time the task is updated, revision
increments by 1. The existing revision
must be included when updating the task. This ensures you're working with the latest task and prevents unintended overwrites.
To update only one rule, use the updateRule()
function.
function bulkUpdateRules(rules: Array<MaskedRule>, options: BulkUpdateRulesOptions): Promise<BulkUpdateRulesResponse>
Masked rules to update.
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
The calculateServiceFees()
function returns a Promise that resolves to an array containing the calculated fees.
The specified order information is evaluated against all rules created for the site. If the rule conditions are met, the service fee set in the rule is applied. Otherwise, no service fee is added.
function calculateServiceFees(order: Order, options: CalculateServiceFeesOptions): Promise<CalculateServiceFeesResponse>
Order information needed to evaluate the rules and calculate the relevant fees.
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
The createRule()
function returns a Promise that resolves to the created rule.
To create multiple rules at once, use the bulkCreateRules()
function.
function createRule(rule: Rule): Promise<Rule>
Rule to create.
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
The deleteRule()
function returns a Promise that resolves to void.
To delete multiple rules at once, use the bulkDeleteRules()
function.
function deleteRule(ruleId: string): Promise<void>
ID of the rule to delete.
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
The createRule()
function returns a Promise that resolves to the retrieved rule.
function getRule(ruleId: string): Promise<Rule>
ID of the rule to retrieve.
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
The listRules()
function returns a Promise that resolves to an array of the retrieved rules.
You can filter by location or app that the rules are associated with.
function listRules(options: ListRulesOptions): Promise<ListRulesResponse>
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Creates a query to retrieve a list of rules.
The queryRules()
function builds a query to retrieve a list of up to 1,000 rules and returns a RulesQueryBuilder
object.
The returned object contains the query definition which is typically used to run the query using the find()
function.
You can refine the query by chaining RulesQueryBuilder
functions onto the query. RulesQueryBuilder
functions enable you to sort, filter, and control the results that queryRules()
returns. The functions that are chained to queryRules()
are applied in the order they are called.
queryRules()
runs with the following RulesQueryBuilder
defaults that you can override:
skip
:0
limit
:50
The following QueryRulesBuilder
functions are supported for the queryRules()
function. For a full description of the Rules object, see the object returned for the items
property in RulesQueryResult
.
PROPERTY | SUPPORTED FILTERS & SORTING |
---|---|
_id | eq() ,ne() ,exists() ,in() ,hasSome() ,startsWith() ,ascending() ,descending() |
function queryRules(): RulesQueryBuilder
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
The updateRule()
function returns a Promise that resolves to the updated rule.
Each time the task is updated, revision
increments by 1. The existing revision
must be included when updating the task. This ensures you're working with the latest task and prevents unintended overwrites.
To update multiple rules at once, use the bulkUpdateRules()
function.
function updateRule(_id: string, rule: UpdateRule): Promise<Rule>
Rule ID.