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:

📘

NOTE

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

Merchant-level REST API endpoints

1. 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

1.1 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

Response parameters

1.2 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

Response parameters

Order-level REST API endpoints

1. 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.

2. 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

Response parameters

3. 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

Response parameters

4. 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

Response parameters