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

OrderService

constructor​

Parameters​

__namedParametersInjectedDependenciesRequired

Properties​

manager_EntityManagerRequired
transactionManager_undefined | EntityManagerRequired
__container__anyRequired
EventsobjectRequired
Events.GIFT_CARD_CREATEDstringRequired

Default: "order.gift_card_created"

Events.PAYMENT_CAPTUREDstringRequired

Default: "order.payment_captured"

Events.PAYMENT_CAPTURE_FAILEDstringRequired

Default: "order.payment_capture_failed"

Events.SHIPMENT_CREATEDstringRequired

Default: "order.shipment_created"

Events.FULFILLMENT_CREATEDstringRequired

Default: "order.fulfillment_created"

Events.FULFILLMENT_CANCELEDstringRequired

Default: "order.fulfillment_canceled"

Events.RETURN_REQUESTEDstringRequired

Default: "order.return_requested"

Events.ITEMS_RETURNEDstringRequired

Default: "order.items_returned"

Events.RETURN_ACTION_REQUIREDstringRequired

Default: "order.return_action_required"

Events.REFUND_CREATEDstringRequired

Default: "order.refund_created"

Events.REFUND_FAILEDstringRequired

Default: "order.refund_failed"

Events.SWAP_CREATEDstringRequired

Default: "order.swap_created"

Events.PLACEDstringRequired

Default: "order.placed"

Events.UPDATEDstringRequired

Default: "order.updated"

Events.CANCELEDstringRequired

Default: "order.canceled"

Events.COMPLETEDstringRequired

Default: "order.completed"

orderRepository_Repository<Order> & objectRequired
customerService_CustomerServiceRequired
paymentProviderService_PaymentProviderServiceRequired
shippingOptionService_ShippingOptionServiceRequired
shippingProfileService_ShippingProfileServiceRequired
discountService_DiscountServiceRequired
fulfillmentProviderService_FulfillmentProviderServiceRequired
fulfillmentService_FulfillmentServiceRequired
lineItemService_LineItemServiceRequired
totalsService_TotalsServiceRequired
newTotalsService_NewTotalsServiceRequired
taxProviderService_TaxProviderServiceRequired
regionService_RegionServiceRequired
cartService_CartServiceRequired
addressRepository_Repository<Address>Required
giftCardService_GiftCardServiceRequired
draftOrderService_DraftOrderServiceRequired
inventoryService_IInventoryServiceRequired
eventBus_EventBusServiceRequired
featureFlagRouter_FlagRouterRequired
remoteLink_RemoteLinkRequired
productVariantInventoryService_ProductVariantInventoryServiceRequired
__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​

selectorSelector<Order>Required
the query object for find
configFindConfig<Order>Required
the config to be used for find

Returns​

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

listAndCount​

Parameters​

selectorQuerySelector<Order>Required
the query object for find
configFindConfig<Order>Required
the config to be used for find

Returns​

PromisePromise<[Order[], number]>Required
the result of the find operation

transformQueryForTotals​

Parameters​

configFindConfig<Order>Required

Returns​

relationsundefined | string[]Required
selectundefined | keyof Order[]Required
totalsToSelectundefined | keyof Order[]Required
relationsundefined | string[]Required
selectundefined | keyof Order[]Required
totalsToSelectundefined | keyof Order[]Required

retrieve​

Gets an order by id.

Parameters​

orderIdstringRequired
id or selector of order to retrieve
configFindConfig<Order>Required
config of order to retrieve

Default: {}

Returns​

PromisePromise<Order>Required
the order document

retrieveLegacy​

Parameters​

orderIdOrSelectorstring | Selector<Order>Required
configFindConfig<Order>Required

Default: {}

Returns​

PromisePromise<Order>Required

retrieveWithTotals​

Parameters​

orderIdstringRequired
optionsFindConfig<Order>Required

Default: {}

contextTotalsContextRequired

Default: {}

Returns​

PromisePromise<Order>Required

retrieveByCartId​

Gets an order by cart id.

Parameters​

cartIdstringRequired
cart id to find order
configFindConfig<Order>Required
the config to be used to find order

Default: {}

Returns​

PromisePromise<Order>Required
the order document

retrieveByCartIdWithTotals​

Parameters​

cartIdstringRequired
optionsFindConfig<Order>Required

Default: {}

Returns​

PromisePromise<Order>Required

retrieveByExternalId​

Gets an order by id.

Parameters​

externalIdstringRequired
id of order to retrieve
configFindConfig<Order>Required
query config to get order by

Default: {}

Returns​

PromisePromise<Order>Required
the order document

completeOrder​

Parameters​

orderIdstringRequired
id of the order to complete

Returns​

PromisePromise<Order>Required
the result of the find operation

createFromCart​

Creates an order from a cart

Parameters​

cartOrIdstring | CartRequired

Returns​

PromisePromise<Order>Required
resolves to the creation result.

createGiftCardsFromLineItem_​

Parameters​

orderOrderRequired
lineItemLineItemRequired
managerEntityManagerRequired

Returns​

Promise<GiftCard>[]Promise<GiftCard>[]Required

createShipment​

Adds a shipment to the order to indicate that an order has left the warehouse. Will ask the fulfillment provider for any documents that may have been created in regards to the shipment.

Parameters​

orderIdstringRequired
the id of the order that has been shipped
fulfillmentIdstringRequired
the fulfillment that has now been shipped
configobjectRequired
the config of the order that has been shipped
config.metadataRecord<string, unknown>Required
trackingLinksTrackingLink[]
array of tracking numbers associated with the shipment
config.no_notificationboolean

Returns​

PromisePromise<Order>Required
the resulting order following the update.

updateBillingAddress​

Updates the order's billing address.

Parameters​

orderOrderRequired
the order to update
addressAddressRequired
the value to set the billing address to

Returns​

PromisePromise<void>Required
the result of the update operation

updateShippingAddress​

Updates the order's shipping address.

Parameters​

orderOrderRequired
the order to update
addressAddressRequired
the value to set the shipping address to

Returns​

PromisePromise<void>Required
the result of the update operation

addShippingMethod​

Parameters​

orderIdstringRequired
optionIdstringRequired
configCreateShippingMethodDtoRequired

Default: {}

dataRecord<string, unknown>

Returns​

PromisePromise<Order>Required

update​

Updates an order. Metadata updates should use dedicated method, e.g. setMetadata etc. The function will throw errors if metadata updates are attempted.

Parameters​

orderIdstringRequired
the id of the order. Must be a string that can be casted to an ObjectId
updateUpdateOrderInputRequired
an object with the update values.

Returns​

PromisePromise<Order>Required
resolves to the update result.

cancel​

Cancels an order. Throws if fulfillment process has been initiated. Throws if payment process has been initiated.

Parameters​

orderIdstringRequired
id of order to cancel.

Returns​

PromisePromise<Order>Required
result of the update operation.

capturePayment​

Captures payment for an order.

Parameters​

orderIdstringRequired
id of order to capture payment for.

Returns​

PromisePromise<Order>Required
result of the update operation.

validateFulfillmentLineItem​

Checks that a given quantity of a line item can be fulfilled. Fails if the fulfillable quantity is lower than the requested fulfillment quantity. Fulfillable quantity is calculated by subtracting the already fulfilled quantity from the quantity that was originally purchased.

Parameters​

itemLineItemRequired
the line item to check has sufficient fulfillable quantity.
quantitynumberRequired
the quantity that is requested to be fulfilled.

Returns​

null | LineItemnull | LineItemRequired
a line item that has the requested fulfillment quantity set.

createFulfillment​

Creates fulfillments for an order. In a situation where the order has more than one shipping method, we need to partition the order items, such that they can be sent to their respective fulfillment provider.

Parameters​

orderIdstringRequired
id of order to fulfil.
itemsToFulfillFulFillmentItemType[]Required
items to fulfil.
configobjectRequired
the config to fulfil.

Default: {}

config.no_notificationboolean
config.location_idstring
config.metadataRecord<string, unknown>

Returns​

PromisePromise<Order>Required
result of the update operation.

cancelFulfillment​

Cancels a fulfillment (if related to an order)

Parameters​

fulfillmentIdstringRequired
the ID of the fulfillment to cancel

Returns​

PromisePromise<Order>Required
updated order

getFulfillmentItems​

Retrieves the order line items, given an array of items.

Parameters​

orderOrderRequired
the order to get line items from
itemsFulFillmentItemType[]Required
the items to get
transformer(item: undefined | LineItem, quantity: number) => unknownRequired
a function to apply to each of the items retrieved from the order, should return a line item. If the transformer returns an undefined value the line item will be filtered from the returned array.

Returns​

PromisePromise<LineItem[]>Required
the line items generated by the transformer.

archive​

Archives an order. It only alloved, if the order has been fulfilled and payment has been captured.

Parameters​

orderIdstringRequired
the order to archive

Returns​

PromisePromise<Order>Required
the result of the update operation

createRefund​

Refunds a given amount back to the customer.

Parameters​

orderIdstringRequired
id of the order to refund.
refundAmountnumberRequired
the amount to refund.
reasonstringRequired
the reason to refund.
configobjectRequired
the config for refund.
notestring
note for refund.
config.no_notificationboolean

Returns​

PromisePromise<Order>Required
the result of the refund operation.

decorateTotalsLegacy​

Parameters​

orderOrderRequired
totalsFieldsstring[]Required

Default: []

Returns​

PromisePromise<Order>Required

decorateTotals​

**decorateTotals**(order, totalsFields?): Promise&#60;[Order](../../entities/classes/entities.Order.mdx)&#62;

Calculate and attach the different total fields on the object

Parameters​

orderOrderRequired
totalsFieldsstring[]

Returns​

PromisePromise<Order>Required
Calculate and attach the different total fields on the object

**decorateTotals**(order, context?): Promise&#60;[Order](../../entities/classes/entities.Order.mdx)&#62;

Calculate and attach the different total fields on the object

Parameters​

orderOrderRequired
contextTotalsContext

Returns​

PromisePromise<Order>Required
Calculate and attach the different total fields on the object

registerReturnReceived​

Handles receiving a return. This will create a refund to the customer. If the returned items don't match the requested items the return status will be updated to requires_action. This behaviour is useful in situations where a custom refund amount is requested, but the returned items are not matching the requested items. Setting the allowMismatch argument to true, will process the return, ignoring any mismatches.

Parameters​

orderIdstringRequired
the order to return.
receivedReturnReturnRequired
the received return
customRefundAmountnumber
the custom refund amount return

Returns​

PromisePromise<Order>Required
the result of the update operation

getTotalsRelations​

Parameters​

configFindConfig<Order>Required

Returns​

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