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, paymentStateMachine: PaymentStateMachine, paymentMethodService: PaymentMethodService, fulfillmentService: FulfillmentService, listQueryBuilder: ListQueryBuilder, stockMovementService: StockMovementService, refundStateMachine: RefundStateMachine, historyService: HistoryService, promotionService: PromotionService, eventBus: EventBus, channelService: ChannelService, orderModifier: OrderModifier, customFieldRelationService: CustomFieldRelationService)
  getOrderProcessStates() => OrderProcessState[];
  findAll(ctx: RequestContext, options?: OrderListOptions) => Promise<PaginatedList<Order>>;
  async findOne(ctx: RequestContext, orderId: ID) => Promise<Order | undefined>;
  async findOneByCode(ctx: RequestContext, orderCode: string) => Promise<Order | undefined>;
  async findByCustomerId(ctx: RequestContext, customerId: ID, options?: ListQueryOptions<Order>) => Promise<PaginatedList<Order>>;
  getOrderPayments(ctx: RequestContext, orderId: ID) => Promise<Payment[]>;
  async getRefundOrderItems(ctx: RequestContext, refundId: ID) => Promise<OrderItem[]>;
  getOrderModifications(ctx: RequestContext, orderId: ID) => Promise<OrderModification[]>;
  getPaymentRefunds(ctx: RequestContext, paymentId: ID) => Promise<Refund[]>;
  async getActiveOrderForUser(ctx: RequestContext, userId: ID) => Promise<Order | undefined>;
  async create(ctx: RequestContext, userId?: ID) => Promise<Order>;
  async updateCustomFields(ctx: RequestContext, orderId: ID, customFields: any) => ;
  async addItemToOrder(ctx: RequestContext, orderId: ID, productVariantId: ID, quantity: number, customFields?: { [key: string]: any }) => Promise<ErrorResultUnion<UpdateOrderItemsResult, Order>>;
  async adjustOrderLine(ctx: RequestContext, orderId: ID, orderLineId: ID, quantity: number, customFields?: { [key: string]: any }) => Promise<ErrorResultUnion<UpdateOrderItemsResult, Order>>;
  async removeItemFromOrder(ctx: RequestContext, orderId: ID, orderLineId: ID) => Promise<ErrorResultUnion<RemoveOrderItemsResult, Order>>;
  async removeAllItemsFromOrder(ctx: RequestContext, orderId: ID) => Promise<ErrorResultUnion<RemoveOrderItemsResult, Order>>;
  async addSurchargeToOrder(ctx: RequestContext, orderId: ID, surchargeInput: Partial<Omit<Surcharge, 'id' | 'createdAt' | 'updatedAt' | 'order'>>) => Promise<Order>;
  async removeSurchargeFromOrder(ctx: RequestContext, orderId: ID, surchargeId: ID) => Promise<Order>;
  async applyCouponCode(ctx: RequestContext, orderId: ID, couponCode: string) => Promise<ErrorResultUnion<ApplyCouponCodeResult, Order>>;
  async removeCouponCode(ctx: RequestContext, orderId: ID, couponCode: string) => ;
  async getOrderPromotions(ctx: RequestContext, orderId: ID) => Promise<Promotion[]>;
  getNextOrderStates(order: Order) => ReadonlyArray<OrderState>;
  async setShippingAddress(ctx: RequestContext, orderId: ID, input: CreateAddressInput) => Promise<Order>;
  async setBillingAddress(ctx: RequestContext, orderId: ID, input: CreateAddressInput) => Promise<Order>;
  async getEligibleShippingMethods(ctx: RequestContext, orderId: ID) => Promise<ShippingMethodQuote[]>;
  async getEligiblePaymentMethods(ctx: RequestContext, orderId: ID) => Promise<PaymentMethodQuote[]>;
  async setShippingMethod(ctx: RequestContext, orderId: ID, shippingMethodId: ID) => Promise<ErrorResultUnion<SetOrderShippingMethodResult, Order>>;
  async transitionToState(ctx: RequestContext, orderId: ID, state: OrderState) => Promise<Order | OrderStateTransitionError>;
  async transitionFulfillmentToState(ctx: RequestContext, fulfillmentId: ID, state: FulfillmentState) => Promise<Fulfillment | FulfillmentStateTransitionError>;
  async modifyOrder(ctx: RequestContext, input: ModifyOrderInput) => Promise<ErrorResultUnion<ModifyOrderResult, Order>>;
  async transitionPaymentToState(ctx: RequestContext, paymentId: ID, state: PaymentState) => Promise<ErrorResultUnion<TransitionPaymentToStateResult, Payment>>;
  async addPaymentToOrder(ctx: RequestContext, orderId: ID, input: PaymentInput) => Promise<ErrorResultUnion<AddPaymentToOrderResult, Order>>;
  async addManualPaymentToOrder(ctx: RequestContext, input: ManualPaymentInput) => Promise<ErrorResultUnion<AddManualPaymentToOrderResult, Order>>;
  async settlePayment(ctx: RequestContext, paymentId: ID) => Promise<ErrorResultUnion<SettlePaymentResult, Payment>>;
  async createFulfillment(ctx: RequestContext, input: FulfillOrderInput) => Promise<ErrorResultUnion<AddFulfillmentToOrderResult, Fulfillment>>;
  async getOrderFulfillments(ctx: RequestContext, order: Order) => Promise<Fulfillment[]>;
  async getOrderSurcharges(ctx: RequestContext, orderId: ID) => Promise<Surcharge[]>;
  async cancelOrder(ctx: RequestContext, input: CancelOrderInput) => Promise<ErrorResultUnion<CancelOrderResult, Order>>;
  async refundOrder(ctx: RequestContext, input: RefundOrderInput) => Promise<ErrorResultUnion<RefundOrderResult, Refund>>;
  async settleRefund(ctx: RequestContext, input: SettleRefundInput) => Promise<Refund>;
  async addCustomerToOrder(ctx: RequestContext, orderId: ID, customer: Customer) => Promise<Order>;
  async addNoteToOrder(ctx: RequestContext, input: AddNoteToOrderInput) => Promise<Order>;
  async updateOrderNote(ctx: RequestContext, input: UpdateOrderNoteInput) => Promise<HistoryEntry>;
  async deleteOrderNote(ctx: RequestContext, id: ID) => Promise<DeletionResponse>;
  async mergeOrders(ctx: RequestContext, user: User, guestOrder?: Order, existingOrder?: Order) => Promise<Order | undefined>;
}

Members

constructor

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

getOrderProcessStates

method
type:
() => 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 CustomOrderProcess objects defined in the OrderOptions process array.

findAll

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

findOne

async method
type:
(ctx: RequestContext, orderId: ID) => Promise<Order | undefined>

findOneByCode

async method
type:
(ctx: RequestContext, orderCode: string) => Promise<Order | undefined>

findByCustomerId

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

getOrderPayments

method
type:
(ctx: RequestContext, orderId: ID) => Promise<Payment[]>
Returns all Payment entities associated with the Order.

getRefundOrderItems

async method
type:
(ctx: RequestContext, refundId: ID) => Promise<OrderItem[]>
Returns all OrderItems associated with the given {@link Refund}.

getOrderModifications

method
type:
(ctx: RequestContext, orderId: ID) => Promise<OrderModification[]>
Returns an array of any OrderModification entities associated with the Order.

getPaymentRefunds

method
type:
(ctx: RequestContext, paymentId: ID) => Promise<Refund[]>
Returns any {@link Refund}s associated with a Payment.

getActiveOrderForUser

async method
type:
(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

async method
type:
(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.

updateCustomFields

async method
type:
(ctx: RequestContext, orderId: ID, customFields: any) =>
Updates the custom fields of an Order.

addItemToOrder

async method
type:
(ctx: RequestContext, orderId: ID, productVariantId: ID, quantity: number, customFields?: { [key: string]: any }) => Promise<ErrorResultUnion<UpdateOrderItemsResult, Order>>
Adds an OrderItem to the Order, either creating a new OrderLine or incrementing an existing one.

adjustOrderLine

async method
type:
(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

async method
type:
(ctx: RequestContext, orderId: ID, orderLineId: ID) => Promise<ErrorResultUnion<RemoveOrderItemsResult, Order>>
Removes the specified OrderLine from the Order.

removeAllItemsFromOrder

async method
type:
(ctx: RequestContext, orderId: ID) => Promise<ErrorResultUnion<RemoveOrderItemsResult, Order>>
Removes all OrderLines from the Order.

addSurchargeToOrder

async method
type:
(ctx: RequestContext, orderId: ID, surchargeInput: Partial<Omit<Surcharge, 'id' | 'createdAt' | 'updatedAt' | 'order'>>) => Promise<Order>
Adds a Surcharge to the Order.

removeSurchargeFromOrder

async method
type:
(ctx: RequestContext, orderId: ID, surchargeId: ID) => Promise<Order>
Removes a Surcharge from the Order.

applyCouponCode

async method
type:
(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

async method
type:
(ctx: RequestContext, orderId: ID, couponCode: string) =>
Removes a coupon code from the Order.

getOrderPromotions

async method
type:
(ctx: RequestContext, orderId: ID) => Promise<Promotion[]>
Returns all Promotions associated with an Order. A Promotion only gets associated with and Order once the order has been placed (see OrderPlacedStrategy).

getNextOrderStates

method
type:
(order: Order) => ReadonlyArray<OrderState>
Returns the next possible states that the Order may transition to.

setShippingAddress

async method
type:
(ctx: RequestContext, orderId: ID, input: CreateAddressInput) => Promise<Order>
Sets the shipping address for the Order.

setBillingAddress

async method
type:
(ctx: RequestContext, orderId: ID, input: CreateAddressInput) => Promise<Order>
Sets the billing address for the Order.

getEligibleShippingMethods

async method
type:
(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

async method
type:
(ctx: RequestContext, orderId: ID) => Promise<PaymentMethodQuote[]>
Returns an array of quotes stating which PaymentMethods may be used on this Order.

setShippingMethod

async method
type:
(ctx: RequestContext, orderId: ID, shippingMethodId: ID) => Promise<ErrorResultUnion<SetOrderShippingMethodResult, Order>>
Sets the ShippingMethod to be used on this Order.

transitionToState

async method
type:
(ctx: RequestContext, orderId: ID, state: OrderState) => Promise<Order | OrderStateTransitionError>
Transitions the Order to the given state.

transitionFulfillmentToState

async method
type:
(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

async method
type:
(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, but will not actually persist any of those changes to the database.

transitionPaymentToState

async method
type:
(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

async method
type:
(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

async method
type:
(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

async method
type:
(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.

createFulfillment

async method
type:
(ctx: RequestContext, input: FulfillOrderInput) => Promise<ErrorResultUnion<AddFulfillmentToOrderResult, Fulfillment>>
Creates a new Fulfillment associated with the given Order and OrderItems.

getOrderFulfillments

async method
type:
(ctx: RequestContext, order: Order) => Promise<Fulfillment[]>
Returns an array of all Fulfillments associated with the Order.

getOrderSurcharges

async method
type:
(ctx: RequestContext, orderId: ID) => Promise<Surcharge[]>
Returns an array of all Surcharges associated with the Order.

cancelOrder

async method
type:
(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

async method
type:
(ctx: RequestContext, input: RefundOrderInput) => Promise<ErrorResultUnion<RefundOrderResult, Refund>>
Creates a {@link Refund} against the order and in doing so invokes the createRefund() method of the PaymentMethodHandler.

settleRefund

async method
type:
(ctx: RequestContext, input: SettleRefundInput) => Promise<Refund>
Settles a Refund by transitioning it to the Settled state.

addCustomerToOrder

async method
type:
(ctx: RequestContext, orderId: ID, customer: Customer) => Promise<Order>
Associates a Customer with the Order.

addNoteToOrder

async method
type:
(ctx: RequestContext, input: AddNoteToOrderInput) => Promise<Order>
Creates a new “ORDER_NOTE” type OrderHistoryEntry in the Order’s history timeline.

updateOrderNote

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

deleteOrderNote

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

mergeOrders

async method
type:
(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.