Configuring Taxes

This feature in Carts API allows users to levy taxes on resources such as items, fulfillment, and fees. Fees are optionally taxable.

Prerequisites

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

1. Create a cart.
2. Create a fulfillment to add fulfillment taxes.
3. Create an item to add item taxes.
4. Create either item, fulfillment, or cart fees to add fee taxes.

Tax Initialization

You can add taxes on the cart, cart fees, cart fulfillment, items, item fees, item fulfillment, and fulfillment fees through a single request. To ensure that fees are subject to tax, the fees should be marked as taxable.

You can apply taxes at multiple levels, including individual items, fulfillment, or fees. The tax resource maintains a consistent structure across all levels.

The following code sample provides an example of tax object structure in request payload:

Tax resource

Click to expand the JSON example.

    {
        "amount": 4.0,
        "attributes": {
            "rate": 5,
            "message": "5% tax"
        }
    }

For accurate tax calculation, address information is required. While items, fulfillment, and their fees already have associated addresses from the fulfillment information, the cart fee requires a separate field for the address to be provided.

The following code sample provides an example tax object structure in a request payload with the destinationAddress and originAddress:

Tax fee resource with addresses

Click to expand the JSON example.

    {
        "amount": 4.0,
        "attributes": {
            "rate": 5,
            "message": "5% tax"
        },
        "taxDetails":{
        "destinationAddress": "{{destinationAddressId}}",
        "originAddress": "{{originAddressId}}"
        }
    }

Examples

Applying sales taxes on items and fulfillments

Use the replace tax data endpoint to create sales taxes on items and fulfillments as in the following example:

Click to expand the curl example.

curl --location --request PUT '{{modular_cart_domain}}/carts/ba0e93f5-e47f-4b0d-bac8-6233b67ef65f/tax' \
--header 'x-fabric-tenant-id:  {tenantId}' \
--header 'Content-Type: application/json' \
--header 'Authorization: {authToken}' \
--data '{
    "items": [
        {
            "id": "c0f1c36d-35e6-4098-94a7-3b92fba089d7",
            "tax": [
                {
                    "amount": 10,
                    "attributes": {
                        "rate": 8
                    }
                },
                {
                    "amount": 2,
                    "attributes": {
                        "rate": 3
                    }
                }
            ]    
        }
    ],
    "fulfillments": [
        {
            "id": "a7f51053-6fbd-42a6-8fbc-303bfc16c13f",
            "tax": [
                {
                    "amount": 10,
                    "attributes": {
                        "rate": 1
                    }
                },
                {
                    "amount": 4,
                    "attributes": {
                        "VAT": "enabled"
                    }
                }
            ]
        }
    ]
}'

Applying sales taxes on items, fulfillments and the service charge

Use the replace tax data endpoint to create sales taxes on items and fulfillments, and service charge which are also taxable as in the following example:

Click to expand the JSON and curl example.

Ensure that fulfillment fees are set to taxable.

{
    "id": "d4e9f8dc-c0ae-4ef3-be8b-bd23579a4dd3",  // feeId
    "name": "fulfillment-fee",
    "price": {
        "amount": 5.0
    },
    "taxable": true,
    "attributes": {
        "message": "Shipping fee"
    },
    "tax": {
        "total": 0,
        "collection": []
    },
    "updatedAt": "2024-09-02T15:21:19.874Z",
    "createdAt": "2024-09-02T15:21:19.874Z"
}

Add tax to the cart curl.

curl --location --request PUT 'https://dev.cart.fabric.inc/beta/v3/modular/carts/ba0e93f5-e47f-4b0d-bac8-6233b67ef65f/tax' \
--header 'x-fabric-tenant-id:  {tenantId}' \
--header 'Content-Type: application/json' \
--header 'Authorization: {authToken}' \
--data '{
    "items": [
        {
            "id": "2c51a3da-e3ff-40ef-bb5b-3e191892293c",
            "tax": [
                {
                    "amount": 10,
                    "attributes": {
                        "rate": 8
                    }
                },
                {
                    "amount": 2,
                    "attributes": {
                        "rate": 3
                    }
                }
            ]    
        }
    ],
    "fulfillments": [
        {
            "id": "131b9a58-8ee5-41dc-a79e-736ca934b435",
            "tax": [
                {
                    "amount": 10,
                    "attributes": {
                        "rate": 1
                    }
                },
                {
                    "amount": 4,
                    "attributes": {
                        "VAT": "enabled"
                    }
                }
            ],
            "fees": [
                {
                    "id": "d4e9f8dc-c0ae-4ef3-be8b-bd23579a4dd3",
                    "tax": [
                        {
                            "amount": 1,
                            "attributes": {
                                "rate": 1
                            }
                        }
                    ]
                }
            ]
        }
    ]
}'