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, requestCache: RequestContextCacheService, translator: TranslatorService, stockLevelService: StockLevelService)
getOrderProcessStates() => OrderProcessState[];
findAll(ctx: RequestContext, options?: OrderListOptions, relations?: RelationPaths<Order>) => Promise<PaginatedList<Order>>;
async findOne(ctx: RequestContext, orderId: ID, relations?: RelationPaths<Order>) => Promise<Order | undefined>;
async findOneByCode(ctx: RequestContext, orderCode: string, relations?: RelationPaths<Order>) => Promise<Order | undefined>;
async findOneByOrderLineId(ctx: RequestContext, orderLineId: ID, relations?: RelationPaths<Order>) => Promise<Order | undefined>;
async 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[]>;
async getAggregateOrder(ctx: RequestContext, order: Order) => Promise<Order | undefined>;
getOrderChannels(ctx: RequestContext, order: Order) => Promise<Channel[]>;
async getActiveOrderForUser(ctx: RequestContext, userId: ID) => Promise<Order | undefined>;
async create(ctx: RequestContext, userId?: ID) => Promise<Order>;
async createDraft(ctx: RequestContext) => ;
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) => readonly 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, shippingMethodIds: 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 cancelPayment(ctx: RequestContext, paymentId: ID) => Promise<ErrorResultUnion<CancelPaymentResult, 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 deleteOrder(ctx: RequestContext, orderOrId: ID | Order) => ;
async mergeOrders(ctx: RequestContext, user: User, guestOrder?: Order, existingOrder?: Order) => Promise<Order | undefined>;
async applyPriceAdjustments(ctx: RequestContext, order: Order, updatedOrderLines?: OrderLine[]) => Promise<Order>;
}
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, requestCache: RequestContextCacheService, translator: TranslatorService, stockLevelService: StockLevelService) => 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 OrderProcess objects
defined in the OrderOptions
process array.
findAll
method
type:
(ctx: RequestContext, options?: OrderListOptions, relations?: RelationPaths<Order>) => Promise<PaginatedList<Order>>
findOne
method
type:
(ctx: RequestContext, orderId: ID, relations?: RelationPaths<Order>) => Promise<Order | undefined>
findOneByCode
method
type:
(ctx: RequestContext, orderCode: string, relations?: RelationPaths<Order>) => Promise<Order | undefined>
findOneByOrderLineId
method
type:
(ctx: RequestContext, orderLineId: ID, relations?: RelationPaths<Order>) => Promise<Order | undefined>
findByCustomerId
method
type:
(ctx: RequestContext, customerId: ID, options?: ListQueryOptions<Order>, relations?: RelationPaths<Order>) => Promise<PaginatedList<Order>>
getOrderPayments
method
type:
(ctx: RequestContext, orderId: ID) => Promise<Payment[]>
Returns all Payment entities associated with the Order.
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.
getSellerOrders
method
type:
(ctx: RequestContext, order: Order) => Promise<Order[]>
getAggregateOrder
method
type:
(ctx: RequestContext, order: Order) => Promise<Order | undefined>
getOrderChannels
method
type:
(ctx: RequestContext, order: Order) => Promise<Channel[]>
getActiveOrderForUser
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
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.
createDraft
method
type:
(ctx: RequestContext) =>
updateCustomFields
method
type:
(ctx: RequestContext, orderId: ID, customFields: any) =>
Updates the custom fields of an Order.
addItemToOrder
method
type:
(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
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
method
type:
(ctx: RequestContext, orderId: ID, orderLineId: ID) => Promise<ErrorResultUnion<RemoveOrderItemsResult, Order>>
Removes the specified OrderLine from the Order.
removeAllItemsFromOrder
method
type:
(ctx: RequestContext, orderId: ID) => Promise<ErrorResultUnion<RemoveOrderItemsResult, Order>>
Removes all OrderLines from the Order.
addSurchargeToOrder
method
type:
(ctx: RequestContext, orderId: ID, surchargeInput: Partial<Omit<Surcharge, 'id' | 'createdAt' | 'updatedAt' | 'order'>>) => Promise<Order>
Adds a Surcharge to the Order.
removeSurchargeFromOrder
method
type:
(ctx: RequestContext, orderId: ID, surchargeId: ID) => Promise<Order>
Removes a Surcharge from the Order.
applyCouponCode
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
method
type:
(ctx: RequestContext, orderId: ID, couponCode: string) =>
Removes a coupon code from the Order.
getOrderPromotions
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) => readonly OrderState[]
Returns the next possible states that the Order may transition to.
setShippingAddress
method
type:
(ctx: RequestContext, orderId: ID, input: CreateAddressInput) => Promise<Order>
Sets the shipping address for the Order.
setBillingAddress
method
type:
(ctx: RequestContext, orderId: ID, input: CreateAddressInput) => Promise<Order>
Sets the billing address for the Order.
getEligibleShippingMethods
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
method
type:
(ctx: RequestContext, orderId: ID) => Promise<PaymentMethodQuote[]>
Returns an array of quotes stating which PaymentMethods may be used on this Order.
setShippingMethod
method
type:
(ctx: RequestContext, orderId: ID, shippingMethodIds: ID[]) => Promise<ErrorResultUnion<SetOrderShippingMethodResult, Order>>
Sets the ShippingMethod to be used on this Order.
transitionToState
method
type:
(ctx: RequestContext, orderId: ID, state: OrderState) => Promise<Order | OrderStateTransitionError>
Transitions the Order to the given state.
transitionFulfillmentToState
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
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, except history entry and additional payment actions.
Using dryRun option, you must wrap function call in transaction manually.
transitionPaymentToState
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
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
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
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.
cancelPayment
method
type:
(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
method
type:
(ctx: RequestContext, input: FulfillOrderInput) => Promise<ErrorResultUnion<AddFulfillmentToOrderResult, Fulfillment>>
Creates a new Fulfillment associated with the given Order and OrderItems.
getOrderFulfillments
method
type:
(ctx: RequestContext, order: Order) => Promise<Fulfillment[]>
Returns an array of all Fulfillments associated with the Order.
getOrderSurcharges
method
type:
(ctx: RequestContext, orderId: ID) => Promise<Surcharge[]>
Returns an array of all Surcharges associated with the Order.
cancelOrder
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
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
method
type:
(ctx: RequestContext, input: SettleRefundInput) => Promise<Refund>
Settles a Refund by transitioning it to the
Settled state.
addCustomerToOrder
method
type:
(ctx: RequestContext, orderId: ID, customer: Customer) => Promise<Order>
Associates a Customer with the Order.
addNoteToOrder
method
type:
(ctx: RequestContext, input: AddNoteToOrderInput) => Promise<Order>
Creates a new “ORDER_NOTE” type OrderHistoryEntry in the Order’s history timeline.
updateOrderNote
method
type:
(ctx: RequestContext, input: UpdateOrderNoteInput) => Promise<HistoryEntry>
deleteOrderNote
method
type:
(ctx: RequestContext, id: ID) => Promise<DeletionResponse>
deleteOrder
Deletes an Order, ensuring that any Sessions that reference this Order are dereferenced before deletion.
mergeOrders
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.
applyPriceAdjustments
method
type:
(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.