Medusa

Calculate Cart Taxes

POST

/store/carts/{id}/taxes

Carts

Calculate the cart's tax lines and amounts.

Request Example

Shell

JavaScript

Java

Swift

curl --location -g --request POST '{{BASE_URL}}/store/carts//taxes' \
--header 'x-publishable-api-key;'

Response Example

200 - Example 1

{
    "cart": {
        "id": "string",
        "region_id": "string",
        "customer_id": "string",
        "sales_channel_id": "string",
        "email": "user@example.com",
        "currency_code": "usd",
        "metadata": {},
        "created_at": "2019-08-24T14:15:22Z",
        "updated_at": "2019-08-24T14:15:22Z",
        "original_item_total": 0,
        "original_item_subtotal": 0,
        "original_item_tax_total": 0,
        "item_total": 0,
        "item_subtotal": 0,
        "item_tax_total": 0,
        "original_total": 0,
        "original_subtotal": 0,
        "original_tax_total": 0,
        "total": 0,
        "subtotal": 0,
        "tax_total": 0,
        "discount_total": 0,
        "discount_tax_total": 0,
        "gift_card_total": 0,
        "gift_card_tax_total": 0,
        "shipping_total": 0,
        "shipping_subtotal": 0,
        "shipping_tax_total": 0,
        "original_shipping_total": 0,
        "original_shipping_subtotal": 0,
        "original_shipping_tax_total": 0,
        "shipping_address": {
            "id": "string",
            "customer_id": "string",
            "first_name": "string",
            "last_name": "string",
            "phone": "string",
            "company": "string",
            "address_1": "string",
            "address_2": "string",
            "city": "string",
            "country_code": "us",
            "postal_code": "string",
            "metadata": {},
            "created_at": "2019-08-24T14:15:22Z",
            "updated_at": "2019-08-24T14:15:22Z",
            "province": "us-ca"
        },
        "billing_address": {
            "id": "string",
            "customer_id": "string",
            "first_name": "string",
            "last_name": "string",
            "phone": "string",
            "company": "string",
            "address_1": "string",
            "address_2": "string",
            "city": "string",
            "country_code": "us",
            "postal_code": "string",
            "metadata": {},
            "created_at": "2019-08-24T14:15:22Z",
            "updated_at": "2019-08-24T14:15:22Z",
            "province": "us-ca"
        },
        "shipping_methods": [
            {
                "id": "string",
                "cart_id": "string",
                "name": "string",
                "description": "string",
                "amount": 0,
                "is_tax_inclusive": true,
                "shipping_option_id": "string",
                "metadata": {},
                "created_at": "2019-08-24T14:15:22Z",
                "updated_at": "2019-08-24T14:15:22Z",
                "original_total": 0,
                "original_subtotal": 0,
                "original_tax_total": 0,
                "total": 0,
                "subtotal": 0,
                "tax_total": 0,
                "discount_total": 0,
                "discount_tax_total": 0,
                "data": {},
                "adjustments": [
                    {
                        "shipping_method": {},
                        "id": "string",
                        "code": "string",
                        "amount": 0,
                        "cart_id": "string",
                        "description": "string",
                        "promotion_id": "string",
                        "provider_id": "string",
                        "created_at": "2019-08-24T14:15:22Z",
                        "updated_at": "2019-08-24T14:15:22Z"
                    }
                ],
                "tax_lines": [
                    {
                        "shipping_method": {},
                        "shipping_method_id": "string",
                        "total": 0,
                        "subtotal": 0,
                        "id": "string",
                        "description": "string",
                        "tax_rate_id": "string",
                        "code": "string",
                        "rate": 0,
                        "provider_id": "string",
                        "created_at": "2019-08-24T14:15:22Z",
                        "updated_at": "2019-08-24T14:15:22Z"
                    }
                ]
            }
        ],
        "promotions": [
            {
                "id": "string",
                "code": "string",
                "is_automatic": true,
                "application_method": {
                    "value": "string",
                    "currency_code": "string",
                    "type": "fixed"
                }
            }
        ],
        "region": {
            "id": "string",
            "name": "string",
            "currency_code": "usd",
            "automatic_taxes": true,
            "metadata": {},
            "created_at": "2019-08-24T14:15:22Z",
            "updated_at": "2019-08-24T14:15:22Z",
            "countries": [
                {
                    "id": "string",
                    "iso_2": "us",
                    "iso_3": "usa",
                    "num_code": 840,
                    "name": "string",
                    "display_name": "string"
                }
            ],
            "payment_providers": [
                {
                    "id": "string",
                    "is_enabled": true
                }
            ]
        },
        "items": [
            {
                "id": "string",
                "title": "string",
                "subtitle": "string",
                "thumbnail": "string",
                "quantity": 0,
                "product_id": "string",
                "product_title": "string",
                "product_description": "string",
                "product_subtitle": "string",
                "product_type": "string",
                "product_collection": "string",
                "product_handle": "string",
                "variant_id": "string",
                "variant_sku": "string",
                "variant_barcode": "string",
                "variant_title": "string",
                "requires_shipping": true,
                "is_discountable": true,
                "is_tax_inclusive": true,
                "compare_at_unit_price": 0,
                "unit_price": 0,
                "cart": {},
                "cart_id": "string",
                "metadata": {},
                "created_at": "2019-08-24T14:15:22Z",
                "updated_at": "2019-08-24T14:15:22Z",
                "deleted_at": "2019-08-24T14:15:22Z",
                "original_total": 0,
                "original_subtotal": 0,
                "original_tax_total": 0,
                "item_total": 0,
                "item_subtotal": 0,
                "item_tax_total": 0,
                "total": 0,
                "subtotal": 0,
                "tax_total": 0,
                "discount_total": 0,
                "discount_tax_total": 0,
                "variant_option_values": {
                    "Color": "Red"
                },
                "tax_lines": [
                    {
                        "item": {},
                        "item_id": "string",
                        "total": 0,
                        "subtotal": 0,
                        "id": "string",
                        "description": "string",
                        "tax_rate_id": "string",
                        "code": "string",
                        "rate": 0,
                        "provider_id": "string",
                        "created_at": "2019-08-24T14:15:22Z",
                        "updated_at": "2019-08-24T14:15:22Z"
                    }
                ],
                "adjustments": [
                    {
                        "item": {},
                        "item_id": "string",
                        "id": "string",
                        "code": "string",
                        "amount": 0,
                        "cart_id": "string",
                        "description": "string",
                        "promotion_id": "string",
                        "provider_id": "string",
                        "created_at": "2019-08-24T14:15:22Z",
                        "updated_at": "2019-08-24T14:15:22Z"
                    }
                ],
                "variant": {
                    "product": {},
                    "length": 0,
                    "title": "string",
                    "metadata": {},
                    "id": "string",
                    "width": 0,
                    "weight": 0,
                    "height": 0,
                    "origin_country": "string",
                    "hs_code": "string",
                    "mid_code": "string",
                    "material": "string",
                    "created_at": "2019-08-24T14:15:22Z",
                    "updated_at": "2019-08-24T14:15:22Z",
                    "deleted_at": "2019-08-24T14:15:22Z",
                    "product_id": "string",
                    "sku": "string",
                    "barcode": "string",
                    "ean": "string",
                    "upc": "string",
                    "allow_backorder": true,
                    "variant_rank": 0,
                    "manage_inventory": true,
                    "inventory_quantity": 0,
                    "options": [
                        {
                            "id": "string",
                            "value": "string",
                            "option": {},
                            "option_id": "string",
                            "metadata": {},
                            "created_at": "2019-08-24T14:15:22Z",
                            "updated_at": "2019-08-24T14:15:22Z",
                            "deleted_at": "2019-08-24T14:15:22Z"
                        }
                    ],
                    "calculated_price": {
                        "id": "string",
                        "is_calculated_price_price_list": true,
                        "is_calculated_price_tax_inclusive": true,
                        "calculated_amount": 0,
                        "calculated_amount_with_tax": 0,
                        "calculated_amount_without_tax": 0,
                        "is_original_price_price_list": true,
                        "is_original_price_tax_inclusive": true,
                        "original_amount": 0,
                        "currency_code": "usd",
                        "calculated_price": {},
                        "original_price": {},
                        "original_amount_with_tax": 0,
                        "original_amount_without_tax": 0
                    }
                },
                "product": {
                    "length": 0,
                    "title": "string",
                    "description": "string",
                    "id": "string",
                    "metadata": {},
                    "created_at": "2019-08-24T14:15:22Z",
                    "updated_at": "2019-08-24T14:15:22Z",
                    "handle": "string",
                    "subtitle": "string",
                    "is_giftcard": true,
                    "thumbnail": "string",
                    "width": 0,
                    "weight": 0,
                    "height": 0,
                    "origin_country": "string",
                    "hs_code": "string",
                    "mid_code": "string",
                    "material": "string",
                    "collection_id": "string",
                    "type_id": "string",
                    "discountable": true,
                    "external_id": "string",
                    "deleted_at": "2019-08-24T14:15:22Z",
                    "categories": [
                        {}
                    ],
                    "status": "draft",
                    "images": [
                        {
                            "id": "string",
                            "url": "string",
                            "created_at": "2019-08-24T14:15:22Z",
                            "updated_at": "2019-08-24T14:15:22Z",
                            "deleted_at": "2019-08-24T14:15:22Z",
                            "metadata": {},
                            "rank": 0
                        }
                    ],
                    "tags": [
                        {
                            "id": "string",
                            "value": "string",
                            "created_at": "2019-08-24T14:15:22Z",
                            "updated_at": "2019-08-24T14:15:22Z",
                            "deleted_at": "2019-08-24T14:15:22Z",
                            "metadata": {}
                        }
                    ],
                    "collection": {
                        "id": "string",
                        "title": "string",
                        "handle": "string",
                        "created_at": "2019-08-24T14:15:22Z",
                        "updated_at": "2019-08-24T14:15:22Z",
                        "deleted_at": "2019-08-24T14:15:22Z",
                        "metadata": {},
                        "products": [
                            {}
                        ]
                    },
                    "type": {
                        "id": "string",
                        "metadata": {},
                        "created_at": "2019-08-24T14:15:22Z",
                        "updated_at": "2019-08-24T14:15:22Z",
                        "deleted_at": "2019-08-24T14:15:22Z",
                        "value": "string"
                    },
                    "options": [
                        {
                            "id": "string",
                            "title": "string",
                            "product": {},
                            "product_id": "string",
                            "metadata": {},
                            "created_at": "2019-08-24T14:15:22Z",
                            "updated_at": "2019-08-24T14:15:22Z",
                            "deleted_at": "2019-08-24T14:15:22Z",
                            "values": [
                                {
                                    "id": "string",
                                    "value": "string",
                                    "option": {},
                                    "option_id": "string",
                                    "metadata": {},
                                    "created_at": "2019-08-24T14:15:22Z",
                                    "updated_at": "2019-08-24T14:15:22Z",
                                    "deleted_at": "2019-08-24T14:15:22Z"
                                }
                            ]
                        }
                    ],
                    "variants": [
                        {
                            "product": {},
                            "length": 0,
                            "title": "string",
                            "metadata": {},
                            "id": "string",
                            "width": 0,
                            "weight": 0,
                            "height": 0,
                            "origin_country": "string",
                            "hs_code": "string",
                            "mid_code": "string",
                            "material": "string",
                            "created_at": "2019-08-24T14:15:22Z",
                            "updated_at": "2019-08-24T14:15:22Z",
                            "deleted_at": "2019-08-24T14:15:22Z",
                            "product_id": "string",
                            "sku": "string",
                            "barcode": "string",
                            "ean": "string",
                            "upc": "string",
                            "allow_backorder": true,
                            "variant_rank": 0,
                            "manage_inventory": true,
                            "inventory_quantity": 0,
                            "options": [
                                {
                                    "id": "string",
                                    "value": "string",
                                    "option": {},
                                    "option_id": "string",
                                    "metadata": {},
                                    "created_at": "2019-08-24T14:15:22Z",
                                    "updated_at": "2019-08-24T14:15:22Z",
                                    "deleted_at": "2019-08-24T14:15:22Z"
                                }
                            ],
                            "calculated_price": {
                                "id": "string",
                                "is_calculated_price_price_list": true,
                                "is_calculated_price_tax_inclusive": true,
                                "calculated_amount": 0,
                                "calculated_amount_with_tax": 0,
                                "calculated_amount_without_tax": 0,
                                "is_original_price_price_list": true,
                                "is_original_price_tax_inclusive": true,
                                "original_amount": 0,
                                "currency_code": "usd",
                                "calculated_price": {},
                                "original_price": {},
                                "original_amount_with_tax": 0,
                                "original_amount_without_tax": 0
                            }
                        }
                    ]
                }
            }
        ],
        "payment_collection": {
            "id": "string",
            "currency_code": "string",
            "amount": 0,
            "authorized_amount": 0,
            "captured_amount": 0,
            "refunded_amount": 0,
            "completed_at": "2019-08-24T14:15:22Z",
            "created_at": "2019-08-24T14:15:22Z",
            "updated_at": "2019-08-24T14:15:22Z",
            "metadata": {},
            "status": "canceled",
            "payment_providers": [
                {
                    "id": "string"
                }
            ],
            "payment_sessions": [
                {
                    "id": "string",
                    "amount": 0,
                    "currency_code": "usd",
                    "provider_id": "string",
                    "authorized_at": "2019-08-24T14:15:22Z",
                    "payment_collection": {},
                    "data": {},
                    "status": "authorized",
                    "context": {
                        "customer": {
                            "id": "cus_123"
                        }
                    },
                    "payment": {
                        "id": "string",
                        "amount": 0,
                        "authorized_amount": 0,
                        "currency_code": "string",
                        "provider_id": "string",
                        "created_at": "2019-08-24T14:15:22Z",
                        "updated_at": "2019-08-24T14:15:22Z",
                        "captured_at": "2019-08-24T14:15:22Z",
                        "canceled_at": "2019-08-24T14:15:22Z",
                        "captured_amount": 0,
                        "refunded_amount": 0,
                        "payment_collection": {},
                        "payment_session": {},
                        "data": {},
                        "captures": [
                            {
                                "id": "string",
                                "amount": 0,
                                "created_at": "2019-08-24T14:15:22Z",
                                "created_by": "string",
                                "payment": {}
                            }
                        ],
                        "refunds": [
                            {
                                "id": "string",
                                "amount": 0,
                                "refund_reason_id": "string",
                                "note": "string",
                                "created_at": "2019-08-24T14:15:22Z",
                                "created_by": "string",
                                "payment": {},
                                "refund_reason": {
                                    "id": "string",
                                    "label": "string",
                                    "description": "string",
                                    "metadata": {},
                                    "created_at": "2019-08-24T14:15:22Z",
                                    "updated_at": "2019-08-24T14:15:22Z"
                                }
                            }
                        ]
                    }
                }
            ],
            "payments": [
                {
                    "id": "string",
                    "amount": 0,
                    "authorized_amount": 0,
                    "currency_code": "string",
                    "provider_id": "string",
                    "created_at": "2019-08-24T14:15:22Z",
                    "updated_at": "2019-08-24T14:15:22Z",
                    "captured_at": "2019-08-24T14:15:22Z",
                    "canceled_at": "2019-08-24T14:15:22Z",
                    "captured_amount": 0,
                    "refunded_amount": 0,
                    "payment_collection": {},
                    "payment_session": {},
                    "data": {},
                    "captures": [
                        {
                            "id": "string",
                            "amount": 0,
                            "created_at": "2019-08-24T14:15:22Z",
                            "created_by": "string",
                            "payment": {}
                        }
                    ],
                    "refunds": [
                        {
                            "id": "string",
                            "amount": 0,
                            "refund_reason_id": "string",
                            "note": "string",
                            "created_at": "2019-08-24T14:15:22Z",
                            "created_by": "string",
                            "payment": {},
                            "refund_reason": {
                                "id": "string",
                                "label": "string",
                                "description": "string",
                                "metadata": {},
                                "created_at": "2019-08-24T14:15:22Z",
                                "updated_at": "2019-08-24T14:15:22Z"
                            }
                        }
                    ]
                }
            ]
        }
    }
}

Request

Path Params

string

required

The cart's ID.

Query Params

fields

string

fields

optional

Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Header Params

x-publishable-api-key

string

required

Publishable API Key created in the Medusa Admin.

Responses

🟢200OK

application/json

Body

The cart's details.

cart

object (StoreCart)

required

The cart's details.

string

required

The cart's ID.

region_id

string

region_id

optional

The ID of the region the cart belongs to.

customer_id

string

customer_id

optional

The ID of the customer the cart belongs to.

sales_channel_id

string

sales_channel_id

optional

The ID of the cart's sales channel. Only products that belong to the same sales channel can be added to the cart. The created order will be associated with the same sales channel.

string <email>

optional

The email of the customer the cart belongs to.

currency_code

string

currency_code

required

The cart's currency code.

Example:

usd

metadata

object

optional

The cart's metadata, can hold custom key-value pairs.

created_at

string <date-time>

created_at

optional

The date the cart was created.

updated_at

string <date-time>

updated_at

optional

The date the cart was updated.

original_item_total

number

original_item_total

required

The cart items' total including taxes, excluding promotions.

original_item_subtotal

number

original_item_subtotal

required

The cart items' total excluding taxes, including promotions.

original_item_tax_total

number

original_item_tax_total

required

The cart items' tax total excluding promotions.

item_total

number

item_total

required

The cart items' total including taxes and promotions.

item_subtotal

number

item_subtotal

required

The cart items' total excluding taxes, including promotions.

item_tax_total

number

item_tax_total

required

The cart items' tax total including promotions.

original_total

number

original_total

required

The cart's total including taxes, excluding promotions.

original_subtotal

number

original_subtotal

required

The cart's total excluding taxes, including promotions.

original_tax_total

number

original_tax_total

required

The cart's tax total excluding promotions.

total

number

total

required

The cart's total including taxes and promotions.

subtotal

number

subtotal

required

The cart's total excluding taxes, including promotions.

tax_total

number

tax_total

required

The cart's tax total including promotions.

discount_total

number

discount_total

required

The cart's discount total.

discount_tax_total

number

discount_tax_total

required

The tax total applied on the discounted amount.

gift_card_total

number

gift_card_total

required

The total gift card amount applied on the cart.

gift_card_tax_total

number

gift_card_tax_total

required

The total taxes applied on the gift card amount.

shipping_total

number

shipping_total

required

The cart's shipping total including taxes and promotions.

shipping_subtotal

number

shipping_subtotal

required

The cart's shipping total excluding taxes, including promotions.

shipping_tax_total

number

shipping_tax_total

required

The total taxes applied on the cart's shipping amount.

original_shipping_total

number

original_shipping_total

required

The cart's shipping total including taxes, excluding promotions.

original_shipping_subtotal

number

original_shipping_subtotal

required

The cart's shipping total excluding taxes, including promotions.

original_shipping_tax_total

number

original_shipping_tax_total

required

The total taxes applied on the cart's shipping amount.

shipping_address

object (StoreCartAddress)

optional

The address's details.

billing_address

object (StoreCartAddress)

optional

The address's details.

shipping_methods

array[object (StoreCartShippingMethod) {21}]

optional

The cart's shipping methods.

promotions

array[object (StoreCartPromotion) {4}]

required

The cart's promotions.

region

object (StoreRegion)

optional

The region's details.

items

array[object (StoreCartLineItem) {43}]

optional

The cart's items.

payment_collection

object (StorePaymentCollection)

optional

The payment collection's details.

🟠400Bad Request

🟠401Unauthorized

🟠404Record Not Found

🟠409409

🟠422Parameter Error

🔴500Server Error

Modified at 2025-06-17 04:21:30

Add Line Item to Cart

Get a Cart