Product

The Unified Data Layer provides methods that let you query products, fetch product details, and manage product reviews

Coverage

The following table provides an overview of the methods and their coverage across different platforms.

Method	Commercetools	SAPCC	BigCommerce	SFCC	Magento
`getProducts`	✅	✅	✅	✅	✅
`searchProducts`	✅	✅	✅	✅	✅
`getProductDetails`	✅	✅	✅	✅	✅
`getProductReviews`	✅	✅	✅	❌	✅

getProducts

The getProducts method retrieves a list of specific products based on product ids and/or skus and returns a list of SfProductCatalogItem objects.

Usage

const { products } = await sdk.unified.getProducts({
  ids: ["PRODUCT-ID"],
});

Type

export type GetProducts = (args: GetProductsArgs) => Promise<{
  products: SfProductCatalogItem[];
}>;

export type GetProductsArgs = {
  ids?: string[];
  skus?: string[];
};

type SfProductCatalogItem {
  id: SfId;
  sku: Maybe<string>;
  name: Maybe<string>;
  slug: string;
  price: Maybe<SfDiscountablePrice>;
  primaryImage: Maybe<SfImage>;
  rating: Maybe<{
    average: number;
    count: number;
  }>;
  quantityLimit: Maybe<number>;
}

searchProducts

The searchProducts method, in opposite to getProducts method, is dedicated for use cases when user wants to search for products that match a category, certain facets, or a search string. This method is used in the Alokai Storefront for the category pages and for showing search results.

Usage

When using searchProducts, you can query products using a category, facets, or a search string. When multiple search filters are passed, the result will contain the products that match all of the search criteria.

// search using category
const { products } = await sdk.unified.searchProducts({
  category: "CATEGORY_ID",
});

// search using facets
const { products } = await sdk.unified.searchProducts({
  facets: {
    color: ["black", "grey"],
  },
});

// search using a text string
const { products } = await sdk.unified.searchProducts({
  search: "custom search query",
});

// search for black t-shirts
const { products } = await sdk.unified.searchProducts({
  category: "T-SHIRTS",
  facets: {
    color: ["black"],
  },
});

Pagination

To handle pagination of the search results, you can use the currentPage and pageSize arguments to determine which products should be returned from your search.

If no pageSize argument is passed, the itemsPerPage value from your middleware configuration will be used.

const { products, pagination, facets } = await sdk.unified.searchProducts({
  pageSize: 25, // overrides itemsPerPage value from middleware.config.ts
  currentPage: 2,
  facets: {
    color: ["black", "grey"],
  },
});

Sorting

The sortBy argument can be used to sort the paginated results. If no sortBy argument is passed, the search will default to sorting by relevance. You can also pass in an arbitary string and that string will be passed through to the backend.

const { products, pagination } = await sdk.unified.searchProducts({
  category: 'CATEGORY_ID' // id of the desired category
  sortBy: 'price-low-to-high'
})

const { products, pagination } = await sdk.unified.searchProducts({
  category: 'CATEGORY_ID' // id of the desired category
  sortBy: 'custom-sort'
})

You can adjust the sorting options to your needs by overriding the SfSortBy interface using declaration merging. Take a look at this example:

/**
 * place this code in udm.d.ts file in your frontend app directory
 * and assure that file is in "include" scope of your TSConfig
 **/

declare module "@vsf-enterprise/unified-api-<integration>" {
  export interface SfSortBy {
    sortBy?: "relevant" | "from-a-to-z" | "from-z-to-a";
  }
}

Type

type SearchProducts = (args: SearchProductsArgs) => Promise<{
  products: SfProductCatalogItem[];
  pagination: SfPagination;
  facets: SfFacet[];
  currentCategory: Maybe<SfCategory>;
  subCategories: SfCategory[];
  categoryHierarchy: SfCategory[];
}>;

export interface SfSortBy {}

type SearchProductsArgs = {
  pageSize?: number;
  currentPage?: number;
  sortBy?:
    | "relevant"
    | "price-low-to-high"
    | "price-high-to-low"
    | (string & {});
  search?: string;
  category?: SfCategory["id"];
  facets?: {
    [name: string]: string[];
  };
} & SfSortBy;

getProductDetails

getProductDetails fetches the details of a single product using either its identifier or SKU.

It returns an SfProduct object containing detailed product data, and a list of SfCategory objects denoting the category hierarchy of the product.

In comparison to getProducts, the data returned from getProductDetails contains additional information that will likely only be needed on things like individual product pages. This data includes the different variants of a product, its entire image gallery, description, and attributes.

Usage

// fetching by id
const { products, categoryHeirarchy } = sdk.unified.getProductDetails({
  id: "product-id",
});

// fetching by id and SKU
const { products, categoryHeirarchy } = sdk.unified.getProductDetails({
  id: "product-id",
  sku: "product-sku",
});

Type

export type GetProductDetails = (args: GetProductDetailsArgs) => Promise<{
  product: SfProduct;
  categoryHierarchy: SfCategory[];
}>;

export type GetProductDetailsArgs = {
  id: SfId;
  sku?: string;
};

export interface SfProduct {
  id: SfId;
  sku: Maybe<string>;
  name: Maybe<string>;
  slug: string;
  description: Maybe<string>;
  price: Maybe<SfDiscountablePrice>;
  primaryImage: Maybe<SfImage>;
  gallery: SfImage[];
  rating: Maybe<{
    average: number;
    count: number;
  }>;
  variants: SfProductVariant[];
  attributes: SfAttribute[];
  /*
   * Maximum available quantity for product, null if unlimited
   */
  quantityLimit: Maybe<number>;
}

getProductReviews

This method is not available for Salesforce Commerce Cloud

getProductReviews retrieves reviews associated with a specific product using that product's id. The method returns a list of SfProductReview objects and pagination data.

Usage

pageSize must be set.

If not passed, the pageSize will default to 0 - meaning that no product reviews are returned.

const { reviews, pagination } = await sdk.unified.getProductReviews({
  productId: "product-id",
  pageSize: 10,
  currentPage: 0,
});

Types

export type GetProductReviews = (args: GetProductReviewsArgs) => Promise<{
  reviews: SfProductReview[];
  pagination: SfPagination;
}>;

export type GetProductReviewsArgs = {
  productId: SfId;
  pageSize?: number;
  currentPage?: number;
};

export interface SfProductReview {
  id: SfId;
  title: Maybe<string>;
  text: Maybe<string>;
  rating: Maybe<number>;
  /*
   * Name of the reviewer (Full name or nickname)
   */
  reviewer: Maybe<string>;
  /*
   * Creation date in ISO 8601 format
   */
  createdAt: string;
}