Skip to main content
Skip to main content

OrderService

Constructors​

constructor​

**new OrderService**(«destructured»)

Parameters​

__namedParametersInjectedDependenciesRequired

Properties​

__configModule__Record<string, unknown>
__container__anyRequired
__moduleDeclaration__Record<string, unknown>
addressRepository_Repository<Address>Required
cartService_CartServiceRequired
customerService_CustomerServiceRequired
discountService_DiscountServiceRequired
draftOrderService_DraftOrderServiceRequired
eventBus_EventBusServiceRequired
featureFlagRouter_FlagRouterRequired
fulfillmentProviderService_FulfillmentProviderServiceRequired
fulfillmentService_FulfillmentServiceRequired
giftCardService_GiftCardServiceRequired
inventoryService_IInventoryServiceRequired
lineItemService_LineItemServiceRequired
manager_EntityManagerRequired
newTotalsService_NewTotalsServiceRequired
orderRepository_Repository<Order> & { findOneWithRelations: Method findOneWithRelations ; findWithRelations: Method findWithRelations }Required
paymentProviderService_PaymentProviderServiceRequired
productVariantInventoryService_ProductVariantInventoryServiceRequired
regionService_RegionServiceRequired
shippingOptionService_ShippingOptionServiceRequired
shippingProfileService_ShippingProfileServiceRequired
taxProviderService_TaxProviderServiceRequired
totalsService_TotalsServiceRequired
transactionManager_undefined | EntityManagerRequired
EventsobjectRequired
Events.CANCELEDstringRequired

Default: "order.canceled"

Events.COMPLETEDstringRequired

Default: "order.completed"

Events.FULFILLMENT_CANCELEDstringRequired

Default: "order.fulfillment_canceled"

Events.FULFILLMENT_CREATEDstringRequired

Default: "order.fulfillment_created"

Events.GIFT_CARD_CREATEDstringRequired

Default: "order.gift_card_created"

Events.ITEMS_RETURNEDstringRequired

Default: "order.items_returned"

Events.PAYMENT_CAPTUREDstringRequired

Default: "order.payment_captured"

Events.PAYMENT_CAPTURE_FAILEDstringRequired

Default: "order.payment_capture_failed"

Events.PLACEDstringRequired

Default: "order.placed"

Events.REFUND_CREATEDstringRequired

Default: "order.refund_created"

Events.REFUND_FAILEDstringRequired

Default: "order.refund_failed"

Events.RETURN_ACTION_REQUIREDstringRequired

Default: "order.return_action_required"

Events.RETURN_REQUESTEDstringRequired

Default: "order.return_requested"

Events.SHIPMENT_CREATEDstringRequired

Default: "order.shipment_created"

Events.SWAP_CREATEDstringRequired

Default: "order.swap_created"

Events.UPDATEDstringRequired

Default: "order.updated"

Accessors​

activeManager_​

Protected get**activeManager_**(): EntityManager

Returns​

EntityManager

EntityManagerEntityManagerRequired

Methods​

addShippingMethod​

**addShippingMethod**(orderId, optionId, data?, config?): Promise&#60;[Order](/references/services/classes/Order)&#62;

Parameters​

orderIdstringRequired
optionIdstringRequired
dataRecord<string, unknown>
configCreateShippingMethodDtoRequired

Default: {}

Returns​

Promise<Order>

PromisePromise<Order>Required

archive​

**archive**(orderId): Promise&#60;[Order](/references/services/classes/Order)&#62;

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

Parameters​

orderIdstringRequired
the order to archive

Returns​

Promise<Order>

PromisePromise<Order>Required
the result of the update operation

atomicPhase_​

Protected **atomicPhase_**<TypeParameter TResult, TypeParameter TError>(work, isolationOrErrorHandler?, maybeErrorHandlerOrDontFail?): Promise&#60;TResult&#62;

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.

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​

Promise<TResult>

PromisePromise<TResult>Required
the result of the transactional work

cancel​

**cancel**(orderId): Promise&#60;[Order](/references/services/classes/Order)&#62;

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​

Promise<Order>

PromisePromise<Order>Required
result of the update operation.

cancelFulfillment​

**cancelFulfillment**(fulfillmentId): Promise&#60;[Order](/references/services/classes/Order)&#62;

Cancels a fulfillment (if related to an order)

Parameters​

fulfillmentIdstringRequired
the ID of the fulfillment to cancel

Returns​

Promise<Order>

PromisePromise<Order>Required
updated order

capturePayment​

**capturePayment**(orderId): Promise&#60;[Order](/references/services/classes/Order)&#62;

Captures payment for an order.

Parameters​

orderIdstringRequired
id of order to capture payment for.

Returns​

Promise<Order>

PromisePromise<Order>Required
result of the update operation.

completeOrder​

**completeOrder**(orderId): Promise&#60;[Order](/references/services/classes/Order)&#62;

Parameters​

orderIdstringRequired
id of the order to complete

Returns​

Promise<Order>

PromisePromise<Order>Required
the result of the find operation

createFromCart​

**createFromCart**(cartOrId): Promise&#60;[Order](/references/services/classes/Order)&#62;

Creates an order from a cart

Parameters​

cartOrIdstring | CartRequired

Returns​

Promise<Order>

PromisePromise<Order>Required
resolves to the creation result.

createFulfillment​

**createFulfillment**(orderId, itemsToFulfill, config?): Promise&#60;[Order](/references/services/classes/Order)&#62;

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.location_idstring
config.metadataRecord<string, unknown>
config.no_notificationboolean

Returns​

Promise<Order>

PromisePromise<Order>Required
result of the update operation.

createGiftCardsFromLineItem_​

Protected **createGiftCardsFromLineItem_**(order, lineItem, manager): Promise&#60;[GiftCard](/references/services/classes/GiftCard)&#62;[]

Parameters​

orderOrderRequired
An order is a purchase made by a customer. It holds details about payment and fulfillment of the order. An order may also be created from a draft order, which is created by an admin user.
lineItemLineItemRequired
Line Items are created when a product is added to a Cart. When Line Items are purchased they will get copied to the resulting order, swap, or claim, and can eventually be referenced in Fulfillments and Returns. Line items may also be used for order edits.
managerEntityManagerRequired

Returns​

Promise<GiftCard>[]

Promise&#60;GiftCard&#62;[]Promise<GiftCard>[]Required

createRefund​

**createRefund**(orderId, refundAmount, reason, note?, config?): Promise&#60;[Order](/references/services/classes/Order)&#62;

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.
notestring
note for refund.
configobjectRequired
the config for refund.
config.no_notificationboolean

Returns​

Promise<Order>

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

createShipment​

**createShipment**(orderId, fulfillmentId, trackingLinks?, config?): Promise&#60;[Order](/references/services/classes/Order)&#62;

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
trackingLinksTrackingLink[]
array of tracking numbers associated with the shipment
configobjectRequired
the config of the order that has been shipped
config.metadataRecord<string, unknown>Required
config.no_notificationboolean

Returns​

Promise<Order>

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

decorateTotals​

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

Calculate and attach the different total fields on the object

Parameters​

orderOrderRequired
totalsFieldsstring[]

Returns​

Promise<Order>

PromisePromise<Order>Required

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

Calculate and attach the different total fields on the object

Parameters​

orderOrderRequired
contextTotalsContext

Returns​

Promise<Order>

PromisePromise<Order>Required

decorateTotalsLegacy​

Protected **decorateTotalsLegacy**(order, totalsFields?): Promise&#60;[Order](/references/services/classes/Order)&#62;

Parameters​

orderOrderRequired
An order is a purchase made by a customer. It holds details about payment and fulfillment of the order. An order may also be created from a draft order, which is created by an admin user.
totalsFieldsstring[]Required

Default: []

Returns​

Promise<Order>

PromisePromise<Order>Required

getFulfillmentItems​

Protected **getFulfillmentItems**(order, items, transformer): Promise&#60;[LineItem](/references/services/classes/LineItem)[]&#62;

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​

Promise<LineItem[]>

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

getTotalsRelations​

Private **getTotalsRelations**(config): string[]

Parameters​

configFindConfig<Order>Required

Returns​

string[]

string[]string[]Required

list​

**list**(selector, config?): Promise&#60;[Order](/references/services/classes/Order)[]&#62;

Parameters​

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

Returns​

Promise<Order[]>

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

listAndCount​

**listAndCount**(selector, config?): Promise&#60;[[Order](/references/services/classes/Order)[], number]&#62;

Parameters​

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

Returns​

Promise<[Order[], number]>

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

registerReturnReceived​

**registerReturnReceived**(orderId, receivedReturn, customRefundAmount?): Promise&#60;[Order](/references/services/classes/Order)&#62;

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​

Promise<Order>

PromisePromise<Order>Required
the result of the update operation

retrieve​

**retrieve**(orderId, config?): Promise&#60;[Order](/references/services/classes/Order)&#62;

Gets an order by id.

Parameters​

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

Default: {}

Returns​

Promise<Order>

PromisePromise<Order>Required
the order document

retrieveByCartId​

**retrieveByCartId**(cartId, config?): Promise&#60;[Order](/references/services/classes/Order)&#62;

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​

Promise<Order>

PromisePromise<Order>Required
the order document

retrieveByCartIdWithTotals​

**retrieveByCartIdWithTotals**(cartId, options?): Promise&#60;[Order](/references/services/classes/Order)&#62;

Parameters​

cartIdstringRequired
optionsFindConfig<Order>Required

Default: {}

Returns​

Promise<Order>

PromisePromise<Order>Required

retrieveByExternalId​

**retrieveByExternalId**(externalId, config?): Promise&#60;[Order](/references/services/classes/Order)&#62;

Gets an order by id.

Parameters​

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

Default: {}

Returns​

Promise<Order>

PromisePromise<Order>Required
the order document

retrieveLegacy​

Protected **retrieveLegacy**(orderIdOrSelector, config?): Promise&#60;[Order](/references/services/classes/Order)&#62;

Parameters​

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

Default: {}

Returns​

Promise<Order>

PromisePromise<Order>Required

retrieveWithTotals​

**retrieveWithTotals**(orderId, options?, context?): Promise&#60;[Order](/references/services/classes/Order)&#62;

Parameters​

orderIdstringRequired
optionsFindConfig<Order>Required

Default: {}

contextTotalsContextRequired

Default: {}

Returns​

Promise<Order>

PromisePromise<Order>Required

shouldRetryTransaction_​

Protected **shouldRetryTransaction_**(err): boolean

Parameters​

errRecord<string, unknown> | { code: string }Required

Returns​

boolean

booleanboolean

transformQueryForTotals​

Protected **transformQueryForTotals**(config): &#123; relations: undefined \| string[] ; select: undefined \| keyof [Order](/references/services/classes/Order)[] ; totalsToSelect: undefined \| keyof [Order](/references/services/classes/Order)[] &#125;

Parameters​

configFindConfig<Order>Required

Returns​

object

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

update​

**update**(orderId, update): Promise&#60;[Order](/references/services/classes/Order)&#62;

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​

Promise<Order>

PromisePromise<Order>Required
resolves to the update result.

updateBillingAddress​

Protected **updateBillingAddress**(order, address): Promise&#60;void&#62;

Updates the order's billing address.

Parameters​

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

Returns​

Promise<void>

PromisePromise<void>Required
the result of the update operation

updateShippingAddress​

Protected **updateShippingAddress**(order, address): Promise&#60;void&#62;

Updates the order's shipping address.

Parameters​

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

Returns​

Promise<void>

PromisePromise<void>Required
the result of the update operation

validateFulfillmentLineItem​

Protected **validateFulfillmentLineItem**(item, quantity): null \| [LineItem](/references/services/classes/LineItem)

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 | LineItem

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

withTransaction​

**withTransaction**(transactionManager?): [OrderService](/references/services/classes/OrderService)

Parameters​

transactionManagerEntityManager

Returns​

OrderService

OrderServiceOrderServiceRequired
Was this section helpful?
© 2023 Medusa, Inc. All rights reserved.