(MSC Pilot) Manage service charges for Web apps

Learn how to use the MSC REST API to manage multiple service charges (MSC) for Web apps.

North America—United States and Canada

This topic describes how to use the MSC REST API to manage multiple service charges (MSC) for Web apps. The endpoints are organized into two sections for merchant-level and order-level endpoints:

REST APIs to manage service chargesDescription
Merchant-level REST API endpointsUse to:

- Get a list of all service charges
- Get details for single service charge
Order-level REST API endpointsUse to:

- Add one or more service charges associated with a merchant to a given order
- Remove one or more service charges associated with a merchant from an order
- Get a single service charge associated with an order
- Get the list of service charges associated with a given ord

📘

NOTE

To access the complete, testable MSC REST API reference endpoints, see the MSC REST API Index.


Merchant-level REST API endpoints

Get service charges associated with a merchant

Use the v3/merchants/{mId}/order_fees endpoint to:

  • get a list of all service charges
  • get a single charge associated with a merchant

Get a list of all service charges

  1. Send a GET request to v3/merchants/{mId}/order_fees.
  2. Enter the merchant identifier (mId) in the request.
curl --request GET  \
--url 'https://sandbox.dev.clover.com/v3/merchants/{mId}/order_fees' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer {access_token}'
{
    "elements": [
        {
            "id": "DPDDK16CGET6E",
            "name": "StaffMed",
            "percentage": 1000,
            "createdTime": 1705681517000,
            "modifiedTime": 1705681517000
        },
        {
            "id": "7QC732JVN2DXP",
            "name": "Delivery",
            "percentage": 40000,
            "createdTime": 1705029883000,
            "modifiedTime": 1705029883000,
            "type": ""
        },
        {
            "id": "HHBECXV21DRQ4",
            "name": "LargeParty",
            "percentage": 30000,
            "createdTime": 1704480354000,
            "modifiedTime": 1705360002000,
            "type": ""
        }
    ],
    "href": "/v3/merchants/HDHEQBN4ARCF5/order_fees"
}

Request parameters

PropertyTypeDescriptionRequired/ Optional
mIdstringMerchant identifier.Required
Query filterstringFilter fields:

- modifiedTime
- amount
- serviceChargeUuid
- type
- percentage
- name
- createdTime
- id
- deletedTime
Required

Response parameters

PropertyTypeDescription
idstringService charge identifier.
namestringService charge name.
percentageintegerService charge amount in percent.
createdTimeintegerTimestamp when the order fee was created.
modifiedTimeintegerTimestamp when the service charge was last modified.

Get details for a single service charge

  1. Send a GET request to v3/merchants/{mId}/order_fees/{orderFeeId}.
  2. Enter the merchant identifier (mId) and the order fee identifier (orderFeeId) in the request.
curl --request GET  \
--url 'https://sandbox.dev.clover.com/v3/merchants/{mId}/order_fees/{orderFeeId}' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer {access_token}'
{
    "id": "HHBECXV21DRQ4",
    "name": "LargeParty",
    "percentage": 30000,
    "createdTime": 1704480354000,
    "modifiedTime": 1705360002000,
    "type": ""
}

Request parameters

PropertyTypeDescriptionRequired/ Optional
mIdstringMerchant identifier.Required
orderFeeIdstringOrder fee identifier.Required

Response parameters

PropertyTypeDescription
idstringOrder fee identifier.
namestringService charge (order fee) name.
percentageintegerService charge amount in percent.
createdTimeintegerTime when the service charge was recorded on the server.
modifiedTimeintegerTime when the service charge was modified on the server.

Order-level REST API endpoints

Use the isOrderFee object flag to control where service charges appear

At the API level, service charges are handled as line items (of service charge type). However, in your app interface, service charges should not display with the line items—they should be listed after the subtotal because taxes are not applied to service fees.

You can control the placement of service charges in your app interface using the isOrderFee object flag.

  • For regular (non-service charge) lineItems the LineItem object flag is set to isOrderFee: false.
  • When using orderFeeLineItem , set the LineItem object flag to isOrderFee: true.

Make sure the response for the service charges found indicates isOrderFee: true.
For example:

{
"id": "S4XK3VG1RXK1C",
"orderRef": {
"id": "P6JVBY8V8KFEC"
},
"name": "test order fee 2",
"price": 0,
"note": "test note",
"printed": false,
"createdTime": 1709732377000,
"orderClientCreatedTime": 1709732166000,
"exchanged": false,
"refunded": false,
"isRevenue": false,
"percentage": 190000,
"orderFee": {
"id": "7M8463224GJ5R"
},
"isOrderFee": true

Make service charges display in the correct location

  1. For the regular order line items, filter out service charge line items using the isOrderFee : false object flag.
  2. For the post-subtotal item list, include service charges using theisOrderFee : true object flag.
illustration of receipts with service charges

Illustration of correct and incorrect placement of service charges in an order receipt

Get a list of service charges associated with an order

  1. Send a GET request to the v3/merchants/{mId}/orders/{orderId}/order_fee_line_items endpoint.
  2. Enter the merchant identifier (mId) and the order identifier (orderId) in the request.
curl --request GET  \
--url 'https://sandbox.dev.clover.com/v3/merchants/{mId}/orders/{orderId}/order_fee_line_items' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer {access_token}'
{
"elements": [
{
"id": "S4XK3VG1RXK1C",
"orderRef": {
"id": "P6JVBY8V8KFEC"
},
"name": "order fee",
"price": 10,
"note": "test note",
"printed": false,
"createdTime": 1709732377000,
"orderClientCreatedTime": 1709732166000,
"exchanged": false,
"refunded": false,
"isRevenue": false,
"percentage": 190000,
"orderFee": {
"id": "7M8463224GJ5R"
},
"isOrderFee": true
}
],
"href": "http://sandbox.dev.clover.com/v3/merchants/{mid}/orders/{orderId}/order_fee_line_items?limit=100"
}

Request parameters

PropertyTypeDescriptionRequired/ Optional
mIdstringMerchant identifier.Required
orderIdstringOrder identifier.Required
Expand querystringExpandable fields:

- employee
- order type
- payments
Optional

Response parameters

ParameterTypeDescription
idstringMerchant identifier.
orderRefidstringReference identifier of the order fee with which the service charge is associated.
namestringName of the order fee.
priceintegerOrder fee price.
notestringComments or information, if any.
createdTimeintegerTime when the service charge was recorded on the server.
orderClientCreatedTimeintegerOrder client-created time for user data of line item.
percentageintegerService charge amount in percent.
orderFeeidstringOrder fee identifier.

Add service charges associated with a merchant to an order

📘

NOTE

No tax on order fees—Since MSC order fees are treated as line items, and order fees are non-taxed items, you must mark each order fee line item as a 0% No Tax Applied tax.

For more information, see Tax report example 5: zero tax.

To add one or more service charges associated with a merchant to an order:

  1. Send a POST request to /v3/merchants/{mId}/orders/{orderId}/order_fee_line_items.
  2. Enter the merchant identifier (mId) and order identifier (orderId) in the request.
curl --request POST  \
--url 'https://sandbox.dev.clover.com/v3/merchants/{mId}/orders/{orderId}/order_fee_line_items'/
--header 'content-type: application/json' \
--header 'Authorization: Bearer {access_token}'
{
"id": "S4XK3VG1RXK1C",
"orderRef": {
"id": "P6JVBY8V8KFEC"
},
"name": "test order fee 2",
"price": 0,
"note": "test note",
"printed": false,
"createdTime": 1709732377000,
"orderClientCreatedTime": 1709732166000,
"exchanged": false,
"refunded": false,
"isRevenue": false,
"percentage": 190000,
"orderFee": {
"id": "7M8463224GJ5R"
},
"isOrderFee": true
}
}

Request parameters

ParameterDescriptionRequired/ Optional
mIdMerchant identifier.Required
orderIdOrder identifier.Required

Response parameters

ParameterTypeDescription
idstringMerchant identifier.
orderRefidstringReference identifier of the order fee with which the service charge is associated
namestringName of the order fee.
priceintegerOrder fee price.
notestringComments or information, if any.
createdTimeintegerTime when the service charge was recorded on the server.
orderClientCreatedTimeintegerOrder client-created time for user data of line item.
percentageintegerService charge amount in percent.
orderFeeidstringOrder fee identifier.

Remove service charges associated with a merchant from an order

To remove one or more service charges associated with a merchant from an order:

  1. Send a DELETE request to /v3/merchants/{mId}/orders/{orderId}/order_fee_line_items/{orderFeeLineItemId}.
  2. Enter the merchant identifier (mId), order identifier (orderId) and the order fee line item identifier (orderFeeLineitemId) in the request.
curl --request DELETE  \
--url 'https://sandbox.dev.clover.com/v3/merchants/{mId}/orders/{orderId}/order_fee_line_items/{orderFeeLineItemId}' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer {access_token}'

Request parameters

ParameterTypeDescriptionRequired/ Optional
mIdstringMerchant identifier.Required
orderIdstringOrder identifier.Required
orderFeeLineItemIdstringOrder fee line item identifier.Required

Response parameters

MessageTypeDescription
200stringSuccessful response. Service charge is deleted.