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:

  • The site or project owner must install either the Wix Restaurants Orders app or the Wix Restaurants Orders (New) app.

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.
Did this help?

Setup

@wix/restaurants

To use the ServiceFees API, install the @wix/restaurants package using npm or Yarn:

Copy

or

Copy

Then import { serviceFees } from @wix/restaurants:

Copy
Did this help?

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

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.

Did this help?

bulkCreateRules( )

Developer Preview

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.

Authentication
  • When developing websites or building an app with Blocks, this method may require elevated permissions, depending on the identity of the user calling it and the calling user’s permissions.
  • When building apps without Blocks or for headless projects, you can only call this method directly when authenticated as a Wix app or Wix user identity. When authenticated as a different identity, you can call this method using elevation.
  • Elevation permits users to call methods they typically cannot access. Therefore, you should only use it intentionally and securely.
Permissions
Manage Restaurants - all permissions
Learn more about app permissions.
Method Declaration
Copy
Method Parameters
rulesArray<Rule>Required

Rules to create.

optionsBulkCreateRulesOptions
Returns
Return Type:Promise<BulkCreateRulesResponse>
JavaScript
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

bulkDeleteRules( )

Developer Preview

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.

Authentication
  • When developing websites or building an app with Blocks, this method may require elevated permissions, depending on the identity of the user calling it and the calling user’s permissions.
  • When building apps without Blocks or for headless projects, you can only call this method directly when authenticated as a Wix app or Wix user identity. When authenticated as a different identity, you can call this method using elevation.
  • Elevation permits users to call methods they typically cannot access. Therefore, you should only use it intentionally and securely.
Permissions
Manage Restaurants - all permissions
Learn more about app permissions.
Method Declaration
Copy
Method Parameters
ruleIdsArray<string>Required

IDs of the rules to delete.

Returns
Return Type:Promise<BulkDeleteRulesResponse>
JavaScript
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

bulkUpdateRules( )

Developer Preview

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.

Authentication
  • When developing websites or building an app with Blocks, this method may require elevated permissions, depending on the identity of the user calling it and the calling user’s permissions.
  • When building apps without Blocks or for headless projects, you can only call this method directly when authenticated as a Wix app or Wix user identity. When authenticated as a different identity, you can call this method using elevation.
  • Elevation permits users to call methods they typically cannot access. Therefore, you should only use it intentionally and securely.
Permissions
Manage Restaurants - all permissions
Learn more about app permissions.
Method Declaration
Copy
Method Parameters
rulesArray<MaskedRule>Required

Masked rules to update.

optionsBulkUpdateRulesOptions
Returns
Return Type:Promise<BulkUpdateRulesResponse>
JavaScript
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

calculateServiceFees( )

Developer Preview

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.

Permissions
Manage Restaurants - all permissions
Learn more about app permissions.
Method Declaration
Copy
Method Parameters
orderOrderRequired

Order information needed to evaluate the rules and calculate the relevant fees.

optionsCalculateServiceFeesOptions
Returns
Return Type:Promise<CalculateServiceFeesResponse>
JavaScript
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

createRule( )

Developer Preview

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.

Authentication
  • When developing websites or building an app with Blocks, this method may require elevated permissions, depending on the identity of the user calling it and the calling user’s permissions.
  • When building apps without Blocks or for headless projects, you can only call this method directly when authenticated as a Wix app or Wix user identity. When authenticated as a different identity, you can call this method using elevation.
  • Elevation permits users to call methods they typically cannot access. Therefore, you should only use it intentionally and securely.
Permissions
Manage Restaurants - all permissions
Learn more about app permissions.
Method Declaration
Copy
Method Parameters
ruleRuleRequired

Rule to create.

Returns
Return Type:Promise<Rule>
JavaScript
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?