OrderService
OrderService
Contains methods relating to Order entities.
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 }, relations?: RelationPaths<Order>) => Promise<ErrorResultUnion<UpdateOrderItemsResult, Order>>;
addItemsToOrder(ctx: RequestContext, orderId: ID, items: Array<{
productVariantId: ID;
quantity: number;
customFields?: { [key: string]: any };
}>, relations?: RelationPaths<Order>) => Promise<{ order: Order; errorResults: Array<JustErrorResults<UpdateOrderItemsResult>> }>;
adjustOrderLine(ctx: RequestContext, orderId: ID, orderLineId: ID, quantity: number, customFields?: { [key: string]: any }, relations?: RelationPaths<Order>) => Promise<ErrorResultUnion<UpdateOrderItemsResult, Order>>;
adjustOrderLines(ctx: RequestContext, orderId: ID, lines: Array<{ orderLineId: ID; quantity: number; customFields?: { [key: string]: any } }>, relations?: RelationPaths<Order>) => Promise<{ order: Order; errorResults: Array<JustErrorResults<UpdateOrderItemsResult>> }>;
removeItemFromOrder(ctx: RequestContext, orderId: ID, orderLineId: ID) => Promise<ErrorResultUnion<RemoveOrderItemsResult, Order>>;
removeItemsFromOrder(ctx: RequestContext, orderId: ID, orderLineIds: 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>;
transitionRefundToState(ctx: RequestContext, refundId: ID, state: RefundState, transactionId?: string) => Promise<Refund | RefundStateTransitionError>;
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[], relations?: RelationPaths<Order>) => Promise<Order>;
}
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) => OrderServicegetOrderProcessStates
() => 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
(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[]>Returns all Payment entities associated with the Order.
getOrderModifications
(ctx: RequestContext, orderId: ID) => Promise<OrderModification[]>Returns an array of any OrderModification entities associated with the Order.
getPaymentRefunds
(ctx: RequestContext, paymentId: ID) => Promise<Refund[]>Returns any Refunds associated with a Payment.
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>Returns any Order associated with the specified User's Customer account
that is still in the active state.
create
(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
(ctx: RequestContext) => updateCustomFields
(ctx: RequestContext, orderId: ID, customFields: any) => Updates the custom fields of an Order.
updateOrderCustomer
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
(ctx: RequestContext, orderId: ID, productVariantId: ID, quantity: number, customFields?: { [key: string]: any }, relations?: RelationPaths<Order>) => Promise<ErrorResultUnion<UpdateOrderItemsResult, Order>>Adds an item to the Order, either creating a new OrderLine or incrementing an existing one.
If you need to add multiple items to an Order, use addItemsToOrder() instead.
addItemsToOrder
(ctx: RequestContext, orderId: ID, items: Array<{
productVariantId: ID;
quantity: number;
customFields?: { [key: string]: any };
}>, relations?: RelationPaths<Order>) => Promise<{ order: Order; errorResults: Array<JustErrorResults<UpdateOrderItemsResult>> }>Adds multiple items to an Order. This method is more efficient than calling addItemToOrder
multiple times, as it only needs to fetch the entire Order once, and only performs
price adjustments once at the end.
Since this method can return multiple error results, it is recommended to check the errorResults
array to determine if any errors occurred.
adjustOrderLine
(ctx: RequestContext, orderId: ID, orderLineId: ID, quantity: number, customFields?: { [key: string]: any }, relations?: RelationPaths<Order>) => Promise<ErrorResultUnion<UpdateOrderItemsResult, Order>>Adjusts the quantity and/or custom field values of an existing OrderLine.
If you need to adjust multiple OrderLines, use adjustOrderLines() instead.
adjustOrderLines
(ctx: RequestContext, orderId: ID, lines: Array<{ orderLineId: ID; quantity: number; customFields?: { [key: string]: any } }>, relations?: RelationPaths<Order>) => Promise<{ order: Order; errorResults: Array<JustErrorResults<UpdateOrderItemsResult>> }>Adjusts the quantity and/or custom field values of existing OrderLines.
This method is more efficient than calling adjustOrderLine multiple times, as it only needs to fetch
the entire Order once, and only performs price adjustments once at the end.
Since this method can return multiple error results, it is recommended to check the errorResults
array to determine if any errors occurred.
removeItemFromOrder
(ctx: RequestContext, orderId: ID, orderLineId: ID) => Promise<ErrorResultUnion<RemoveOrderItemsResult, Order>>Removes the specified OrderLine from the Order.
If you need to remove multiple OrderLines, use removeItemsFromOrder() instead.
removeItemsFromOrder
(ctx: RequestContext, orderId: ID, orderLineIds: ID[]) => Promise<ErrorResultUnion<RemoveOrderItemsResult, Order>>Removes the specified OrderLines from the Order.
This method is more efficient than calling removeItemFromOrder multiple times, as it only needs to fetch
the entire Order once, and only performs price adjustments once at the end.
removeAllItemsFromOrder
(ctx: RequestContext, orderId: ID) => Promise<ErrorResultUnion<RemoveOrderItemsResult, Order>>Removes all OrderLines from the Order.
addSurchargeToOrder
(ctx: RequestContext, orderId: ID, surchargeInput: Partial<Omit<Surcharge, 'id' | 'createdAt' | 'updatedAt' | 'order'>>) => Promise<Order>Adds a Surcharge to the Order.
removeSurchargeFromOrder
(ctx: RequestContext, orderId: ID, surchargeId: ID) => Promise<Order>Removes a Surcharge from the Order.
applyCouponCode
(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
(ctx: RequestContext, orderId: ID, couponCode: string) => Removes a coupon code from the Order.
getOrderPromotions
(ctx: RequestContext, orderId: ID) => Promise<Promotion[]>Returns all Promotions associated with an Order.
getNextOrderStates
(order: Order) => readonly OrderState[]Returns the next possible states that the Order may transition to.
setShippingAddress
(ctx: RequestContext, orderId: ID, input: CreateAddressInput) => Promise<Order>Sets the shipping address for the Order.
setBillingAddress
(ctx: RequestContext, orderId: ID, input: CreateAddressInput) => Promise<Order>Sets the billing address for the Order.
getEligibleShippingMethods
(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
(ctx: RequestContext, orderId: ID) => Promise<PaymentMethodQuote[]>Returns an array of quotes stating which PaymentMethods may be used on this Order.
setShippingMethod
(ctx: RequestContext, orderId: ID, shippingMethodIds: ID[]) => Promise<ErrorResultUnion<SetOrderShippingMethodResult, Order>>Sets the ShippingMethod to be used on this Order.
transitionToState
(ctx: RequestContext, orderId: ID, state: OrderState) => Promise<Order | OrderStateTransitionError>Transitions the Order to the given state.
transitionFulfillmentToState
(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.
transitionRefundToState
(ctx: RequestContext, refundId: ID, state: RefundState, transactionId?: string) => Promise<Refund | RefundStateTransitionError>Transitions a Refund to the given state
modifyOrder
(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
(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
(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
(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
(ctx: RequestContext, paymentId: ID) => Promise<ErrorResultUnion<SettlePaymentResult, Payment>>Settles a payment by invoking the PaymentMethodHandler's settlePayment() method. Automatically
transitions the Order state if all Payments are settled.
cancelPayment
(ctx: RequestContext, paymentId: ID) => Promise<ErrorResultUnion<CancelPaymentResult, Payment>>Cancels a payment by invoking the PaymentMethodHandler's cancelPayment() method (if defined), and transitions the Payment to
the Cancelled state.
createFulfillment
(ctx: RequestContext, input: FulfillOrderInput) => Promise<ErrorResultUnion<AddFulfillmentToOrderResult, Fulfillment>>Creates a new Fulfillment associated with the given Order and OrderItems.
getOrderFulfillments
(ctx: RequestContext, order: Order) => Promise<Fulfillment[]>Returns an array of all Fulfillments associated with the Order.
getOrderSurcharges
(ctx: RequestContext, orderId: ID) => Promise<Surcharge[]>Returns an array of all Surcharges associated with the Order.
cancelOrder
(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
(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
(ctx: RequestContext, input: SettleRefundInput) => Promise<Refund>Settles a Refund by transitioning it to the Settled state.
addCustomerToOrder
(ctx: RequestContext, orderIdOrOrder: ID | Order, customer: Customer) => Promise<Order>Associates a Customer with the Order.
addNoteToOrder
(ctx: RequestContext, input: AddNoteToOrderInput) => Promise<Order>Creates a new "ORDER_NOTE" type OrderHistoryEntry in the Order's history timeline.
updateOrderNote
(ctx: RequestContext, input: UpdateOrderNoteInput) => Promise<HistoryEntry>deleteOrderNote
(ctx: RequestContext, id: ID) => Promise<DeletionResponse>deleteOrder
Deletes an Order, ensuring that any Sessions that reference this Order are dereferenced before deletion.
mergeOrders
(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
(ctx: RequestContext, order: Order, updatedOrderLines?: OrderLine[], relations?: RelationPaths<Order>) => 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.