Menu

Carts API Routes

A cart is a virtual shopping bag that customers can use to add items they want to purchase.

A cart is then used to checkout and place an order.

These API routes allow customers to create and manage their cart, and place an order.

POST /store/carts#

Create Cart

Create a cart.

Authentication: none.

Header parameters

x-publishable-api-keystring
Publishable API Key created in the Medusa Admin.
x-medusa-localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US

Query parameters

fieldsstringOptional
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.
localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US

Request body (application/json)

region_idstringOptional
The ID of the cart's region. This affects the prices and currency of the cart.
shipping_addressobjectOptional
The address's details.
billing_addressobjectOptional
The address's details.
emailstringOptional
The email of the cart's customer.
currency_codestringOptional
The cart's currency code. If not provided, the region's currency is used. This affects prices in the cart, as well.
Example: usd
itemsobject[]Optional
The cart's items.
sales_channel_idstringOptional
The ID of the sales channel that cart is created in. If not provided, the store's default sales channel is associated with the cart instead. A product's availability in a sales channel only filters the products you retrieve. Medusa doesn't reject a variant added to the cart when its product isn't available in the cart's sales channel. Refer to the guide in the external documentation to learn how to enforce that validation.
metadataobjectOptional
The cart's metadata, can hold custom key-value pairs. Learn more in the Manage Metadata section.
additional_dataobjectOptional
Pass additional custom data to the API route. This data is passed to the underlying workflow under the additional_data parameter.

Request examples

Responses

200 OK

cartobject
The cart's details.

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • cart.created: Emitted when a cart is created.

GET /store/carts/{id}#

Get a Cart

Retrieve a cart by its ID. You can expand the cart's relations or select the fields that should be returned.

Authentication: none.

Path parameters

idstring
The cart's ID.

Header parameters

x-publishable-api-keystring
Publishable API Key created in the Medusa Admin.
x-medusa-localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US

Query parameters

fieldsstringOptional
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.
localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US

Request examples

Responses

200 OK

cartobject
The cart's details.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /store/carts/{id}#

Update a Cart

Update a cart's details. This unsets the payment methods chosen before, and the customer would have to choose them again. Also, if the customer has chosen a shipping method whose option isn't valid for the cart's shipping address anymore, the shipping method will be unset. For example, if the shipping option is valid only in the US geo zone, and the shipping address's country code is DE, the shipping method will be unset.

Authentication: none.

Path parameters

idstring
The cart's ID.

Header parameters

x-publishable-api-keystring
Publishable API Key created in the Medusa Admin.
x-medusa-localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US

Query parameters

fieldsstringOptional
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.
localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US

Request body (application/json)

region_idstringOptional
The ID of the associated region. This can affect the prices and currency code of the cart.
customer_idstringOptional
The ID of the customer that the cart belongs to.
sales_channel_idstringOptional
The ID of the associated sales channel. A product's availability in a sales channel only filters the products you retrieve. Medusa doesn't reject a variant added to the cart when its product isn't available in the cart's sales channel. Refer to the guide in the external documentation to learn how to enforce that validation.
emailstringOptional
The email of the customer that the cart belongs to.
currency_codestringOptional
The cart's currency code.
Example: usd
shipping_address_idstringOptional
The ID of the cart's shipping address.
billing_address_idstringOptional
The ID of the cart's billing address.
billing_addressobjectOptional
The address to create.
shipping_addressobjectOptional
The address to create.
metadataobjectOptional
The cart's metadata, ca hold custom key-value pairs. Learn more in the Manage Metadata section.
additional_dataobjectOptional
Pass additional custom data to the API route. This data is passed to the underlying workflow under the additional_data parameter.

Request examples

Responses

200 OK

cartobject
The cart's details.

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • cart.updated: Emitted when a cart's details are updated.
  • cart.region_updated: Emitted when the cart's region is updated. This event is emitted alongside the cart.updated event.

POST /store/carts/{id}/complete#

Complete Cart

Complete a cart and place an order.

Authentication: none.

Path parameters

idstring
The cart's ID.

Header parameters

x-publishable-api-keystring
Publishable API Key created in the Medusa Admin.
x-medusa-localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US

Query parameters

fieldsstringOptional
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.
localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US

Request examples

Responses

200 OK

typestring
The type of the returned object. In this case, the order is returned because the cart was completed successfully.

Default: "order"

orderobjectOptional
The order's details.
cartobjectOptional
The cart's details.
errorobjectOptional
The error's details.

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • order.placed: Emitted when an order is placed, or when a draft order is converted to an order.
  • reservation-item.created: Emitted when reservations are created.

POST /store/carts/{id}/customer#

Change Cart's Customer to Logged-in Customer

Change the cart's customer to the currently logged-in customer. This is useful when you create the cart for a guest customer, then they log in with their account.

Authentication: cookie session, JWT bearer token.

Path parameters

idstring
The cart's ID.

Header parameters

x-publishable-api-keystring
Publishable API Key created in the Medusa Admin.
x-medusa-localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US

Query parameters

fieldsstringOptional
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.
localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US

Request body (application/json)

additional_dataobjectOptional
Pass additional custom data to the API route. This data is passed to the underlying workflow under the additional_data parameter.

Request examples

Responses

200 OK

cartobject
The cart's details.

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • cart.customer_transferred: Emitted when the customer in the cart is transferred.

POST /store/carts/{id}/gift-cards#

Add Gift Card to Cart

Add a Gift Card to a cart

Plugin: This API route is only available when the loyalty plugin is installed in the MedusaGo application.

Authentication: none.

Path parameters

idstring
The cart's ID.

Header parameters

x-publishable-api-keystring
Publishable API Key created in the Medusa Admin.
x-medusa-localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US

Query parameters

localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US

Request body (application/json)

codestring
The gift card's code.

Request examples

Responses

200 OK

cartobject
The cart's details.

400, 401, 404, 409, 422, 500: an error response is returned.

DELETE /store/carts/{id}/gift-cards#

Remove Gift Card from Cart

Remove a Gift Card from a cart.

Plugin: This API route is only available when the loyalty plugin is installed in the MedusaGo application.

Authentication: none.

Path parameters

idstring
The cart's ID.

Header parameters

x-publishable-api-keystring
Publishable API Key created in the Medusa Admin.
x-medusa-localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US

Query parameters

localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US

Request body (application/json)

codestring
The gift card code to remove from the cart.

Request examples

Responses

200 OK

cartobject
The cart's details.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /store/carts/{id}/line-items#

Add Line Item to Cart

Add a product variant as a line item in the cart.

Authentication: none.

Path parameters

idstring
The cart's ID.

Header parameters

x-publishable-api-keystring
Publishable API Key created in the Medusa Admin.
x-medusa-localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US

Query parameters

fieldsstringOptional
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.
localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US

Request body (application/json)

variant_idstring
The ID of the product variant to add as a line item.
quantitynumber
The item's quantity.
metadataobjectOptional
The item's metadata, can hold custom key-value pairs.
additional_dataobjectOptional
Pass additional custom data to the API route. This data is passed to the underlying workflow under the additional_data parameter.

Request examples

Responses

200 OK

cartobject
The cart's details.

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • cart.updated: Emitted when a cart's details are updated.

POST /store/carts/{id}/line-items/{line_id}#

Update a Line Item in a Cart

Update a line item's details in the cart.

Authentication: none.

Path parameters

idstring
The cart's ID.
line_idstring
The line item's ID.

Header parameters

x-publishable-api-keystring
Publishable API Key created in the Medusa Admin.
x-medusa-localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US

Query parameters

fieldsstringOptional
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.
localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US

Request body (application/json)

quantitynumber
The item's quantity.
metadataobjectOptional
The item's metadata, can hold custom key-value pairs.
additional_dataobjectOptional
Pass additional custom data to the API route. This data is passed to the underlying workflow under the additional_data parameter.

Request examples

Responses

200 OK

cartobject
The cart's details.

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • cart.updated: Emitted when a cart's details are updated.

DELETE /store/carts/{id}/line-items/{line_id}#

Remove Line Item from Cart

Remove a line item from a cart.

Authentication: none.

Path parameters

idstring
The cart's ID.
line_idstring
The line item's ID.

Header parameters

x-publishable-api-keystring
Publishable API Key created in the Medusa Admin.
x-medusa-localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US

Query parameters

fieldsstringOptional
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.
localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US

Request examples

Responses

200 OK

idstring
The ID of the deleted line item.
objectstring
The name of the deleted object.

Default: "line-item"

deletedboolean
Whether the item was deleted.
parentobjectOptional
The cart's details.

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • cart.updated: Emitted when a cart's details are updated.

POST /store/carts/{id}/promotions#

Add Promotions to Cart

Add a list of promotions to a cart.

Authentication: none.

Path parameters

idstring
The cart's ID.

Header parameters

x-publishable-api-keystring
Publishable API Key created in the Medusa Admin.
x-medusa-localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US

Query parameters

fieldsstringOptional
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.
localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US

Request body (application/json)

promo_codesstring[]
Promotion codes to add to the cart.

Request examples

Responses

200 OK

cartobject
The cart's details.

400, 401, 404, 409, 422, 500: an error response is returned.

DELETE /store/carts/{id}/promotions#

Remove Promotions from Cart

Remove a list of promotions from a cart.

Authentication: none.

Path parameters

idstring
The cart's ID.

Header parameters

x-publishable-api-keystring
Publishable API Key created in the Medusa Admin.
x-medusa-localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US

Query parameters

fieldsstringOptional
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.
localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US

Request body (application/json)

promo_codesstring[]
The promotion code to remove from the cart.

Request examples

Responses

200 OK

cartobject
The cart's details.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /store/carts/{id}/shipping-methods#

Add Shipping Method to Cart

Add a shipping method to a cart. Use this API route when the customer chooses their preferred shipping option.

If the chosen shipping option's price_type is calculated, its price is computed by the associated fulfillment provider when it's added to the cart. If the provider fails to calculate the price, this route returns an error.

Authentication: none.

Path parameters

idstring
The cart's ID.

Header parameters

x-publishable-api-keystring
Publishable API Key created in the Medusa Admin.
x-medusa-localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US

Query parameters

localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US
fieldsstringOptional
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.

Request body (application/json)

option_idstring
The ID of the shipping option to add to the cart.
dataobjectOptional
Any additional data relevant for the third-party fulfillment provider to process the shipment.
additional_dataobjectOptional
Pass additional custom data to the API route. This data is passed to the underlying workflow under the additional_data parameter.

Request examples

Responses

200 OK

cartobject
The cart's details.

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • cart.updated: Emitted when a cart's details are updated.

POST /store/carts/{id}/store-credits#

Add Store Credit to Cart

Add a Store Credit to a cart

Plugin: This API route is only available when the loyalty plugin is installed in the MedusaGo application.

Authentication: none.

Path parameters

idstring
The cart's ID.

Header parameters

x-publishable-api-keystring
Publishable API Key created in the Medusa Admin.
x-medusa-localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US

Query parameters

localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US

Request body (application/json)

amountnumber
The amount of store credits to add to the cart.

Request examples

Responses

200 OK

cartobject
The cart's details.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /store/carts/{id}/taxes#

Calculate Cart Taxes

Calculate the cart's tax lines and amounts.

Medusa recalculates a cart's tax lines automatically on cart changes when the cart's region has automatic_taxes enabled, so you typically don't need to use this route. Use this route to force a recalculation, such as when automatic_taxes is disabled, which also triggers a fresh calculation from your third-party tax provider, if you use one.

Authentication: none.

Path parameters

idstring
The cart's ID.

Header parameters

x-publishable-api-keystring
Publishable API Key created in the Medusa Admin.
x-medusa-localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US

Query parameters

localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US
fieldsstringOptional
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.

Request examples

Responses

200 OK

cartobject
The cart's details.

400, 401, 404, 409, 422, 500: an error response is returned.

Found a problem with this page?Report Issue
Edited Nov 14·Edit this page