Product data

Read this when you build a product page, a card or a slider and need to know what a Product looks like and which fields can be missing.

The type is Product from @salla.sa/twilight-theme-engine/types. Prices are numbers in the store's currency. The fields on this page match what the demo store's API returns today; names in the examples are translated to English.

Where products come fromCopy Anchor Link

A Product reaches your code in three ways. They are the same type but not the same data.

useProduct adds no fields. When the customer picks options it replaces price, sale_price, regular_price, is_on_sale, weight, sku and barcode, clears starting_price and sets is_out_of_stock, and reload() swaps in a fresh detail object. Pass { isPreview: true } while you only have a list item, so the hook re-seeds when the detail arrives.

ProductCard takes a Product (list item or detail). The product page puts the detail object in the loader data as product. ProductContextProvider and useProductContext() from @salla.sa/twilight-theme-engine/contexts share one product down your component tree: useProductContext() returns { product }, or null outside a provider. HookSlot does not read it, so a slot handler gets the product only through the slot's context.

Read a product in a componentCopy Anchor Link

import { useProduct } from '@salla.sa/twilight-theme-engine/hooks/useProduct';
import { useMoney } from '@salla.sa/twilight-theme-engine/hooks/useMoney';
import type { Product } from '@salla.sa/twilight-theme-engine/types';

export function ProductSummary({ initial }: { initial: Product }) {
  const { product } = useProduct(initial);
  const { format } = useMoney();

  return (
    <div>
      <img src={product.image?.url} alt={product.image?.alt ?? product.name} />
      <h1>{product.name}</h1>
      {product.is_on_sale ? (
        <p>
          <strong>{format(product.sale_price ?? product.price)}</strong> <s>{format(product.regular_price)}</s>
        </p>
      ) : (
        <p>{format(product.price)}</p>
      )}
      {product.is_out_of_stock && <p>Out of stock</p>}
    </div>
  );
}

Example: a simple product on saleCopy Anchor Link

The detail object of a product with no options, on sale (trimmed: description and images are shortened, images has 2 of its items).

Example: a product with optionsCopy Anchor Link

The demo product "Light": one color option, a SKU per value, a 3D main image, and a starting_price lower than price.

A list item for the same kind of product is much smaller. Here is the real list item of a product with variants (description removed). Note the string ids, sale_price: null, the single image, and has_options instead of options.

Field referenceCopy Anchor Link

The tables are generated from Product in @salla.sa/twilight-theme-engine/types. "Detail" means the field is reliably present only on product.find. Nested objects (images, options, SKUs, category, brand) get their own tables. Prices on Product are plain numbers in currency; use useMoney().format to display them. For the { amount, currency } object, see shared types.

ProductCopy Anchor Link

ratingCopy Anchor Link

categoryCopy Anchor Link

category.sub_categoriesCopy Anchor Link

brandCopy Anchor Link

tagsCopy Anchor Link

imageCopy Anchor Link

imagesCopy Anchor Link

Same fields as image.

optionsCopy Anchor Link

options.valuesCopy Anchor Link

options.detailsCopy Anchor Link

skusCopy Anchor Link

skus.priceCopy Anchor Link

skus.regular_priceCopy Anchor Link

Same fields as skus.price.

skus.sale_priceCopy Anchor Link

Same fields as skus.price.

notify_availabilityCopy Anchor Link

donationCopy Anchor Link

Allowed values and detail-only flagsCopy Anchor Link

type is one of product, service, group_products, codes, digital, food, donating, booking or financial_support. status is one of sale, out, out-and-notify or hidden. An option's type is text, textarea, radio, checkbox, select, image or color; the demo store also sends thumbnail and single-option. has_options is true on list items and is not on the detail object, so check options?.length on a detail.

What useProduct returnsCopy Anchor Link

Variants by product typeCopy Anchor Link

The engine has no separate type per kind of product. It reads type and these fields:

Common tasksCopy Anchor Link

Show the discount percentageCopy Anchor Link

function discountPercent(product: Product): number {
  if (!product.is_on_sale || !product.regular_price) return 0;
  return Math.round((1 - Number(product.price) / product.regular_price) * 100);
}

For regular_price: 199 and price: 188 it returns 6. Merchants often type the same text in promotion_title, so the badge below may already say it.

Is it in stock?Copy Anchor Link

const { product } = useProduct(initial);
const canBuy = product.is_available && !product.is_out_of_stock;

useProduct flips is_out_of_stock when the SDK reports that the chosen option combination is not available.

To show a stock message, treat quantity === -1 as unlimited:

const unlimited = product.quantity === -1;
const remaining = product.can_show_remained_quantity && !unlimited ? product.quantity : null;

Which variant is selected?Copy Anchor Link

The product object does not store the customer's choice. Keep the chosen value ids yourself (from your option inputs), then find the SKU:

import type { Product } from '@salla.sa/twilight-theme-engine/types';

function findSku(product: Product, selectedValueIds: number[]) {
  return product.skus?.find(
    (sku) =>
      sku.related_option_values.length === selectedValueIds.length &&
      selectedValueIds.every((id) => sku.related_option_values.includes(id))
  );
}

Then sku.price.amount is the price of that variant and sku.stock_quantity its stock (null means unlimited).

Image gallery URLsCopy Anchor Link

const urls = product.images?.map((img) => img.url) ?? [product.image?.url];
const main = product.images?.find((img) => img.main)?.url ?? product.image?.url;

Check type before you render an item as <img>: it can be a video (video_url) or a 3D image (three_d_image_url).

Show the badgeCopy Anchor Link

There is no badge field. The card chooses one text in this order: preorder.label, promotion_title, then (with withQuantity) the remaining quantity, then the out-of-stock label.

const badge = (typeof product.preorder?.label === 'string' && product.preorder.label) || product.promotion_title || null;

Digital, booking and donationCopy Anchor Link

if (product.type === 'donating' && product.donation) {
  const { collected_amount, target_amount, target_percent, can_donate } = product.donation;
}
const needsShipping = product.is_require_shipping;
const fixedQuantity = product.type === 'booking' || product.is_hidden_quantity;

GotchasCopy Anchor Link

• Ids differ by source. Lists send string ids, detail sends numbers, but the type says number. Compare with String(a.id) === String(b.id), and pass Number(product.id) to useWishlist.
• sale_price when there is no sale. With no sale it can be null, 0 or equal to price. Branch on is_on_sale, not on sale_price.
• Prices are numbers on Product but { amount, currency } objects on skus[] (and base_currency_price). See shared types.
• null, empty and missing all happen. promotion_title can be "" or null; rating is null without reviews; list items leave out whole sections. Use optional chaining and ?? [].
• options can be [] on a product without options, not missing. Check .length.
• List items are partial. image has no alt; category.url, brand.url and tags[].url can be null; quantity and max_quantity are null; is_hidden_quantity is spelled is_hidded_quantity.
• description is HTML written by the merchant. Render it with dangerouslySetInnerHTML, and pass it through stripUnsafeHtml from @salla.sa/twilight-theme-engine/utils first. List items from the API may have it HTML-escaped (<p>), so use the detail description on a product page.
• Live changes are browser-only. On the server useProduct returns exactly the product you passed.

NextCopy Anchor Link

• useProduct and ProductCard
• product API module for find, list and the query keys
• Product route
• Shared types for Money and friends