Purchase Order Functions

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

Version: 0.0.1

Function	Description
addPurchaseOrderComment	Adds a comment to a purchase order..
addPurchaseOrderItemsToCart	Adds purchase order items to a cart..
approvePurchaseOrders	Approves one or more purchase orders..
cancelPurchaseOrders	Cancels one or more purchase orders..
createPurchaseOrderApprovalRule	Creates a new purchase order approval rule..
currencyInfo	An async function that fetches currency information including the base currency code and available currency codes from GraphQL API..
deletePurchaseOrderApprovalRule	Deletes one or more purchase order approval rules..
getPurchaseOrder	Gets a single purchase order by UID..
getPurchaseOrderApprovalRule	Retrieves a specific purchase order approval rule by its unique identifier.
getPurchaseOrderApprovalRuleMetadata	Gets the current user’s purchase order approval rule metadata..
getPurchaseOrderApprovalRules	Gets the current user’s purchase order approval rules with pagination support..
getPurchaseOrders	Gets a list of purchase orders with optional filtering and pagination..
placeOrderForPurchaseOrder	Places an order from an approved purchase order..
placePurchaseOrder	Places a purchase order from a cart..
rejectPurchaseOrders	Rejects one or more purchase orders..
updatePurchaseOrderApprovalRule	Updates an existing purchase order approval rule..
validatePurchaseOrders	Validates one or more purchase orders..

addPurchaseOrderComment

Adds a comment to a purchase order.

const addPurchaseOrderComment = async (
  uid: string,
  comment: string
): Promise<PurchaseOrderCommentModel>

Parameter	Type	Req?	Description
uid	string	Yes	See function signature above
comment	string	Yes	See function signature above

Events

Does not emit any drop-in events.

Returns

Returns PurchaseOrderCommentModel.

---

addPurchaseOrderItemsToCart

Adds purchase order items to a cart.

const addPurchaseOrderItemsToCart = async (
  purchaseOrderUid: string,
  cartId: string,
  replaceExistingCartItems: boolean = false
): Promise<CartModel>

Parameter	Type	Req?	Description
purchaseOrderUid	string	Yes	See function signature above
cartId	string	Yes	The unique identifier for the shopping cart. This ID is used to track and persist cart data across sessions.
replaceExistingCartItems	boolean	No	See function signature above

Events

Does not emit any drop-in events.

Returns

Returns CartModel.

---

approvePurchaseOrders

Approves one or more purchase orders.

const approvePurchaseOrders = async (
  uids: string | string[]
): Promise<{
  errors: { message: string; type: string }[];
  purchaseOrders: PurchaseOrderModel[];
}>

Parameter	Type	Req?	Description
uids	string | string[]	Yes	See function signature above

Events

Does not emit any drop-in events.

Returns

Returns Promise<{ errors: { message: string; type: string }[]; purchaseOrders: PurchaseOrderModel[]; }>. See PurchaseOrderModel.

---

cancelPurchaseOrders

Cancels one or more purchase orders.

const cancelPurchaseOrders = async (
  uids: string | string[]
): Promise<{
  errors: { message: string; type: string }[];
  purchaseOrders: PurchaseOrderModel[];
}>

Parameter	Type	Req?	Description
uids	string | string[]	Yes	See function signature above

Events

Does not emit any drop-in events.

Returns

Returns Promise<{ errors: { message: string; type: string }[]; purchaseOrders: PurchaseOrderModel[]; }>. See PurchaseOrderModel.

---

createPurchaseOrderApprovalRule

Creates a new purchase order approval rule.

const createPurchaseOrderApprovalRule = async (
  input: any
): Promise<PurchaseOrderApprovalRuleModel>

Parameter	Type	Req?	Description
input	any	Yes	Input parameters for the operation.

Events

Does not emit any drop-in events.

Returns

Returns PurchaseOrderApprovalRuleModel.

---

currencyInfo

An async function that fetches currency information including the base currency code and available currency codes from GraphQL API.

const currencyInfo = async (): Promise<{
  baseCurrencyCode: string;
  availableCurrencyCodes: { text: string; value: string }[];
}>

Events

Does not emit any drop-in events.

Returns

Returns:

Promise<{
  baseCurrencyCode: string;
  availableCurrencyCodes: { text: string; value: string }[];
}>

---

deletePurchaseOrderApprovalRule

Deletes one or more purchase order approval rules.

const deletePurchaseOrderApprovalRule = async (
  uids: string | string[]
): Promise<{
  deletePurchaseOrderApprovalRule: {
    errors: { message?: string; type?: string }[];
  };
}>

Parameter	Type	Req?	Description
uids	string | string[]	Yes	See function signature above

Events

Does not emit any drop-in events.

Returns

Returns:

Promise<{
  deletePurchaseOrderApprovalRule: {
    errors: { message?: string; type?: string }[];
  };
}>

---

getPurchaseOrder

Gets a single purchase order by UID.

const getPurchaseOrder = async (
  uid: string
): Promise<{
  purchaseOrder: PurchaseOrderModel;
}>

Parameter	Type	Req?	Description
uid	string	Yes	See function signature above

Events

Does not emit any drop-in events.

Returns

Returns Promise<{ purchaseOrder: PurchaseOrderModel; }>. See PurchaseOrderModel.

---

getPurchaseOrderApprovalRule

Retrieves a specific purchase order approval rule by its unique identifier. This function fetches detailed information about an approval rule including its configuration, applicable roles, approval conditions, and approvers.

const getPurchaseOrderApprovalRule = async (
  id: string
): Promise<PurchaseOrderApprovalRuleModel>

Parameter	Type	Req?	Description
id	string	Yes	See function signature above

Events

Does not emit any drop-in events.

Returns

Returns PurchaseOrderApprovalRuleModel.

---

getPurchaseOrderApprovalRuleMetadata

Gets the current user’s purchase order approval rule metadata.

const getPurchaseOrderApprovalRuleMetadata = async (): Promise<PurchaseOrderApprovalRuleMetadataModel>

Events

Does not emit any drop-in events.

Returns

Returns PurchaseOrderApprovalRuleMetadataModel.

---

getPurchaseOrderApprovalRules

Gets the current user’s purchase order approval rules with pagination support.

const getPurchaseOrderApprovalRules = async (
  currentPage: number = DEFAULT_PAGE_INFO.currentPage,
  pageSize: number = DEFAULT_PAGE_INFO.pageSize
): Promise<{
  totalCount: number;
  pageInfo: {
    currentPage: number;
    pageSize: number;
    totalPages: number;
  };
  items: PurchaseOrderApprovalRuleModel[];
}>

Parameter	Type	Req?	Description
currentPage	number	No	See function signature above
pageSize	number	No	See function signature above

Events

Does not emit any drop-in events.

Returns

Returns Promise<{ totalCount: number; pageInfo: { currentPage: number; pageSize: number; totalPages: number; }; items: PurchaseOrderApprovalRuleModel[]; }>. See PurchaseOrderApprovalRuleModel.

---

getPurchaseOrders

Gets a list of purchase orders with optional filtering and pagination.

const getPurchaseOrders = async (
  filter?: any,
  pageSize: number = 20,
  currentPage: number = 1
): Promise<{
  totalCount: number;
  pageInfo: {
    currentPage: number;
    pageSize: number;
    totalPages: number;
  };
  purchaseOrderItems: PurchaseOrderModel[];
}>

Parameter	Type	Req?	Description
filter	any	No	See function signature above
pageSize	number	No	See function signature above
currentPage	number	No	See function signature above

Events

Does not emit any drop-in events.

Returns

Returns Promise<{ totalCount: number; pageInfo: { currentPage: number; pageSize: number; totalPages: number; }; purchaseOrderItems: PurchaseOrderModel[]; }>. See PurchaseOrderModel.

---

placeOrderForPurchaseOrder

Places an order from an approved purchase order.

const placeOrderForPurchaseOrder = async (
  purchaseOrderUid: string
): Promise<CustomerOrderModel>

Parameter	Type	Req?	Description
purchaseOrderUid	string	Yes	See function signature above

Events

Does not emit any drop-in events.

Returns

Returns CustomerOrderModel.

---

placePurchaseOrder

Places a purchase order from a cart.

const placePurchaseOrder = async (
  cartId: string
): Promise<{ purchaseOrder: PurchaseOrderModel }>

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 purchase-order/placed event.

Returns

Returns { purchaseOrder: PurchaseOrderModel }. See PurchaseOrderModel.

---

rejectPurchaseOrders

Rejects one or more purchase orders.

const rejectPurchaseOrders = async (
  uids: string | string[]
): Promise<{
  errors: { message: string; type: string }[];
  purchaseOrders: PurchaseOrderModel[];
}>

Parameter	Type	Req?	Description
uids	string | string[]	Yes	See function signature above

Events

Does not emit any drop-in events.

Returns

Returns Promise<{ errors: { message: string; type: string }[]; purchaseOrders: PurchaseOrderModel[]; }>. See PurchaseOrderModel.

---

updatePurchaseOrderApprovalRule

Updates an existing purchase order approval rule.

const updatePurchaseOrderApprovalRule = async (
  input: any
): Promise<PurchaseOrderApprovalRuleModel>

Parameter	Type	Req?	Description
input	any	Yes	Input parameters for the operation.

Events

Does not emit any drop-in events.

Returns

Returns PurchaseOrderApprovalRuleModel.

---

validatePurchaseOrders

Validates one or more purchase orders.

const validatePurchaseOrders = async (
  uids: string | string[]
): Promise<{
  errors: { message: string; type: string }[];
  purchaseOrders: PurchaseOrderModel[];
}>

Parameter	Type	Req?	Description
uids	string | string[]	Yes	See function signature above

Events

Does not emit any drop-in events.

Returns

Returns Promise<{ errors: { message: string; type: string }[]; purchaseOrders: PurchaseOrderModel[]; }>. See PurchaseOrderModel.

---

Data Models

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

CartModel

The CartModel object is returned by the following functions: addPurchaseOrderItemsToCart.

interface CartModel {
  cart: {
    id: string;
    items: {
      uid: string;
      quantity: number;
      product: {
        uid: string;
        name: string;
        sku: string;
      };
    }[];
    pagination?: {
      currentPage: number;
      pageSize: number;
      totalPages: number;
      totalCount: number;
    };
  };
  userErrors: Array<{
    message: string;
  }>;
}

CustomerOrderModel

The CustomerOrderModel object is returned by the following functions: placeOrderForPurchaseOrder.

interface CustomerOrderModel {
  appliedCoupons: Coupon[];
  appliedGiftCards: GiftCard[];
  availableActions: string[];
  billingAddress: CustomerAddress;
  carrier: string;
  comments: string[];
  creditMemos: any[];
  customerInfo: CustomerInfo;
  email: string;
  giftMessage: string;
  giftReceiptIncluded: boolean;
  giftWrapping: any;
  id: string;
  invoices: any[];
  isVirtual: boolean;
  items: OrderItem[];
  itemsEligibleForReturn: any[];
  number: string;
  orderDate: string;
  orderStatusChangeDate: string;
  paymentMethods: PaymentMethod[];
  printedCardIncluded: boolean;
  returns: any;
  shipments: Shipment[];
  shippingAddress: CustomerAddress;
  shippingMethod: string;
  status: string;
  token: string;
  total: OrderTotal;
}

PurchaseOrderApprovalRuleMetadataModel

The PurchaseOrderApprovalRuleMetadataModel object is returned by the following functions: getPurchaseOrderApprovalRuleMetadata.

interface PurchaseOrderApprovalRuleMetadataModel {
  availableAppliesTo: CompanyRole[];
  availableRequiresApprovalFrom: CompanyRole[];
}

PurchaseOrderApprovalRuleModel

The PurchaseOrderApprovalRuleModel object is returned by the following functions: createPurchaseOrderApprovalRule, getPurchaseOrderApprovalRule, getPurchaseOrderApprovalRules, updatePurchaseOrderApprovalRule.

interface PurchaseOrderApprovalRuleModel {
  createdAt: string;
  createdBy: string;
  description: string;
  updatedAt: string;
  name: string;
  status: string;
  uid: string;
  appliesToRoles: {
    id: string;
    name: string;
    usersCount: number;
    permissions: Array<{
      id: string;
      sortOrder: number;
      text: string;
    }>;
  }[];
  condition: {
    attribute: string;
    operator: string;
    quantity: number;
    amount: {
      currency: string;
      value: number;
    };
  };
  approverRoles: {
    id: string;
    name: string;
    usersCount: number;
    permissions: Array<{
      id: string;
      sortOrder: number;
      text: string;
    }>;
  }[];
}

PurchaseOrderCommentModel

The PurchaseOrderCommentModel object is returned by the following functions: addPurchaseOrderComment.

interface PurchaseOrderCommentModel {
  createdAt: string;
  text: string;
  uid: string;
  author: {
    allowRemoteShoppingAssistance: boolean;
    confirmationStatus: string;
    createdAt: string;
    dateOfBirth: string;
    email: string;
    firstname: string;
    gender: number;
    jobTitle: string;
    lastname: string;
    middlename: string;
    prefix: string;
    status: string;
    structureId: string;
    suffix: string;
    telephone: string;
  };
}

PurchaseOrderModel

The PurchaseOrderModel object is returned by the following functions: approvePurchaseOrders, cancelPurchaseOrders, getPurchaseOrder, getPurchaseOrders, placePurchaseOrder, rejectPurchaseOrders, validatePurchaseOrders.

interface PurchaseOrderModel {
  typename: string;
  uid: string;
  number: string;
  status: string;
  availableActions: string[];
  approvalFlow:
    | {
        ruleName: string;
        events: Array<{
          message: string;
          name: string;
          role: string;
          status: string;
          updatedAt: string;
        }>;
      }[]
    | [];
  comments?: Array<{
    uid: string;
    createdAt: string;
    author: {
      firstname: string;
      lastname: string;
      email: string;
    };
    text: string;
  }>;
  createdAt: string;
  updatedAt: string;
  createdBy: {
    firstname: string;
    lastname: string;
    email: string;
  };
  historyLog?: Array<{
    activity: string;
    createdAt: string;
    message: string;
    uid: string;
  }>;
  quote: QuoteProps | null;
  order: {
    orderNumber: string;
    id: string;
  };
}