Configuring Fees

The fees feature in Carts API allows you to add, update, or remove additional fees beyond the resource price, such as gifting fees, platform fees, and service fees. These fees can be applied at various levels, including the cart, individual items, or fulfillment, providing flexibility in customizing the total cost structure. Optionally, the fees may be taxable.

Prerequisites

The following prerequisites must be completed sequentially to configure a fee.

1. Create a cart.
2. Create a fulfillment to apply the fulfillment fee.
3. Create an item to add the item fee.

Fee Initialization

You can apply fees at multiple levels, including the cart, individual items, or fulfillment. The fee resource maintains a consistent structure across all levels. Taxes on fees is controlled by the taxable attribute in the request payload, which defaults to true. This means fees are taxed unless specifically set to false.

The following code sample provides the structure of a fee object:

Click to expand the JSON example.

{
    "id": "188514cb-f36b-4835-a8b3-df75164325d7",
    "name": "cart v3 fees",
    "price": {
        "amount": 10
    },
    "taxable": true,
    "attributes": {
        "message": "gifting-fee"
    },
    "updatedAt": "2024-06-20T07:55:49.021Z",
    "createdAt": "2024-06-20T07:55:49.021Z"
} 

The resource is displayed as a collection of fees for the associated resource as multiple fees can be applied to a single resource.

The following code sample provides the structure of a fee object in a collection:

Click to expand the JSON example.

    "fees": {
        "total": 10,
        "collection": [
            {
                "id": "188514cb-f36b-4835-a8b3-df75164325d7",
                "name": "cart v3 fees",
                "price": {
                    "amount": 10
                },
                "taxable": true,
                "attributes": {
                    "message": "gifting-fee"
                },
                "updatedAt": "2024-06-20T07:55:49.021Z",
                "createdAt": "2024-06-20T07:55:49.021Z"
            }
        ]
    }

Examples

Adding shipping fees, including shipping fee tax

The following steps outline how a fulfillment fee is configured:

1. Create fulfillment fee.

   Click to expand the curl example.

   curl --location '{{modular_cart}}/carts/7d403833-8e0c-43f5-aded-72d6a2eaf062/fulfillments/65879f42-edfb-46de-bf57-77835dec3d60/fees' \
    --header 'Content-Type: application/json' \
    --header 'x-fabric-tenant-id:  {tenantId}' \
    --data '{
        "name": "Shipping fee",
        "price": {
            "amount": 10
        },
        "taxable": true,
        "attributes": {
            "displayMsg": "Shipping Off for orders over $100"
        }
    }'
   

2. Add tax for the fulfillment fee using the replace tax data endpoint.

   Click to expand the curl and JSON response examples

   curl --location --request PUT 'https://dev.cart.fabric.inc/beta/v3/modular/carts/7d403833-8e0c-43f5-aded-72d6a2eaf062/tax' \
    --header 'x-fabric-tenant-id:  {tenantId}' \
    --header 'Content-Type: application/json' \
    --data '{
        "fulfillments": [
            {
                "id": "65879f42-edfb-46de-bf57-77835dec3d60",
                "tax": [
                    {
                        "amount": 2,
                        "attributes": {
                            "rate": 1
                        }
                    }
                ],
                "fees": [
                    {
                        "id": "026b9bd1-2e96-4016-93a3-674da01aa29e",
                        "tax": [
                            {
                                "amount": 1,
                                "attributes": {
                                    "rate": 1
                                }
                            }
                        ]
                    }
                ]
            }
        ]
    }'
   

   Tax here includes fulfillment tax and fulfillment the fee tax as provided in the payload.

   Response:

    "price": {
        "total": 343,
        "subtotal": 310,
        "tax": 3,
        "fulfillments": 30,
        "discounts": 0,
        "fees": 110,
        "adjustments": 0
    }
   

Applying a gifting fee to items that are gift-wrapped

Use the create item fees endpoint to apply the gifting fees to the items that are gift wrapped. The following curl example provides how the request is structured when creating an item fee:

Click to expand the curl example.

curl --location '{{modular_cart_domain}}/carts/7d403833-8e0c-43f5-aded-72d6a2eaf062/items/806d6671-801d-4554-976d-0d38e525a852/fees' \
--header 'Content-Type: application/json' \
--header 'x-fabric-tenant-id:  {tenantId}' \
--data '{
    "name": "Gift wrap",
    "price": {
        "amount": 10
    },
    "taxable": false,
    "attributes": {
        "message": "Happy Birthday John Doe"
    }
}'

Adding a platform fee at the cart level

Use the create cart fees endpoint to add a platform fee at the cart level. The following curl example provides how the request is structured when creating fee at the cart level:

Click to expand the curl example.

    curl --location '{{modular_cart_domain}}/carts/7d403833-8e0c-43f5-aded-72d6a2eaf062/fees' \
    --header 'Content-Type: application/json' \
    --header 'x-fabric-tenant-id:  {tenantId}' \
    --data '{
        "name": "Platform-fee",
        "price": {
            "amount": 100
        },
        "taxable": true,
        "attributes": {
            "reason": "added as an example"
        }
    }'