Skip to main content

OrderService

OrderService

Contains methods relating to Order entities.

Signature
class OrderService {
constructor(connection: TransactionalConnection, configService: ConfigService, productVariantService: ProductVariantService, customerService: CustomerService, countryService: CountryService, orderCalculator: OrderCalculator, shippingCalculator: ShippingCalculator, orderStateMachine: OrderStateMachine, orderMerger: OrderMerger, paymentService: PaymentService, paymentMethodService: PaymentMethodService, fulfillmentService: FulfillmentService, listQueryBuilder: ListQueryBuilder, refundStateMachine: RefundStateMachine, historyService: HistoryService, promotionService: PromotionService, eventBus: EventBus, channelService: ChannelService, orderModifier: OrderModifier, customFieldRelationService: CustomFieldRelationService, requestCache: RequestContextCacheService, translator: TranslatorService, stockLevelService: StockLevelService)
getOrderProcessStates() => OrderProcessState[];
findAll(ctx: RequestContext, options?: OrderListOptions, relations?: RelationPaths<Order>) => Promise<PaginatedList<Order>>;
findOne(ctx: RequestContext, orderId: ID, relations?: RelationPaths<Order>) => Promise<Order | undefined>;
findOneByCode(ctx: RequestContext, orderCode: string, relations?: RelationPaths<Order>) => Promise<Order | undefined>;
findOneByOrderLineId(ctx: RequestContext, orderLineId: ID, relations?: RelationPaths<Order>) => Promise<Order | undefined>;
findByCustomerId(ctx: RequestContext, customerId: ID, options?: ListQueryOptions<Order>, relations?: RelationPaths<Order>) => Promise<PaginatedList<Order>>;
getOrderPayments(ctx: RequestContext, orderId: ID) => Promise<Payment[]>;
getOrderModifications(ctx: RequestContext, orderId: ID) => Promise<OrderModification[]>;
getPaymentRefunds(ctx: RequestContext, paymentId: ID) => Promise<Refund[]>;
getSellerOrders(ctx: RequestContext, order: Order) => Promise<Order[]>;
getAggregateOrder(ctx: RequestContext, order: Order) => Promise<Order | undefined>;
getOrderChannels(ctx: RequestContext, order: Order) => Promise<Channel[]>;
getActiveOrderForUser(ctx: RequestContext, userId: ID) => Promise<Order | undefined>;
create(ctx: RequestContext, userId?: ID) => Promise<Order>;
createDraft(ctx: RequestContext) => ;
updateCustomFields(ctx: RequestContext, orderId: ID, customFields: any) => ;
updateOrderCustomer(ctx: RequestContext, { customerId, orderId, note }: SetOrderCustomerInput) => ;
addItemToOrder(ctx: RequestContext, orderId: ID, productVariantId: ID, quantity: number, customFields?: { [key: string]: any }) => Promise<ErrorResultUnion<UpdateOrderItemsResult, Order>>;
adjustOrderLine(ctx: RequestContext, orderId: ID, orderLineId: ID, quantity: number, customFields?: { [key: string]: any }) => Promise<ErrorResultUnion<UpdateOrderItemsResult, Order>>;
removeItemFromOrder(ctx: RequestContext, orderId: ID, orderLineId: ID) => Promise<ErrorResultUnion<RemoveOrderItemsResult, Order>>;
removeAllItemsFromOrder(ctx: RequestContext, orderId: ID) => Promise<ErrorResultUnion<RemoveOrderItemsResult, Order>>;
addSurchargeToOrder(ctx: RequestContext, orderId: ID, surchargeInput: Partial<Omit<Surcharge, 'id' | 'createdAt' | 'updatedAt' | 'order'>>) => Promise<Order>;
removeSurchargeFromOrder(ctx: RequestContext, orderId: ID, surchargeId: ID) => Promise<Order>;
applyCouponCode(ctx: RequestContext, orderId: ID, couponCode: string) => Promise<ErrorResultUnion<ApplyCouponCodeResult, Order>>;
removeCouponCode(ctx: RequestContext, orderId: ID, couponCode: string) => ;
getOrderPromotions(ctx: RequestContext, orderId: ID) => Promise<Promotion[]>;
getNextOrderStates(order: Order) => readonly OrderState[];
setShippingAddress(ctx: RequestContext, orderId: ID, input: CreateAddressInput) => Promise<Order>;
setBillingAddress(ctx: RequestContext, orderId: ID, input: CreateAddressInput) => Promise<Order>;
getEligibleShippingMethods(ctx: RequestContext, orderId: ID) => Promise<ShippingMethodQuote[]>;
getEligiblePaymentMethods(ctx: RequestContext, orderId: ID) => Promise<PaymentMethodQuote[]>;
setShippingMethod(ctx: RequestContext, orderId: ID, shippingMethodIds: ID[]) => Promise<ErrorResultUnion<SetOrderShippingMethodResult, Order>>;
transitionToState(ctx: RequestContext, orderId: ID, state: OrderState) => Promise<Order | OrderStateTransitionError>;
transitionFulfillmentToState(ctx: RequestContext, fulfillmentId: ID, state: FulfillmentState) => Promise<Fulfillment | FulfillmentStateTransitionError>;
modifyOrder(ctx: RequestContext, input: ModifyOrderInput) => Promise<ErrorResultUnion<ModifyOrderResult, Order>>;
transitionPaymentToState(ctx: RequestContext, paymentId: ID, state: PaymentState) => Promise<ErrorResultUnion<TransitionPaymentToStateResult, Payment>>;
addPaymentToOrder(ctx: RequestContext, orderId: ID, input: PaymentInput) => Promise<ErrorResultUnion<AddPaymentToOrderResult, Order>>;
addManualPaymentToOrder(ctx: RequestContext, input: ManualPaymentInput) => Promise<ErrorResultUnion<AddManualPaymentToOrderResult, Order>>;
settlePayment(ctx: RequestContext, paymentId: ID) => Promise<ErrorResultUnion<SettlePaymentResult, Payment>>;
cancelPayment(ctx: RequestContext, paymentId: ID) => Promise<ErrorResultUnion<CancelPaymentResult, Payment>>;
createFulfillment(ctx: RequestContext, input: FulfillOrderInput) => Promise<ErrorResultUnion<AddFulfillmentToOrderResult, Fulfillment>>;
getOrderFulfillments(ctx: RequestContext, order: Order) => Promise<Fulfillment[]>;
getOrderSurcharges(ctx: RequestContext, orderId: ID) => Promise<Surcharge[]>;
cancelOrder(ctx: RequestContext, input: CancelOrderInput) => Promise<ErrorResultUnion<CancelOrderResult, Order>>;
refundOrder(ctx: RequestContext, input: RefundOrderInput) => Promise<ErrorResultUnion<RefundOrderResult, Refund>>;
settleRefund(ctx: RequestContext, input: SettleRefundInput) => Promise<Refund>;
addCustomerToOrder(ctx: RequestContext, orderIdOrOrder: ID | Order, customer: Customer) => Promise<Order>;
addNoteToOrder(ctx: RequestContext, input: AddNoteToOrderInput) => Promise<Order>;
updateOrderNote(ctx: RequestContext, input: UpdateOrderNoteInput) => Promise<HistoryEntry>;
deleteOrderNote(ctx: RequestContext, id: ID) => Promise<DeletionResponse>;
deleteOrder(ctx: RequestContext, orderOrId: ID | Order) => ;
mergeOrders(ctx: RequestContext, user: User, guestOrder?: Order, existingOrder?: Order) => Promise<Order | undefined>;
applyPriceAdjustments(ctx: RequestContext, order: Order, updatedOrderLines?: OrderLine[]) => Promise<Order>;
}

constructor

method
(connection: TransactionalConnection, configService: ConfigService, productVariantService: ProductVariantService, customerService: CustomerService, countryService: CountryService, orderCalculator: OrderCalculator, shippingCalculator: ShippingCalculator, orderStateMachine: OrderStateMachine, orderMerger: OrderMerger, paymentService: PaymentService, paymentMethodService: PaymentMethodService, fulfillmentService: FulfillmentService, listQueryBuilder: ListQueryBuilder, refundStateMachine: RefundStateMachine, historyService: HistoryService, promotionService: PromotionService, eventBus: EventBus, channelService: ChannelService, orderModifier: OrderModifier, customFieldRelationService: CustomFieldRelationService, requestCache: RequestContextCacheService, translator: TranslatorService, stockLevelService: StockLevelService) => OrderService

getOrderProcessStates

method
() => OrderProcessState[]

Returns an array of all the configured states and transitions of the order process. This is based on the default order process plus all configured OrderProcess objects defined in the OrderOptions process array.

findAll

method
(ctx: RequestContext, options?: OrderListOptions, relations?: RelationPaths<Order>) => Promise<PaginatedList<Order>>

findOne

method
(ctx: RequestContext, orderId: ID, relations?: RelationPaths<Order>) => Promise<Order | undefined>

findOneByCode

method
(ctx: RequestContext, orderCode: string, relations?: RelationPaths<Order>) => Promise<Order | undefined>

findOneByOrderLineId

method
(ctx: RequestContext, orderLineId: ID, relations?: RelationPaths<Order>) => Promise<Order | undefined>

findByCustomerId

method
(ctx: RequestContext, customerId: ID, options?: ListQueryOptions<Order>, relations?: RelationPaths<Order>) => Promise<PaginatedList<Order>>

getOrderPayments

method
(ctx: RequestContext, orderId: ID) => Promise<Payment[]>

Returns all Payment entities associated with the Order.

getOrderModifications

method
(ctx: RequestContext, orderId: ID) => Promise<OrderModification[]>

Returns an array of any OrderModification entities associated with the Order.

getPaymentRefunds

method
(ctx: RequestContext, paymentId: ID) => Promise<Refund[]>

Returns any Refunds associated with a Payment.

getSellerOrders

method
(ctx: RequestContext, order: Order) => Promise<Order[]>

getAggregateOrder

method
(ctx: RequestContext, order: Order) => Promise<Order | undefined>

getOrderChannels

method
(ctx: RequestContext, order: Order) => Promise<Channel[]>

getActiveOrderForUser

method
(ctx: RequestContext, userId: ID) => Promise<Order | undefined>

Returns any Order associated with the specified User's Customer account that is still in the active state.

create

method
(ctx: RequestContext, userId?: ID) => Promise<Order>

Creates a new, empty Order. If a userId is passed, the Order will get associated with that User's Customer account.

createDraft

method
(ctx: RequestContext) =>

updateCustomFields

method
(ctx: RequestContext, orderId: ID, customFields: any) =>

Updates the custom fields of an Order.

updateOrderCustomer

method
v2.2.0
(ctx: RequestContext, { customerId, orderId, note }: SetOrderCustomerInput) =>

Updates the Customer which is assigned to a given Order. The target Customer must be assigned to the same Channels as the Order, otherwise an error will be thrown.

addItemToOrder

method
(ctx: RequestContext, orderId: ID, productVariantId: ID, quantity: number, customFields?: { [key: string]: any }) => Promise<ErrorResultUnion<UpdateOrderItemsResult, Order>>

Adds an item to the Order, either creating a new OrderLine or incrementing an existing one.

adjustOrderLine

method
(ctx: RequestContext, orderId: ID, orderLineId: ID, quantity: number, customFields?: { [key: string]: any }) => Promise<ErrorResultUnion<UpdateOrderItemsResult, Order>>

Adjusts the quantity and/or custom field values of an existing OrderLine.

removeItemFromOrder

method
(ctx: RequestContext, orderId: ID, orderLineId: ID) => Promise<ErrorResultUnion<RemoveOrderItemsResult, Order>>

Removes the specified OrderLine from the Order.

removeAllItemsFromOrder

method
(ctx: RequestContext, orderId: ID) => Promise<ErrorResultUnion<RemoveOrderItemsResult, Order>>

Removes all OrderLines from the Order.

addSurchargeToOrder

method
(ctx: RequestContext, orderId: ID, surchargeInput: Partial<Omit<Surcharge, 'id' | 'createdAt' | 'updatedAt' | 'order'>>) => Promise<Order>

Adds a Surcharge to the Order.

removeSurchargeFromOrder

method
(ctx: RequestContext, orderId: ID, surchargeId: ID) => Promise<Order>

Removes a Surcharge from the Order.

applyCouponCode

method
(ctx: RequestContext, orderId: ID, couponCode: string) => Promise<ErrorResultUnion<ApplyCouponCodeResult, Order>>

Applies a coupon code to the Order, which should be a valid coupon code as specified in the configuration of an active Promotion.

removeCouponCode

method
(ctx: RequestContext, orderId: ID, couponCode: string) =>

Removes a coupon code from the Order.

getOrderPromotions

method
(ctx: RequestContext, orderId: ID) => Promise<Promotion[]>

Returns all Promotions associated with an Order.

getNextOrderStates

method
(order: Order) => readonly OrderState[]

Returns the next possible states that the Order may transition to.

setShippingAddress

method
(ctx: RequestContext, orderId: ID, input: CreateAddressInput) => Promise<Order>

Sets the shipping address for the Order.

setBillingAddress

method
(ctx: RequestContext, orderId: ID, input: CreateAddressInput) => Promise<Order>

Sets the billing address for the Order.

getEligibleShippingMethods

method
(ctx: RequestContext, orderId: ID) => Promise<ShippingMethodQuote[]>

Returns an array of quotes stating which ShippingMethods may be applied to this Order. This is determined by the configured ShippingEligibilityChecker of each ShippingMethod.

The quote also includes a price for each method, as determined by the configured ShippingCalculator of each eligible ShippingMethod.

getEligiblePaymentMethods

method
(ctx: RequestContext, orderId: ID) => Promise<PaymentMethodQuote[]>

Returns an array of quotes stating which PaymentMethods may be used on this Order.

setShippingMethod

method
(ctx: RequestContext, orderId: ID, shippingMethodIds: ID[]) => Promise<ErrorResultUnion<SetOrderShippingMethodResult, Order>>

Sets the ShippingMethod to be used on this Order.

transitionToState

method
(ctx: RequestContext, orderId: ID, state: OrderState) => Promise<Order | OrderStateTransitionError>

Transitions the Order to the given state.

transitionFulfillmentToState

method
(ctx: RequestContext, fulfillmentId: ID, state: FulfillmentState) => Promise<Fulfillment | FulfillmentStateTransitionError>

Transitions a Fulfillment to the given state and then transitions the Order state based on whether all Fulfillments of the Order are shipped or delivered.

modifyOrder

method
(ctx: RequestContext, input: ModifyOrderInput) => Promise<ErrorResultUnion<ModifyOrderResult, Order>>

Allows the Order to be modified, which allows several aspects of the Order to be changed:

  • Changes to OrderLine quantities
  • New OrderLines being added
  • Arbitrary Surcharges being added
  • Shipping or billing address changes

Setting the dryRun input property to true will apply all changes, including updating the price of the Order, except history entry and additional payment actions.

Using dryRun option, you must wrap function call in transaction manually.

transitionPaymentToState

method
(ctx: RequestContext, paymentId: ID, state: PaymentState) => Promise<ErrorResultUnion<TransitionPaymentToStateResult, Payment>>

Transitions the given Payment to a new state. If the order totalWithTax price is then covered by Payments, the Order state will be automatically transitioned to PaymentSettled or PaymentAuthorized.

addPaymentToOrder

method
(ctx: RequestContext, orderId: ID, input: PaymentInput) => Promise<ErrorResultUnion<AddPaymentToOrderResult, Order>>

Adds a new Payment to the Order. If the Order totalWithTax is covered by Payments, then the Order state will get automatically transitioned to the PaymentSettled or PaymentAuthorized state.

addManualPaymentToOrder

method
(ctx: RequestContext, input: ManualPaymentInput) => Promise<ErrorResultUnion<AddManualPaymentToOrderResult, Order>>

This method is used after modifying an existing completed order using the modifyOrder() method. If the modifications cause the order total to increase (such as when adding a new OrderLine), then there will be an outstanding charge to pay.

This method allows you to add a new Payment and assumes the actual processing has been done manually, e.g. in the dashboard of your payment provider.

settlePayment

method

Settles a payment by invoking the PaymentMethodHandler's settlePayment() method. Automatically transitions the Order state if all Payments are settled.

cancelPayment

method

Cancels a payment by invoking the PaymentMethodHandler's cancelPayment() method (if defined), and transitions the Payment to the Cancelled state.

createFulfillment

method
(ctx: RequestContext, input: FulfillOrderInput) => Promise<ErrorResultUnion<AddFulfillmentToOrderResult, Fulfillment>>

Creates a new Fulfillment associated with the given Order and OrderItems.

getOrderFulfillments

method
(ctx: RequestContext, order: Order) => Promise<Fulfillment[]>

Returns an array of all Fulfillments associated with the Order.

getOrderSurcharges

method
(ctx: RequestContext, orderId: ID) => Promise<Surcharge[]>

Returns an array of all Surcharges associated with the Order.

cancelOrder

method
(ctx: RequestContext, input: CancelOrderInput) => Promise<ErrorResultUnion<CancelOrderResult, Order>>

Cancels an Order by transitioning it to the Cancelled state. If stock is being tracked for the ProductVariants in the Order, then new StockMovements will be created to correct the stock levels.

refundOrder

method
(ctx: RequestContext, input: RefundOrderInput) => Promise<ErrorResultUnion<RefundOrderResult, Refund>>

Creates a Refund against the order and in doing so invokes the createRefund() method of the PaymentMethodHandler.

settleRefund

method
(ctx: RequestContext, input: SettleRefundInput) => Promise<Refund>

Settles a Refund by transitioning it to the Settled state.

addCustomerToOrder

method
(ctx: RequestContext, orderIdOrOrder: ID | Order, customer: Customer) => Promise<Order>

Associates a Customer with the Order.

addNoteToOrder

method
(ctx: RequestContext, input: AddNoteToOrderInput) => Promise<Order>

Creates a new "ORDER_NOTE" type OrderHistoryEntry in the Order's history timeline.

updateOrderNote

method
(ctx: RequestContext, input: UpdateOrderNoteInput) => Promise<HistoryEntry>

deleteOrderNote

method
(ctx: RequestContext, id: ID) => Promise<DeletionResponse>

deleteOrder

method
v1.5.0
(ctx: RequestContext, orderOrId: ID | Order) =>

Deletes an Order, ensuring that any Sessions that reference this Order are dereferenced before deletion.

mergeOrders

method
(ctx: RequestContext, user: User, guestOrder?: Order, existingOrder?: Order) => Promise<Order | undefined>

When a guest user with an anonymous Order signs in and has an existing Order associated with that Customer, we need to reconcile the contents of the two orders.

The logic used to do the merging is specified in the OrderOptions mergeStrategy config setting.

applyPriceAdjustments

method
(ctx: RequestContext, order: Order, updatedOrderLines?: OrderLine[]) => Promise<Order>

Applies promotions, taxes and shipping to the Order. If the updatedOrderLines argument is passed in, then all of those OrderLines will have their prices re-calculated using the configured OrderItemPriceCalculationStrategy.