➤ (MSC Pilot) Multiple service charges overview

Help your merchants by updating your app to support multiple service charges. The MSC pilot documentation shows you how.

United States
Canada

🚧

Welcome to the multiple service charges pilot!

The multiple service charges (MSC) feature lets Clover merchants add upto three multiple service charges to an order, such as a large dining-party automatic gratuity, a special menu upsell fee, and a banquet event fee. Previously, only a single service charge was supported.

  • Starting in early Q2 2024, Clover will gradually deploy the multiple service charge (MSC) feature across the merchant base; all merchants will not receive immediate access to the feature. As we do this, you can use our APIs to see the list of service charges your merchants have configured and apply them to orders.
  • During the pilot, you are invited to test the feature with your app in the sandbox environment.
  • After the launch is complete, you will be required to use the new service charge endpoints to use any service charge features. The new endpoints use service charges as line items when applied to an order.

Pilot documentation

MSC developer documentation is not public during the pilot, so the topics do not appear in search results or in the left-navigation panel of this developer documentation portal. To help you navigate the MSC documentation during the pilot, use the quick links in the top-navigation menu on relevant MSC topics.

Multiple service charges functionality

The multiple service charges (MSC) feature lets merchants add up to three multiple percentage-based service charges, such as delivery fees or large group fees to orders. Key points for this feature are:

  • Only merchants can create, update, or delete service charges.
  • Initial release of MSC does not support fee-based service charges or taxable order fees.
  • Clover code base identifies multiple service charges as OrderFees.

Use service charges in your apps

As a Clover developer, note the following:

Your Clover apps can:

  • Add service charges associated with a merchant to an order.
  • Remove service charges from an order.
  • Get all service charges associated with a merchant.
  • Get a list of service charges associated with an order.

Your Clover apps cannot:

  • Create service charges for a merchant.
  • Update or delete service charges associated with a merchant.

Android SDK and data model changes

The Clover data model handles multiple service charges as order-level line items. Your app must filter out multiple service charge line items from regular, non-service charge line items. If multiple service charges are not filtered out, they appear with regular line items in the order details.

The Android SDK contains code snippets to help you filter out the multiple service charges from regular line items in an order. For more information, see Manage service charges for Android apps.

Terminology

Use to understand the terms associated with multiple service charges.

TermDescription
Line itemSingle item on an order.
OrderGoods and services purchased by a customer.
Order feeOrder-level extra fee, charge, or tax added to the cost of a good or service beyond the initially quoted price. This definition includes an order's service charge.
Order totalOrder total includes all taxes, order-level discounts, and order fees or service charges.
Service chargeLegacy implementation of order fees.
SubtotalOrder total before applying non-VAT taxes, order-level discounts, and service charges. The subtotal includes item modifications and discounts.