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

Parameters

orderIdstringRequired

optionIdstringRequired

dataRecord<string, unknown>

configCreateShippingMethodDtoRequired

Default: {}

Returns

Promise<Order>

PromisePromise<Order>Required

---

archive

archive(orderId): Promise<Order>

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_<TResult, TError>(work, isolationOrErrorHandler?, maybeErrorHandlerOrDontFail?): Promise<TResult>

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

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

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

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

Parameters

orderIdstringRequired

id of the order to complete

Returns

Promise<Order>

PromisePromise<Order>Required

the result of the find operation

---

createFromCart

createFromCart(cartOrId): Promise<Order>

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

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<GiftCard>[]

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<GiftCard\>[]Promise<GiftCard>[]Required

---

createRefund

createRefund(orderId, refundAmount, reason, note?, config?): Promise<Order>

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

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

Calculate and attach the different total fields on the object

Parameters

orderOrderRequired

totalsFieldsstring[]

Returns

Promise<Order>

PromisePromise<Order>Required

decorateTotals(order, context?): Promise<Order>

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

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

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<Order[]>

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<[Order[], number]>

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

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

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

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

Parameters

cartIdstringRequired

optionsFindConfig<Order>Required

Default: {}

Returns

Promise<Order>

PromisePromise<Order>Required

---

retrieveByExternalId

retrieveByExternalId(externalId, config?): Promise<Order>

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

Parameters

orderIdOrSelectorstring | Selector<Order>Required

configFindConfig<Order>Required

Default: {}

Returns

Promise<Order>

PromisePromise<Order>Required

---

retrieveWithTotals

retrieveWithTotals(orderId, options?, context?): Promise<Order>

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): { relations: undefined | string[] ; select: undefined | keyof Order[] ; totalsToSelect: undefined | keyof Order[] }

Parameters

configFindConfig<Order>Required

Returns

object

`object`object

relationsundefined | string[]Required

selectundefined | keyof Order[]Required

totalsToSelectundefined | keyof Order[]Required

---

update

update(orderId, update): Promise<Order>

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

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

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

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

Parameters

transactionManagerEntityManager

Returns

OrderService

OrderServiceOrderServiceRequired