Products

Use this module for product grids, product pages, and product discovery.

Methods

Get

Use: products.get(slugOrPath, options?).

Returns: SazitoResponse<Product>.

Accepts a slug or full product path and returns the detail product. All images and attributes (including description and SEO) are available here. themeConfig is absent when the product has no custom page. Images, variants, and categories preserve the API's null versus [] values. taxonomy is present when the store assigned a taxonomy category or specification metafields to the product; see Taxonomy and specification table.

List

Use: products.list(filters?, options?).

Returns: SazitoResponse<PaginatedResponse<ProductListItem>>.

items contains ProductListItem objects intended for product cards. Fetch products.get() for categories, custom page configuration, description and SEO attributes, and variant SKUs.

Search

Use: products.search(query, filters?, options?).

Returns: SazitoResponse<SearchResponse>.

Product hits use the same ProductListItem shape as lists, with a two-image default. See Search for the other result groups.

Response key fields

ProductListItem

Card attributes exclude description, metaTitle, metaDescription, metaKeywords, focusKeyphrase, redirect, canonical, noindex, and id. These attributes are available on the detail product.

Product

Images and optional fields

List images default to the first two images plus any images referenced by variants, in the original order. A list item can return more than two images. Use imageCount for the total number of product images. Details return all images; count their images collection when it is present.

products.list() always uses this default; ProductFilters has no image-limit option. The server returns at most 100 items per page, regardless of pageSize.

import type { ProductListItem } from '@sazito/client-sdk';

function cardImages(product: ProductListItem) {
  const images = product.images ?? [];
  return {
    coverUrl: images[0]?.url,
    totalImages: product.imageCount,
    remainingImages: Math.max(0, product.imageCount - images.length),
  };
}

The array fallback above is for presentation. The SDK preserves null and [] as returned by the API. themeConfig is absent when a detail product has no custom page; use optional access when reading it.

Product images expose id, alt, url, width, and height. Use url to display an image and positive dimensions to calculate an aspect ratio.

Variants, pricing, and categories

Use variant.price for the final price, including gold-pricing adjustments. originalPrice is the raw price when present. Gold component breakdowns, shipping weight, download links, and timestamps are not part of storefront variants. Product timestamps and tags are not part of storefront products.

A variant contains its own attributes and identifiers. Read the product's name and URL from the surrounding Product or ProductListItem.

Detail categories provide id, name, and url for breadcrumbs. To get a category's description or product count, resolve its URL through Entity Routes.

Taxonomy and specification table

product.taxonomy carries the store's taxonomy assignment for the product: the taxonomy category path and the specification table ("ویژگی‌ها") shown on product pages. It is absent when the product has neither a taxonomy category nor specification metafields. Product lists, search hits, and entity routes never include it.

Taxonomy terms expose a string id, a Persian name, and enName when the taxonomy provides an English name. Taxonomy identifiers are separate from storefront category IDs, and breadcrumb entries carry no storefront URL. features skips metafields without an attribute name or without values, joins several values with ، , and drops duplicate rows. Read metafields when you need the identifiers, for example to build filters or structured data.

import type { Product } from '@sazito/client-sdk';

function specificationTable(product: Product) {
  const taxonomy = product.taxonomy;
  if (!taxonomy || taxonomy.features.length === 0) return null;

  return {
    categoryPath: taxonomy.categoryPath,
    rows: taxonomy.features.map(({ label, value }) => ({ label, value })),
  };
}

Dynamic forms

Fetch the form definition when rendering a product form. Use the selected variant's dynamicFormId, falling back to the product's ID when absent:

import { createSazitoClient } from '@sazito/client-sdk';

const client = createSazitoClient({ domain: 'mystore.sazito.com' });
async function loadProductForm(slug: string, variantId: number) {
  const response = await client.products.get(slug);
  if (response.error) return response;

  const product = response.data;
  const variant = product.variants?.find((item) => item.id === variantId);
  const formId = variant?.dynamicFormId ?? product.dynamicFormId;

  if (formId === undefined || formId <= 0) return null;
  return client.dynamicForms.getForm(formId);
}

const formResponse = await loadProductForm('shoe-123', 12001);
// null means no form; otherwise handle formResponse.data or formResponse.error.

See Dynamic Forms for form fields and uploads.

SDK response fields

Product lists return items, total, page, pageSize, and totalPages inside data. products.get() returns the detail product as data, including variant SKUs and taxonomy when present. Use the exported SDK types and camelCase field names when rendering product data.

Attribute values and colors

ProductAttribute.value is either a display string or a rich ProductAttributeValueObject. For color attributes, fieldType is usually 'color' and extra contains the color payload, commonly a hex value such as '#ff0000'. The same normalized attribute shape is used by cart, invoice, order, and checkout responses.

Import these types directly from the package in your application:

import type {
  Product,
  ProductListItem,
  ProductVariant,
  ProductTaxonomy,
  ProductAttribute,
  ProductAttributeValueObject
} from '@sazito/client-sdk';

For the full list of SDK types, see TypeScript types.

Known errors

Examples

// app/lib/sazito-client.ts
import { createSazitoClient } from '@sazito/client-sdk';

export const sazito = createSazitoClient({
  domain: process.env.NEXT_PUBLIC_SAZITO_DOMAIN!,
});

// app/[lang]/(home)/page.tsx
'use client';
import { useEffect, useState } from 'react';
import { sazito } from '@/app/lib/sazito-client';

export default function Example() {
  const [data, setData] = useState<any>(null);

  useEffect(() => {
    sazito.products.list({ page: 1, pageSize: 12 }).then((res) => setData(res.data ?? null));
  }, []);

  return <pre>{JSON.stringify(data, null, 2)}</pre>;
}

Type Details

The following tables are generated from SDK TypeScript types and include nested object fields.

ProductFilters

Source: src/types/product.ts

ProductListItem

Source: src/types/product.ts

ProductListVariant

Source: src/types/product.ts

Product

Source: src/types/product.ts

ProductVariant

Source: src/types/product.ts

ProductBreadcrumbCategory

Source: src/types/product.ts

ProductTaxonomy

Source: src/types/product.ts

ProductTaxonomyTerm

Source: src/types/product.ts

ProductTaxonomyMetafield

Source: src/types/product.ts

ProductTaxonomyFeature

Source: src/types/product.ts

ProductCategory

Source: src/types/product.ts

ProductAttribute

Source: src/types/common.ts

ProductAttributeValueObject

Source: src/types/common.ts

ProductImage

Source: src/types/product.ts

SearchResponse

Source: src/types/search.ts