Skip to main content
Skip to main content
You're viewing the documentation for v1, which isn't the latest Medusa version.Latest documentation

CartService

constructor​

Parameters​

__namedParametersInjectedDependenciesRequired

Properties​

manager_EntityManagerRequired
transactionManager_undefined | EntityManagerRequired
__container__anyRequired
EventsobjectRequired
Events.CUSTOMER_UPDATEDstringRequired

Default: "cart.customer_updated"

Events.CREATEDstringRequired

Default: "cart.created"

Events.UPDATEDstringRequired

Default: "cart.updated"

shippingMethodRepository_Repository<ShippingMethod>Required
cartRepository_Repository<Cart> & objectRequired
addressRepository_Repository<Address>Required
paymentSessionRepository_Repository<PaymentSession>Required
lineItemRepository_Repository<LineItem> & objectRequired
eventBus_EventBusServiceRequired
productVariantService_ProductVariantServiceRequired
productService_ProductServiceRequired
storeService_StoreServiceRequired
salesChannelService_SalesChannelServiceRequired
regionService_RegionServiceRequired
lineItemService_LineItemServiceRequired
paymentProviderService_PaymentProviderServiceRequired
customerService_CustomerServiceRequired
shippingOptionService_ShippingOptionServiceRequired
shippingProfileService_ShippingProfileServiceRequired
discountService_DiscountServiceRequired
giftCardService_GiftCardServiceRequired
taxProviderService_TaxProviderServiceRequired
totalsService_TotalsServiceRequired
newTotalsService_NewTotalsServiceRequired
customShippingOptionService_CustomShippingOptionServiceRequired
priceSelectionStrategy_IPriceSelectionStrategyRequired
lineItemAdjustmentService_LineItemAdjustmentServiceRequired
featureFlagRouter_FlagRouterRequired
remoteQuery_RemoteQueryFunctionRequired
productVariantInventoryService_ProductVariantInventoryServiceRequired
pricingService_PricingServiceRequired
__configModule__Record<string, unknown>
__moduleDeclaration__Record<string, unknown>

Accessors​

activeManager_​

Returns​

EntityManagerEntityManagerRequired

Methods​

withTransaction​

Parameters​

transactionManagerEntityManager

Returns​

thisthisRequired

shouldRetryTransaction_​

Parameters​

errRecord<string, unknown> | objectRequired

Returns​

booleanbooleanRequired

atomicPhase_​

Wraps some work within a transactional block. If the service already has a transaction manager attached this will be reused, otherwise a new transaction manager is created.

Type Parameters​

TResultobjectRequired
TErrorobjectRequired

Parameters​

work(transactionManager: EntityManager) => Promise<TResult>Required
the transactional work to be done
isolationOrErrorHandlerIsolationLevel | (error: TError) => Promise<void | TResult>
the isolation level to be used for the work.
maybeErrorHandlerOrDontFail(error: TError) => Promise<void | TResult>
Potential error handler

Returns​

PromisePromise<TResult>Required
the result of the transactional work

list​

Parameters​

selectorFilterableCartPropsRequired
the query object for find
configFindConfig<Cart>Required
config object

Default: {}

Returns​

PromisePromise<Cart[]>Required
the result of the find operation

retrieve​

Gets a cart by id.

Parameters​

cartIdstringRequired
the id of the cart to get.
optionsFindConfig<Cart>Required
the options to get a cart

Default: {}

totalsConfigTotalsConfigRequired

Default: {}

Returns​

PromisePromise<Cart>Required
the cart document.

retrieveLegacy​

Parameters​

cartIdstringRequired
optionsFindConfig<Cart>Required

Default: {}

totalsConfigTotalsConfigRequired

Default: {}

Returns​

PromisePromise<Cart>Required

Deprecated​

retrieveWithTotals​

Parameters​

cartIdstringRequired
optionsFindConfig<Cart>Required

Default: {}

totalsConfigTotalsConfigRequired

Default: {}

Returns​

PromisePromise<WithRequiredProperty<Cart, "total">>Required

create​

Creates a cart.

Parameters​

dataCartCreatePropsRequired
the data to create the cart with

Returns​

PromisePromise<Cart>Required
the result of the create operation

getValidatedSalesChannel​

Parameters​

salesChannelIdstring

Returns​

PromisePromise<SalesChannel>Required

removeLineItem​

Removes a line item from the cart.

Parameters​

cartIdstringRequired
the id of the cart that we will remove from
lineItemIdstring | string[]Required
the line item(s) to remove.

Returns​

PromisePromise<void>Required
the result of the update operation

validateLineItemShipping_​

Checks if a given line item has a shipping method that can fulfill it. Returns true if all products in the cart can be fulfilled with the current shipping methods.

Parameters​

shippingMethodsShippingMethod[]Required
the set of shipping methods to check from
lineItemShippingProfiledIdstringRequired
the line item

Returns​

booleanbooleanRequired
boolean representing whether shipping method is validated

validateLineItem​

Check if line item's variant belongs to the cart's sales channel.

Parameters​

sales_channel_idobjectRequired
the cart for the line item
sales_channel_id.sales_channel_idnull | stringRequired
lineItemLineItemValidateDataRequired
the line item being added

Returns​

PromisePromise<boolean>Required
a boolean indicating validation result

addLineItem​

Adds a line item to the cart.

Parameters​

cartIdstringRequired
the id of the cart that we will add to
lineItemLineItemRequired
the line item to add.
configobjectRequired
validateSalesChannels - should check if product belongs to the same sales channel as cart (if cart has associated sales channel)
config.validateSalesChannelsbooleanRequired

Default: true

Returns​

PromisePromise<void>Required
the result of the update operation

Deprecated​

Use addOrUpdateLineItems instead.

addOrUpdateLineItems​

Adds or update one or multiple line items to the cart. It also update all existing items in the cart to have has_shipping to false. Finally, the adjustments will be updated.

Parameters​

cartIdstringRequired
the id of the cart that we will add to
lineItemsLineItem | LineItem[]Required
the line items to add.
configobjectRequired
validateSalesChannels - should check if product belongs to the same sales channel as cart (if cart has associated sales channel)
config.validateSalesChannelsbooleanRequired

Default: true

Returns​

PromisePromise<void>Required
the result of the update operation

updateLineItem​

Updates a cart's existing line item.

Parameters​

cartIdstringRequired
the id of the cart to update
lineItemIdstringRequired
the id of the line item to update.
updateLineItemUpdateRequired
the line item to update. Must include an id field.

Returns​

PromisePromise<Cart>Required
the result of the update operation

adjustFreeShipping_​

Ensures shipping total on cart is correct in regards to a potential free shipping discount If a free shipping is present, we set shipping methods price to 0 if a free shipping was present, we set shipping methods to original amount

Parameters​

cartCartRequired
the cart to adjust free shipping for
shouldAddbooleanRequired
flag to indicate, if we should add or remove

Returns​

PromisePromise<void>Required
void

update​

Parameters​

cartOrIdstring | CartRequired
dataCartUpdatePropsRequired

Returns​

PromisePromise<Cart>Required

onSalesChannelChange​

Remove the cart line item that does not belongs to the newly assigned sales channel

Parameters​

cartCartRequired
The cart being updated
newSalesChannelIdstringRequired
The new sales channel being assigned to the cart

Returns​

PromisePromise<void>Required
void

updateCustomerId_​

Sets the customer id of a cart

Parameters​

cartCartRequired
the cart to add email to
customerIdstringRequired
the customer to add to cart

Returns​

PromisePromise<void>Required
the result of the update operation

createOrFetchGuestCustomerFromEmail_​

Creates or fetches a user based on an email.

Parameters​

emailstringRequired
the email to use

Returns​

PromisePromise<Customer>Required
the resultign customer object

updateBillingAddress_​

Updates the cart's billing address.

Parameters​

cartCartRequired
the cart to update
addressOrIdstring | AddressPayload | Partial<Address>Required
the value to set the billing address to
addrRepoRepository<Address>Required
the repository to use for address updates

Returns​

PromisePromise<void>Required
the result of the update operation

updateShippingAddress_​

Updates the cart's shipping address.

Parameters​

cartCartRequired
the cart to update
addressOrIdstring | AddressPayload | Partial<Address>Required
the value to set the shipping address to
addrRepoRepository<Address>Required
the repository to use for address updates

Returns​

PromisePromise<void>Required
the result of the update operation

applyGiftCard_​

Parameters​

cartCartRequired
codestringRequired

Returns​

PromisePromise<void>Required

applyDiscount​

Updates the cart's discounts. If discount besides free shipping is already applied, this will be overwritten Throws if discount regions does not include the cart region

Parameters​

cartCartRequired
the cart to update
discountCodestringRequired
the discount code

Returns​

PromisePromise<void>Required
Updates the cart's discounts. If discount besides free shipping is already applied, this will be overwritten Throws if discount regions does not include the cart region

applyDiscounts​

Updates the cart's discounts. If discount besides free shipping is already applied, this will be overwritten Throws if discount regions does not include the cart region

Parameters​

cartCartRequired
the cart to update
discountCodesstring[]Required
the discount code(s) to apply

Returns​

PromisePromise<void>Required
Updates the cart's discounts. If discount besides free shipping is already applied, this will be overwritten Throws if discount regions does not include the cart region

removeDiscount​

Removes a discount based on a discount code.

Parameters​

cartIdstringRequired
the id of the cart to remove from
discountCodestringRequired
the discount code to remove

Returns​

PromisePromise<Cart>Required
the resulting cart

updatePaymentSession​

Updates the currently selected payment session.

Parameters​

cartIdstringRequired
the id of the cart to update the payment session for
updateRecord<string, unknown>Required
the data to update the payment session with

Returns​

PromisePromise<Cart>Required
the resulting cart

authorizePayment​

Authorizes a payment for a cart. Will authorize with chosen payment provider. This will return a payment object, that we will use to update our cart payment with. Additionally, if the payment does not require more or fails, we will set the payment on the cart.

Parameters​

cartOrIdstring | WithRequiredProperty<Cart, "total">Required
the id of the cart to authorize payment for
contextRecord<string, unknown>Required
object containing whatever is relevant for authorizing the payment with the payment provider. As an example, this could be IP address or similar for fraud handling.

Returns​

PromisePromise<Cart>Required
the resulting cart

setPaymentSession​

Selects a payment session for a cart and creates a payment object in the external provider system

Parameters​

cartIdstringRequired
the id of the cart to add payment method to
providerIdstringRequired
the id of the provider to be set to the cart

Returns​

PromisePromise<void>Required
Selects a payment session for a cart and creates a payment object in the external provider system

setPaymentSessions​

Creates, updates and sets payment sessions associated with the cart. The first time the method is called payment sessions will be created for each provider. Additional calls will ensure that payment sessions have correct amounts, currencies, etc. as well as make sure to filter payment sessions that are not available for the cart's region.

Parameters​

cartOrCartIdstring | WithRequiredProperty<Cart, "total">Required
the id of the cart to set payment session for

Returns​

PromisePromise<void>Required
the result of the update operation.

deletePaymentSession​

Removes a payment session from the cart.

Parameters​

cartIdstringRequired
the id of the cart to remove from
providerIdstringRequired
the id of the provider whose payment session should be removed.

Returns​

PromisePromise<void>Required
the resulting cart.

refreshPaymentSession​

Refreshes a payment session on a cart

Parameters​

cartIdstringRequired
the id of the cart to remove from
providerIdstringRequired
the id of the provider whose payment session should be removed.

Returns​

PromisePromise<void>Required
the resulting cart.

addShippingMethod​

Adds the shipping method to the list of shipping methods associated with the cart. Shipping Methods are the ways that an order is shipped, whereas a Shipping Option is a possible way to ship an order. Shipping Methods may also have additional details in the data field such as an id for a package shop.

Parameters​

cartOrIdstring | CartRequired
the id of the cart to add shipping method to
optionIdstringRequired
id of shipping option to add as valid method
dataRecord<string, unknown>Required
the fulmillment data for the method

Default: {}

Returns​

PromisePromise<Cart>Required
the result of the update operation

findCustomShippingOption​

Finds the cart's custom shipping options based on the passed option id. throws if custom options is not empty and no shipping option corresponds to optionId

Parameters​

cartCustomShippingOptionsCustomShippingOption[]Required
the cart's custom shipping options
optionIdstringRequired
id of the normal or custom shipping option to find in the cartCustomShippingOptions

Returns​

undefined | CustomShippingOptionundefined | CustomShippingOptionRequired
custom shipping option

updateUnitPrices_​

Parameters​

cartCartRequired
regionIdstring
customer_idstring

Returns​

PromisePromise<void>Required

setRegion_​

Set's the region of a cart.

Parameters​

cartCartRequired
the cart to set region on
regionIdstringRequired
the id of the region to set the region to
countryCodenull | stringRequired
the country code to set the country to

Returns​

PromisePromise<void>Required
the result of the update operation

delete​

Deletes a cart from the database. Completed carts cannot be deleted.

Parameters​

cartIdstringRequired
the id of the cart to delete

Returns​

PromisePromise<Cart>Required
the deleted cart or undefined if the cart was not found.

setMetadata​

Dedicated method to set metadata for a cart. To ensure that plugins does not overwrite each others metadata fields, setMetadata is provided.

Parameters​

cartIdstringRequired
the cart to apply metadata to.
keystringRequired
key for metadata field
valuestring | numberRequired
value for metadata field.

Returns​

PromisePromise<Cart>Required
resolves to the updated result.

createTaxLines​

Parameters​

cartOrIdstring | CartRequired

Returns​

PromisePromise<void>Required

deleteTaxLines​

Parameters​

idstringRequired

Returns​

PromisePromise<void>Required

decorateTotals​

Parameters​

cartCartRequired
totalsConfigTotalsConfigRequired

Default: {}

Returns​

PromisePromise<WithRequiredProperty<Cart, "total">>Required

refreshAdjustments_​

Parameters​

cartCartRequired

Returns​

PromisePromise<void>Required

transformQueryForTotals_​

Parameters​

configFindConfig<Cart>Required

Returns​

FindConfigFindConfig<Cart>Required
totalsToSelectTotalField[]Required

decorateTotals_​

Parameters​

cartCartRequired
totalsToSelectTotalField[]Required
optionsTotalsConfigRequired

Returns​

PromisePromise<Cart>Required

Deprecated​

Use decorateTotals instead

getTotalsRelations​

Parameters​

configFindConfig<Cart>Required

Returns​

string[]string[]Required
Was this section helpful?
© 2026 Medusa, Inc. All rights reserved.