Requisition List Functions

The Requisition List drop-in provides API functions for managing lists and their items. Use them to create and update lists, manage products, share lists with company colleagues, and share public lists by email or link.

Function	Description
addProductsToRequisitionList	Adds products to a requisition list.
addRequisitionListItemsToCart	Adds the chosen items from a requisition list to the logged-in user’s cart.
copyItemsBetweenRequisitionLists	Copies items from one requisition list to another for a logged-in user.
createRequisitionList	Creates a new requisition list with the name and description provided for the logged-in user.
deleteRequisitionList	Deletes a requisition list identified by UID.
deleteRequisitionListItems	Deletes items from a requisition list.
enrichConfigurableProducts	Resolves the selected variants for configurable product items.
getRequisitionList	Returns information about the requested requisition list for the logged-in user.
getRequisitionLists	Returns the requisition lists for the logged-in user.
getStoreConfig	Returns details about the store configuration.
moveItemsBetweenRequisitionLists	Moves items from one requisition list to another for a logged-in user.
updateRequisitionList	Updates an existing requisition list with the name and description provided for the logged-in user.
updateRequisitionListItems	Updates the items of an existing requisition list with the quantity and options provided for the logged-in user.
getCompanyUsers	Returns a list of active company users for the current company.
getSharedRequisitionList	Retrieves a shared requisition list by its share token.
importSharedRequisitionList	Imports a shared requisition list into the current customer’s account using a share token.
shareRequisitionListByEmail	Shares a requisition list with one or more company users by email.
shareRequisitionListByToken	Generates a shareable token for a requisition list.
getPublicRequisitionList	Retrieves a public requisition list by its share token, without requiring authentication.
getPublicRequisitionListToken	Retrieves the owner’s reusable public share token for a requisition list.
sharePublicRequisitionList	Emails the public share link of a requisition list to any email addresses.
addPublicRequisitionListItemsToCart	Adds items from a public requisition list to a guest or customer cart.

addProductsToRequisitionList

Adds products to a requisition list.

const addProductsToRequisitionList = async (
  requisitionListUid: string,
  requisitionListItems: Array<RequisitionListItemsInput>
): Promise<RequisitionList | null>

Parameter	Type	Req?	Description
requisitionListUid	string	Yes	The unique identifier for the requisition list to which products will be added.
requisitionListItems	Array<RequisitionListItemsInput>	Yes	An array of product objects to add to the requisition list. Each object includes the product SKU, quantity, and optional configuration like parent SKU for configurable products, selected options (color, size), and entered options (custom text fields).

Events

Emits the requisitionList/data event.

Returns

Returns RequisitionList or null.

addRequisitionListItemsToCart

Adds the chosen items from a requisition list to the logged-in user’s cart.

const addRequisitionListItemsToCart = async (
  requisitionListUid: string,
  requisitionListItemUids: Array<string>
): Promise<Array<AddToCartError> | null>

Parameter	Type	Req?	Description
requisitionListUid	string	Yes	The unique identifier for the requisition list containing the items to add to the cart.
requisitionListItemUids	Array<string>	Yes	An array of requisition list item UIDs to add to the cart. These are the unique identifiers for specific items within the list, not product SKUs.

Events

Does not emit any drop-in events.

Returns

Returns Array<AddToCartError> | null.

createRequisitionList

Creates a new requisition list with the name and description provided for the logged-in user.

const createRequisitionList = async (
  name: string,
  description?: string,
  isPublic?: boolean
): Promise<RequisitionList | null>

Parameter	Type	Req?	Description
name	string	Yes	The display name for the new requisition list. This helps users identify and organize their lists (for example, Office Supplies Q1, Weekly Inventory Restock).
description	string	No	An optional text description providing additional context about the requisition list’s purpose or contents (for example, Monthly recurring orders for maintenance supplies).
isPublic	boolean	No	Marks the new list as public so that it can be shared with anyone by link or email. Use it only when requisition_list_public_sharing_enabled is true in the store configuration.

Events

Emits the requisitionList/data event.

Returns

Returns RequisitionList or null.

deleteRequisitionList

Deletes a requisition list identified by uid.

const deleteRequisitionList = async (
  requisitionListUid: string
): Promise<{
  items: RequisitionList[];
  page_info: any;
  status: any;
} | null>

Parameter	Type	Req?	Description
requisitionListUid	string	Yes	The unique identifier for the requisition list to delete. This operation is permanent and removes the list and all its items.

Events

Emits the requisitionLists/data event.

Returns

Promise<{
  items: RequisitionList[];
  page_info: any;
  status: any;
} | null>

See RequisitionList.

deleteRequisitionListItems

Deletes items from a requisition list.

const deleteRequisitionListItems = async (
  requisitionListUid: string,
  items: Array<string>,
  pageSize: number,
  currentPage: number,
  enrichConfigurableProducts?: (items: Item[]) => Promise<Item[]>
): Promise<RequisitionList | null>

Parameter	Type	Req?	Description
requisitionListUid	string	Yes	The unique identifier for the requisition list from which items will be removed.
items	Array<string>	Yes	An array of requisition list item UIDs to remove. These are the unique identifiers returned in the list’s items array, not product SKUs.
pageSize	number	Yes	The number of items to return per page in the updated requisition list response.
currentPage	number	Yes	The page number for pagination (1-indexed). Used to retrieve a specific page of items after deletion.
enrichConfigurableProducts	items: Item[]	No	See function signature above

Events

Emits the requisitionList/data event.

Returns

Returns RequisitionList or null.

enrichConfigurableProducts

Resolves the selected variants for configurable product items in a requisition list. The function uses each item’s selected option labels to retrieve the matching simple product so the item can display the selected variant’s SKU, price, and thumbnail.

const enrichConfigurableProducts = async (
  items: Item[]
): Promise<Item[]>

Parameter	Type	Req?	Description
items	Item[]	Yes	The requisition list items to enrich. Non-configurable items are returned unchanged.

Events

Does not emit any drop-in events.

Returns

Returns the items with selected configurable product details attached. See the RequisitionListItemModel.

getRequisitionList

Returns information about the requested requisition list for the logged-in user.

const getRequisitionList = async (
  requisitionListID: string,
  currentPage?: number,
  pageSize?: number,
  enrichConfigurableProducts?: (items: Item[]) => Promise<Item[]>
): Promise<RequisitionList | null>

Parameter	Type	Req?	Description
requisitionListID	string	Yes	The unique identifier for the requisition list to retrieve. Returns the list metadata and all items.
currentPage	number	No	The page number for pagination (1-indexed). Defaults to page 1 if not specified.
pageSize	number	No	The number of items to return per page. Controls pagination of the requisition list items.
enrichConfigurableProducts	items: Item[]	No	See function signature above

Events

Emits the requisitionList/data event.

Returns

Returns RequisitionList or null.

getRequisitionLists

Returns the requisition lists for the logged-in user.

const getRequisitionLists = async (
  currentPage?: number,
  pageSize?: number,
  listItemsPageSize?: number
): Promise<RequisitionList[] | null>

Parameter	Type	Req?	Description
currentPage	number	No	The page number for pagination (1-indexed). Used to navigate through multiple pages of requisition lists.
pageSize	number	No	The number of requisition lists to return per page. Controls how many lists appear on each page.
listItemsPageSize	number	No	Sets how many items are loaded per list in each GraphQL request. The default is 100. If a list has more than 100 items, additional requests are automatically made so users (like on a PDP “already on list” view) can see all items.

Events

Emits the requisitionLists/data event.

Returns

Returns an array of RequisitionList objects or null.

getStoreConfig

Returns details about the store configuration.

const getStoreConfig = async (): Promise<any>

Events

Does not emit any drop-in events.

Returns

Returns StoreConfig. If the configuration query returns errors or the request fails, the function returns the default configuration, in which every feature flag is off. If the backend does not support is_requisition_list_active or company_enabled, it returns false.

updateRequisitionList

Updates an existing requisition list with the name and description provided for the logged-in user.

const updateRequisitionList = async (
  requisitionListUid: string,
  name: string,
  description?: string,
  pageSize?: number,
  currentPage?: number,
  enrichConfigurableProducts?: (items: Item[]) => Promise<Item[]>,
  isPublic?: boolean
): Promise<RequisitionList | null>

Parameter	Type	Req?	Description
requisitionListUid	string	Yes	The unique identifier for the requisition list to update.
name	string	Yes	The new display name for the requisition list. Updates the list’s title.
description	string	No	The new text description for the requisition list. Updates the list’s purpose or context information.
pageSize	number	No	The number of items to return per page in the updated requisition list response.
currentPage	number	No	The page number for pagination (1-indexed) in the updated requisition list response.
enrichConfigurableProducts	items: Item[]	No	See function signature above
isPublic	boolean	No	Sets whether the list is public. Pass true to make the list public and false to make it private. Use it only when requisition_list_public_sharing_enabled is true in the store configuration. To set it, pass undefined for the optional parameters that come before it.

Events

Emits the requisitionList/data event.

Returns

Returns RequisitionList or null.

updateRequisitionListItems

Updates the items of an existing requisition list with the quantity and options provided for the logged-in user.

const updateRequisitionListItems = async (
  requisitionListUid: string,
  requisitionListItems: Array<UpdateRequisitionListItemsInput>,
  pageSize: number,
  currentPage: number,
  enrichConfigurableProducts?: (items: Item[]) => Promise<Item[]>
): Promise<RequisitionList | null>

Parameter	Type	Req?	Description
requisitionListUid	string	Yes	The unique identifier for the requisition list containing the items to update.
requisitionListItems	Array<UpdateRequisitionListItemsInput>	Yes	An array of requisition list items to update. Each object includes the item UID and the fields to modify (such as quantity, selected options, or entered options).
pageSize	number	Yes	The number of items to return per page in the updated requisition list response.
currentPage	number	Yes	The page number for pagination (1-indexed) in the updated requisition list response.
enrichConfigurableProducts	items: Item[]	No	See function signature above

Events

Emits the requisitionList/data event.

Returns

Returns RequisitionList or null.

moveItemsBetweenRequisitionLists

Moves items from one requisition list to another for a logged-in user.

const moveItemsBetweenRequisitionLists = async (
  sourceRequisitionListUid: string,
  destinationRequisitionListUid: string,
  requisitionListItemUids: string[],
  pageSize: number,
  currentPage: number
): Promise<MoveItemsResult | null>

Parameter	Type	Req?	Description
sourceRequisitionListUid	string	Yes	The unique identifier for the requisition list from which items will be moved.
destinationRequisitionListUid	string	Yes	The unique identifier for the requisition list to which items will be moved.
requisitionListItemUids	string[]	Yes	An array of requisition list item UIDs to move. These are the unique identifiers for specific items within the source list.
pageSize	number	Yes	The number of items to return per page in the updated requisition list responses.
currentPage	number	Yes	The page number for pagination (1-indexed) in the updated requisition list responses.

Events

Emits the requisitionList/data event for the source list after items are moved.

Returns

Returns an object with the following structure, or null if the operation fails:

interface MoveItemsResult {
  sourceList: RequisitionList | null;
  destinationList: RequisitionList | null;
}

• sourceList: The updated source requisition list after items have been moved, or null if not available.
• destinationList: The updated destination requisition list after items have been added, or null if not available.

copyItemsBetweenRequisitionLists

Copies items from one requisition list to another for a logged-in user.

const copyItemsBetweenRequisitionLists = async (
  sourceRequisitionListUid: string,
  destinationRequisitionListUid: string,
  requisitionListItemUids: string[]
): Promise<CopyItemsResult | null>

Parameter	Type	Req?	Description
sourceRequisitionListUid	string	Yes	The unique identifier for the requisition list from which items will be copied.
destinationRequisitionListUid	string	Yes	The unique identifier for the requisition list to which items will be copied.
requisitionListItemUids	string[]	Yes	An array of requisition list item UIDs to copy. These are the unique identifiers for specific items within the source list.

Events

Does not emit any drop-in events.

Returns

Returns an object with the following structure, or null if the operation fails:

interface CopyItemsResult {
  destinationList: RequisitionList | null;
}

• destinationList: The updated destination requisition list after items have been copied, or null if not available.

getCompanyUsers

Returns a list of active company users for the current company. Used to populate the recipient picker in the share-by-email flow.

const getCompanyUsers = async (): Promise<CompanyUser[]>

Events

Does not emit any drop-in events.

Returns

Returns an array of CompanyUser objects.

interface CompanyUser {
  id: string;
  firstname: string;
  lastname: string;
  email: string;
}

getSharedRequisitionList

Retrieves a shared requisition list by its share token. The caller must be authenticated and belong to the same company as the sender. Returns the sender’s display name alongside the read-only requisition list data.

const getSharedRequisitionList = async (
  token: string,
  currentPage?: number,
  pageSize?: number,
  enrichConfigurableProducts?: (items: Item[]) => Promise<Item[]>
): Promise<SharedRequisitionListResult | null>

Parameter	Type	Req?	Description
token	string	Yes	The share token from the URL (e.g. from ?requisition_id=<token>).
currentPage	number	No	The page number for pagination (1-indexed). Defaults to page 1 if not specified.
pageSize	number	No	The number of items to return per page.
enrichConfigurableProducts	(items: Item[]) => Promise<Item[]>	No	Optional function to enrich configurable product items with variant data before returning.

Events

Does not emit any drop-in events.

Returns

Returns SharedRequisitionListResult | null. Returns null if the token is valid but the requisition list cannot be resolved.

interface SharedRequisitionListResult {
  senderName: string;
  requisitionList: RequisitionList;
}

importSharedRequisitionList

Imports a shared requisition list into the current customer’s account using a share token. After a successful import, the recipient has full edit rights on the list.

const importSharedRequisitionList = async (
  token: string
): Promise<ImportSharedRequisitionListResult>

Parameter	Type	Req?	Description
token	string	Yes	The share token extracted from the URL (e.g. from ?requisition_id=<token>).

Events

Does not emit any drop-in events.

Returns

Returns ImportSharedRequisitionListResult.

interface ImportSharedRequisitionListResult {
  requisitionList: RequisitionList | null;
  userErrors: ImportSharedRequisitionListUserError[];
}

interface ImportSharedRequisitionListUserError {
  message: string;
  code: string;
}

shareRequisitionListByEmail

Shares a requisition list with one or more company users by email. An email notification is sent to each recipient with a link to import the list.

const shareRequisitionListByEmail = async (
  requisitionListUid: string,
  customerUids: string[]
): Promise<Array<ShareRequisitionListByEmailError> | null>

Parameter	Type	Req?	Description
requisitionListUid	string	Yes	The unique identifier of the requisition list to share.
customerUids	string[]	Yes	An array of company user IDs to share the list with. Obtain these from getCompanyUsers.

Events

Does not emit any drop-in events.

Returns

Returns null on success, or an array of error objects if the share failed.

interface ShareRequisitionListByEmailError {
  message: string;
  code: string;
}

shareRequisitionListByToken

Generates a shareable token for a requisition list. The token is used to build a share URL that recipients can open to import the list into their own account.

const shareRequisitionListByToken = async (
  requisitionListUid: string
): Promise<ShareRequisitionListByTokenResult>

Parameter	Type	Req?	Description
requisitionListUid	string	Yes	The unique identifier of the requisition list to generate a share token for.

Events

Does not emit any drop-in events.

Returns

Returns ShareRequisitionListByTokenResult.

interface ShareRequisitionListByTokenResult {
  token: string | null;
  errorMessage: string | null;
}

getPublicRequisitionList

Retrieves a public requisition list by its share token. Unlike getSharedRequisitionList, it does not require the caller to sign in or belong to a company. Anyone with the token can view the list.

Returns the owner’s display name and read-only list data. Each item includes its product name, thumbnail, and url_key.

const getPublicRequisitionList = async (
  token: string,
  currentPage?: number,
  pageSize?: number,
  enrichConfigurableProducts?: (items: Item[]) => Promise<Item[]>
): Promise<SharedRequisitionListResult | null>

Parameter	Type	Req?	Description
token	string	Yes	The public share token from the URL (for example, from ?requisition_id=<token>).
currentPage	number	No	The page number for pagination (1-indexed). Defaults to page 1 if not specified.
pageSize	number	No	The number of items to return per page.
enrichConfigurableProducts	(items: Item[]) => Promise<Item[]>	No	Optional function to enrich configurable product items with variant data before returning.

Events

Does not emit any drop-in events.

Returns

Returns SharedRequisitionListResult | null. Returns null if the response does not contain a requisition list. Throws an error if the server returns GraphQL errors, for example when the token is invalid or the list is no longer public.

interface SharedRequisitionListResult {
  senderName: string;
  requisitionList: RequisitionList;
}

getPublicRequisitionListToken

Retrieves the signed-in owner’s reusable public share token for a requisition list. The same token is used for the share link, the share email, and the add-to-cart action. Use it to build a public share link or to reopen the sharing modal.

const getPublicRequisitionListToken = async (
  requisitionListUid: string
): Promise<GetPublicRequisitionListTokenResult>

Parameter	Type	Req?	Description
requisitionListUid	string	Yes	The unique identifier of the requisition list to get the public share token for.

Events

Does not emit any drop-in events.

Returns

Returns GetPublicRequisitionListTokenResult. The function never throws. It catches GraphQL and network errors and returns them in errorMessage. The token is null when the list has no public token yet, for example when it is not marked public.

interface GetPublicRequisitionListTokenResult {
  token: string | null;
  errorMessage: string | null;
}

sharePublicRequisitionList

Emails a public requisition list’s share link to the specified recipients. Unlike shareRequisitionListByEmail, recipients do not need to be registered company users. Only the list owner can call this function.

const sharePublicRequisitionList = async (
  requisitionListUid: string,
  emails: string[]
): Promise<PublicRequisitionListUserError[] | null>

Parameter	Type	Req?	Description
requisitionListUid	string	Yes	The unique identifier of the public requisition list to share.
emails	string[]	Yes	The email addresses that receive the share link.

Events

Does not emit any drop-in events.

Returns

Returns null when the share succeeds. Otherwise returns an array of PublicRequisitionListUserError objects, for example with the code NOT_PUBLIC when the list is not marked public. Throws an error if the server returns GraphQL errors. If the response does not confirm that any emails were sent and contains no specific errors, the array contains an entry with the code UNKNOWN_ERROR.

interface PublicRequisitionListUserError {
  code: string;
  message: string;
}

addPublicRequisitionListItemsToCart

Adds items from a public requisition list to a cart. The function identifies the list by its share token and the cart by an explicit cart ID. Unlike addRequisitionListItemsToCart, it does not require authentication, so the cart can belong to a guest or a signed-in customer.

const addPublicRequisitionListItemsToCart = async (
  token: string,
  cartId: string,
  itemUids?: string[]
): Promise<AddPublicRequisitionListItemsToCartResult>

Parameter	Type	Req?	Description
token	string	Yes	The public share token of the requisition list.
cartId	string	Yes	The ID of the cart that receives the items.
itemUids	string[]	No	The UIDs of the list items to add. Omit this parameter to add every item in the list.

Events

Does not emit any drop-in events.

Returns

Returns AddPublicRequisitionListItemsToCartResult. An empty userErrors array means every item was added. Possible error codes include NOT_PUBLIC, INVALID_TOKEN, and OUT_OF_STOCK. Throws an error if the server returns GraphQL errors. If the response does not include the mutation result, userErrors contains an entry with the code UNKNOWN_ERROR.

interface AddPublicRequisitionListItemsToCartResult {
  cart: { id: string } | null;
  userErrors: PublicRequisitionListUserError[];
}

The following example adds only the selected items to a cart:

import { addPublicRequisitionListItemsToCart } from '/@dropins/storefront-requisition-list/api.js';

const { userErrors } = await addPublicRequisitionListItemsToCart(
  'abc123token',
  cartId,
  ['item-uid-1', 'item-uid-2']
);

if (userErrors.length > 0) {
  userErrors.forEach(({ code, message }) => console.error(code, message));
}

Data Models

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

RequisitionList

The RequisitionList object is returned by the following functions: addProductsToRequisitionList, createRequisitionList, deleteRequisitionList, deleteRequisitionListItems, getRequisitionList, getRequisitionLists, updateRequisitionList, updateRequisitionListItems, moveItemsBetweenRequisitionLists, copyItemsBetweenRequisitionLists.

interface RequisitionList {
  uid: string;
  name: string;
  description: string;
  updated_at: string;
  items_count: number;
  items: Item[];
  page_info?: PageInfo;
  is_public?: boolean;
}

StoreConfig

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

interface StoreConfig {
  is_requisition_list_active?: string;
  company_enabled?: boolean;
  requisition_list_sharing_enabled?: boolean;
  requisition_list_share_max_recipients?: number | null;
  requisition_list_share_storefront_path?: string | null;
  configurable_thumbnail_source?: string | null;
  requisition_list_public_sharing_enabled?: boolean;
  requisition_list_public_share_link_validity_days?: number | null;
  requisition_list_public_share_max_recipients?: number | null;
  requisition_list_public_share_storefront_path?: string | null;
  [key: string]: any;
}