Order Functions

The Order drop-in provides API functions that enable you to programmatically control behavior, fetch data, and integrate with Adobe Commerce backend services.

Version: 3.2.0

Function	Description
cancelOrder	Calls the cancelOrder mutation.
confirmCancelOrder	Confirms the cancellation of an order using the provided order ID and confirmation key.
confirmGuestReturn	Confirms a return request for a guest order using an order ID and confirmation key.
getAttributesForm	Calls the attributesForm query.
getAttributesList	Is a wrapper for the attributesList query.
getCustomer	Is a wrapper for the customer query.
getCustomerOrdersReturn	Returns details about the returns a customer has requested.
getGuestOrder	Is a wrapper for the guestOrder query.
getOrderDetailsById	Fetches detailed order data by order ID from the Commerce backend.
getStoreConfig	Returns information about the storefront configuration.
guestOrderByToken	Retrieves a guest order using a token generated by Adobe Commerce.
placeNegotiableQuoteOrder	Places an order for a negotiable quote.
placeOrder	API function for the drop-in.
reorderItems	Allows a logged-in customer to add all the products from a previous order into their cart.
requestGuestOrderCancel	Is similar to the cancelOrder function, but it is used for guest orders.
requestGuestReturn	Initiates a return request for a guest order.
requestReturn	Takes the RequestReturnProps form as an argument and initiates the process of returning items from an order.
setPaymentMethodAndPlaceOrder	Sets the payment method on a cart and immediately places the order.

cancelOrder

The cancelOrder function calls the cancelOrder mutation. You must pass an order ID and reason.

const cancelOrder = async (
  orderId: string,
  reason: string,
  onSuccess: Function,
  onError: Function
): Promise<void | null | undefined>

Parameter	Type	Req?	Description
orderId	string	Yes	The ID of the order to cancel.
reason	string	Yes	The reason for canceling the order.
onSuccess	Function	Yes	The callback function to execute when the order is successfully canceled.
onError	Function	Yes	The callback function to execute when an error occurs.

Events

Does not emit any drop-in events.

Returns

Returns void | null | undefined.

confirmCancelOrder

The confirmCancelOrder function confirms the cancellation of an order using the provided order ID and confirmation key. The function calls the confirmCancelOrder mutation.

const confirmCancelOrder = async (
  orderId: string,
  confirmationKey: string
): Promise<any>

Parameter	Type	Req?	Description
orderId	string	Yes	The ID of the order to cancel.
confirmationKey	string	Yes	A key generated when a guest requests to cancel an order.

Events

Emits the order/data event with the updated order information after confirming the cancellation.

Returns

Returns void.

confirmGuestReturn

The confirmGuestReturn function confirms a return request for a guest order using an order ID and confirmation key. The function calls the confirmReturn mutation.

const confirmGuestReturn = async (
  orderId: string,
  confirmationKey: string
): Promise<OrderDataModel | null>

Parameter	Type	Req?	Description
orderId	string	Yes	The ID of the order for which the return is being confirmed.
confirmationKey	string	Yes	The confirmation key sent to the guest’s email address to authorize the return.

Events

Emits the order/data event.

Returns

Returns OrderDataModel or null.

getAttributesForm

The getAttributesForm function calls the attributesForm query.

const getAttributesForm = async (
  formCode: string
): Promise<AttributesFormModel[]>

Parameter	Type	Req?	Description
formCode	string	Yes	One of “customer_account_create”, “customer_account_edit”, “customer_address_create”, “customer_address_edit”.

Events

Does not emit any drop-in events.

Returns

Returns AttributesFormModel[].

getAttributesList

The getAttributesList function is a wrapper for the attributesList query. You must pass an attribute code to retrieve the list. The system default values are CUSTOMER, CUSTOMER_ADDRESS, CATALOG_PRODUCT and RMA_ITEM.

const getAttributesList = async (
  entityType: string
): Promise<AttributesFormModel[] | []>

Parameter	Type	Req?	Description
entityType	string	Yes	The entity type for which to retrieve the list of attributes.

Events

Does not emit any drop-in events.

Returns

Returns AttributesFormModel[] | [].

getCustomer

The getCustomer function is a wrapper for the customer query. You must pass a customer ID to retrieve the customer data.

const getCustomer = async (): Promise<CustomerDataModelShort>

Events

Does not emit any drop-in events.

Returns

Returns CustomerDataModelShort.

getCustomerOrdersReturn

The getCustomerOrdersReturn function returns details about the returns a customer has requested. It is a wrapper for the customer query.

const getCustomerOrdersReturn = async (
  pageSize = 10,
  currentPage = 1
): Promise<CustomerOrdersReturnModel | null>

Parameter	Type	Req?	Description
pageSize	number	No	The number of orders to return at a time.
currentPage	number	No	See function signature above

Events

Does not emit any drop-in events.

Returns

Returns CustomerOrdersReturnModel or null.

getGuestOrder

The getGuestOrder function is a wrapper for the guestOrder query.

const getGuestOrder = async (
  form: { number: string; email: string; lastname: string; }
): Promise<OrderDataModel | null>

Parameter	Type	Req?	Description
number	string	Yes	The order number.
email	string	Yes	The email address associated with the order.
lastname	string	Yes	The last name associated with the order.

Events

Does not emit any drop-in events.

Returns

Returns OrderDataModel or null.

getStoreConfig

The getStoreConfig function returns information about the storefront configuration. It is a wrapper for the storeConfig query.

const getStoreConfig = async (): Promise<StoreConfigModel | null>

Events

Does not emit any drop-in events.

Returns

Returns StoreConfigModel or null.

guestOrderByToken

The guestOrderByToken function retrieves a guest order using a token generated by Adobe Commerce. It is a wrapper for the guestOrderByToken query. The function calls the guestOrderByToken query.

const guestOrderByToken = async (
  token?: string,
  returnRef?: string
): Promise<OrderDataModel | null>

Parameter	Type	Req?	Description
token	string	No	A token for the order assigned by Adobe Commerce.
returnRef	string	No	The reference to return.

Events

Does not emit any drop-in events.

Returns

Returns OrderDataModel or null.

placeNegotiableQuoteOrder

The placeNegotiableQuoteOrder function places an order for a negotiable quote. It is a wrapper for the placeNegotiableQuoteOrder mutation. The function calls the placeNegotiableQuoteOrder mutation.

const placeNegotiableQuoteOrder = async (
  quoteUid: string
): Promise<OrderDataModel | null | undefined>

Parameter	Type	Req?	Description
quoteUid	string	Yes	The unique identifier (UID) of the negotiable quote to place as an order.

Events

Emits the order/placed event.

Returns

Returns OrderDataModel | null | undefined. See OrderDataModel.

placeOrder

const placeOrder = async (
  cartId: string
): Promise<OrderDataModel | null | undefined>

Parameter	Type	Req?	Description
cartId	string	Yes	The unique identifier for the shopping cart. This ID is used to track and persist cart data across sessions.

Events

Emits the following events: cart/reset, order/placed.

Returns

Returns OrderDataModel | null | undefined. See OrderDataModel.

reorderItems

The reorderItems function allows a logged-in customer to add all the products from a previous order into their cart. It is a wrapper for the reorderItems mutation.

const reorderItems = async (
  orderNumber: string
): Promise<ReorderItemsProps>

Parameter	Type	Req?	Description
orderNumber	string	Yes	The order number to reorder.

Events

Does not emit any drop-in events.

Returns

Returns ReorderItemsProps.

requestGuestOrderCancel

The requestGuestOrderCancel function is similar to the cancelOrder function, but it is used for guest orders. The token is a unique value generated using guest’s email, order number and postcode The function calls the requestGuestOrderCancel mutation.

const requestGuestOrderCancel = async (
  token: string,
  reason: string,
  onSuccess: Function,
  onError: Function
): Promise<void>

Parameter	Type	Req?	Description
token	string	Yes	The token for the order assigned by Adobe Commerce.
reason	string	Yes	The reason for canceling the order.
onSuccess	Function	Yes	The callback function to execute when the order is successfully canceled.
onError	Function	Yes	The callback function to execute when an error occurs.

Events

Does not emit any drop-in events.

Returns

Returns void.

requestGuestReturn

The requestGuestReturn function initiates a return request for a guest order. The function calls the requestGuestReturn mutation.

const requestGuestReturn = async (
  form: RequestGuestReturnProps
): Promise<{
  uid: string;
  number: string;
  status: string;
  createdAt: string;
}>

Parameter	Type	Req?	Description
form	RequestGuestReturnProps	Yes	The form data for the guest return request, including order details and items to return.

Events

Does not emit any drop-in events.

Returns

Promise<{
  uid: string;
  number: string;
  status: string;
  createdAt: string;
}>

requestReturn

The requestReturn function takes the RequestReturnProps form as an argument and initiates the process of returning items from an order. It is a wrapper for the requestReturn mutation.

const requestReturn = async (
  form: RequestReturnProps
): Promise<RequestReturnModel | {}>

Parameter	Type	Req?	Description
form	RequestReturnProps	Yes	The form data for the return request.

Events

Does not emit any drop-in events.

Returns

Returns RequestReturnModel | {}. See RequestReturnModel.

setPaymentMethodAndPlaceOrder

The setPaymentMethodAndPlaceOrder function sets the payment method on a cart and immediately places the order. The function calls the setPaymentMethodOnCart mutation.

const setPaymentMethodAndPlaceOrder = async (
  cartId: string,
  paymentMethod: any
): Promise<OrderDataModel | null | undefined>

Parameter	Type	Req?	Description
cartId	string	Yes	The ID of the cart to place as an order.
paymentMethod	any	Yes	The payment method information to apply to the cart before placing the order.

Events

Emits the following events: cart/reset, order/placed.

Returns

Returns OrderDataModel | null | undefined. See OrderDataModel.

getOrderDetailsById

The getOrderDetailsById function fetches detailed order data by order number from the Adobe Commerce backend. It supports optional return details and is used internally by the order initialization helpers.

const getOrderDetailsById = async <T extends QueryType>({
  orderId,
  returnRef,
  queryType,
  returnsPageSize,
}: GetOrderDetailsByIdProps): Promise<TransformedData<T>>

Parameter	Type	Req?	Description
orderId	string	No	The order number to fetch.
returnRef	string	No	An optional return reference used to filter return details.
queryType	QueryType	Yes	The type of data to query. Use 'orderData' for standard order details.
returnsPageSize	number	No	Number of return records to fetch. Defaults to 50.

Events

Does not emit any drop-in events.

Returns

Returns OrderDataModel or null.

Data Models

The following data models are used by functions in this drop-in.

CustomerDataModelShort

The CustomerDataModelShort object is returned by the following functions: getCustomer.

interface CustomerDataModelShort {
  firstname: string;
  lastname: string;
  email: string;
}

CustomerOrdersReturnModel

The CustomerOrdersReturnModel object is returned by the following functions: getCustomerOrdersReturn.

interface CustomerOrdersReturnModel {
  ordersReturn: OrdersReturnPropsModel[];
  pageInfo?: PageInfoProps;
}

OrderDataModel

The OrderDataModel object is returned by the following functions: confirmGuestReturn, getGuestOrder, guestOrderByToken, placeNegotiableQuoteOrder, placeOrder, setPaymentMethodAndPlaceOrder.

type OrderDataModel = {
  giftReceiptIncluded: boolean;
  printedCardIncluded: boolean;
  giftWrappingOrder: {
    price: MoneyProps;
    uid: string;
  };
  placeholderImage?: string;
  returnNumber?: string;
  id: string;
  orderStatusChangeDate?: string;
  number: string;
  email: string;
  token?: string;
  status: string;
  isVirtual: boolean;
  totalQuantity: number;
  shippingMethod?: string;
  carrier?: string;
  orderDate: string;
  returns: OrdersReturnPropsModel[];
  discounts: { amount: MoneyProps; label: string }[];
  coupons: {
    code: string;
  }[];
  payments: {
    code: string;
    name: string;
  }[];
  shipping?: { code: string; amount: number; currency: string };
  shipments: ShipmentsModel[];
  items: OrderItemModel[];
  totalGiftCard: MoneyProps;
  grandTotal: MoneyProps;
  grandTotalExclTax: MoneyProps;
  totalShipping?: MoneyProps;
  subtotalExclTax: MoneyProps;
  subtotalInclTax: MoneyProps;
  totalTax: MoneyProps;
  shippingAddress: OrderAddressModel;
  totalGiftOptions: {
    giftWrappingForItems: MoneyProps;
    giftWrappingForItemsInclTax: MoneyProps;
    giftWrappingForOrder: MoneyProps;
    giftWrappingForOrderInclTax: MoneyProps;
    printedCard: MoneyProps;
    printedCardInclTax: MoneyProps;
  };
  billingAddress: OrderAddressModel;
  availableActions: AvailableActionsProps[];
  taxes: { amount: MoneyProps; rate: number; title: string }[];
  appliedGiftCards: {
    code: string;
    appliedBalance: MoneyProps;
  }[];
};

OrderItemProductModel

type OrderItemProductModel = {
  onlyXLeftInStock?: number;
  priceRange?: {
    maximumPrice?: {
      regularPrice?: MoneyProps;
    };
  };
  uid: string;
  __typename: string;
  stockStatus?: string;
  canonicalUrl?: string;
  urlKey?: string;
  id: string;
  image?: string;
  imageAlt?: string;
  name: string;
  productType: string;
  sku: string;
  thumbnail: {
    url: string;
    label: string;
  };
  giftWrappingAvailable?: boolean;
};

OrderItemModel

type OrderItemModel = {
  giftMessage: {
    senderName: string;
    recipientName: string;
    message: string;
  };
  giftWrappingPrice: MoneyProps;
  productGiftWrapping: {
    uid: string;
    design: string;
    selected: boolean;
    image: {
      url: string;
      label: string;
    };
    price: MoneyProps;
  }[];
  taxCalculations: {
    includeAndExcludeTax: {
      originalPrice: MoneyProps;
      baseOriginalPrice: MoneyProps;
      baseDiscountedPrice: MoneyProps;
      baseExcludingTax: MoneyProps;
    };
    excludeTax: {
      originalPrice: MoneyProps;
      baseOriginalPrice: MoneyProps;
      baseDiscountedPrice: MoneyProps;
      baseExcludingTax: MoneyProps;
    };
    includeTax: {
      singleItemPrice: MoneyProps;
      baseOriginalPrice: MoneyProps;
      baseDiscountedPrice: MoneyProps;
    };
  };
  productSalePrice: MoneyProps;
  status?: string;
  currentReturnOrderQuantity?: number;
  eligibleForReturn: boolean;
  productSku?: string;
  type?: string;
  discounted?: boolean;
  id: string;
  productName?: string;
  productUrlKey?: string;
  regularPrice?: MoneyProps;
  price: MoneyProps;
  product?: OrderItemProductModel;
  selectedOptions?: Array<{
    label: string;
    value: any;
  }>;
  thumbnail?: {
    label: string;
    url: string;
  };
  downloadableLinks: {
    count: number;
    result: string;
  } | null;
  prices: {
    priceIncludingTax: MoneyProps;
    originalPrice: MoneyProps;
    originalPriceIncludingTax: MoneyProps;
    price: MoneyProps;
    discounts: {
      label: string;
      amount: { value: number };
    }[];
  };
  itemPrices: {
    priceIncludingTax: MoneyProps;
    originalPrice: MoneyProps;
    originalPriceIncludingTax: MoneyProps;
    price: MoneyProps;
    discounts: {
      label: string;
      amount: { value: number };
    }[];
  };
  bundleOptions: Record<string, string> | null;
  totalInclTax: MoneyProps;
  priceInclTax: MoneyProps;
  total: MoneyProps;
  configurableOptions: Record<string, string | number | boolean> | undefined;
  giftCard?: {
    senderName: string;
    senderEmail: string;
    recipientEmail: string;
    recipientName: string;
    message: string;
  };
  quantityCanceled: number;
  quantityInvoiced: number;
  quantityOrdered: number;
  quantityRefunded: number;
  quantityReturned: number;
  quantityShipped: number;
  requestQuantity?: number;
  totalQuantity: number;
  returnableQuantity?: number;
  quantityReturnRequested: number;
};

ReorderItemsProps

The ReorderItemsProps object is returned by the following functions: reorderItems.

interface ReorderItemsProps {
  success: boolean;
  userInputErrors: UserInputErrorProps[];
}

RequestReturnModel

The RequestReturnModel object is returned by the following functions: requestReturn.

interface RequestReturnModel {
  uid: string;
  number: string;
  status: string;
  createdAt: string;
}

StoreConfigModel

The StoreConfigModel object is returned by the following functions: getStoreConfig.

interface StoreConfigModel {
  baseMediaUrl: string;
  orderCancellationEnabled: boolean;
  orderCancellationReasons: OrderCancellationReason[];
  shoppingOrderDisplayPrice: OrderDisplayPriceProps;
  shoppingOrdersDisplayShipping: OrderDisplayPriceProps;
  shoppingOrdersDisplaySubtotal: OrderDisplayPriceProps;
  shoppingOrdersDisplayFullSummary: boolean;
  shoppingOrdersDisplayGrandTotal: boolean;
  shoppingOrdersDisplayZeroTax: boolean;
  salesPrintedCard: number;
  salesGiftWrapping: number;
}