Store data

Read this page when you need to know what the store object looks like: which fields exist, which can be missing, and where to find things like languages and currencies.

Where you read itCopy Anchor Link

There are two ways to get the same store object.

The engine loads the store once per request from the store/settings API and hands it to the provider at the root of your app. It is available in server rendering and in the browser, from the first render.

Languages and currencies are not inside the store object. They come from the same API response and you read them from useTwilight().settings (see Common tasks). The theme object is covered in Theme data.

import { useStore } from '@salla.sa/twilight-theme-engine/hooks/useStore';

export function StoreBadge() {
  const { name, logo, url, contacts, settings } = useStore();

  return (
    <a href={url}>
      <img src={logo} alt={name} />
      {contacts.email && <span>{contacts.email}</span>}
      {settings.rating_enabled && <span>Rated by customers</span>}
    </a>
  );
}

The full objectCopy Anchor Link

This is the store of the public demo store 1510890315, shortened: long arrays are cut to a few items and long strings are trimmed. Search it, expand what you need, and click a key to copy its path. Notes sit next to the less obvious fields.

FieldsCopy Anchor Link

The tables below are generated from the engine's Store type. Nested objects get their own table, named by their path (settings.auth, settings.cart, and so on). Example values are in the explorer above.

metaCopy Anchor Link

settingsCopy Anchor Link

settings.authCopy Anchor Link

settings.cartCopy Anchor Link

settings.productCopy Anchor Link

settings.product.availability_notifyCopy Anchor Link

settings.categoryCopy Anchor Link

settings.ratingCopy Anchor Link

settings.blogCopy Anchor Link

settings.keysCopy Anchor Link

settings.taxCopy Anchor Link

settings.certificateCopy Anchor Link

settings.opening_hoursCopy Anchor Link

settings.featuresCopy Anchor Link

contactsCopy Anchor Link

socialCopy Anchor Link

appsCopy Anchor Link

scopeCopy Anchor Link

shippingCopy Anchor Link

ratingCopy Anchor Link

ratingsCopy Anchor Link

order_instructionCopy Anchor Link

The API still sends more than the type lists: for example settings.rating also carries video and points options (allow_attach_videos, required_attach_images, rating_store_points). buy_now, installments, quick_order and bullet_delivery can be an object, an array or null, so check before you use them (in the demo, buy_now is an object and installments is []).

settings.features is not the top-level features array of strings. settings.opening_hours is read by useOpeningHours. scope is null unless the store uses markets or branches; the demo store has none, so there is no real example in the explorer.

refreshCopy Anchor Link

Only on useStore(). refresh(): Promise<void> re-reads store from the Salla SDK config and merges it, one level deep, over the current store. It does nothing when the SDK is not loaded yet, and ignores errors.

Common tasksCopy Anchor Link

Is the store multilingual, and which languages?Copy Anchor Link

is_multilingual is on the store. The list of languages is on settings, as an array.

import { useTwilight } from '@salla.sa/twilight-theme-engine';

function Languages() {
  const { store, settings, locale } = useTwilight();
  if (!store.settings?.is_multilingual) return null;

  return (
    <ul>
      {settings.languages?.map((lang) => (
        <li key={lang.code} aria-current={lang.code === locale}>
          {lang.name} {lang.is_rtl ? '(RTL)' : ''}
        </li>
      ))}
    </ul>
  );
}

Demo values: { "name": "العربية", "code": "ar", "is_rtl": true, "country_code": "sa", "url": "https://assets.salla.sa/images/flags/ar.svg" }. The url is the flag icon, not a page. The engine also adds iso_code, equal to code. See Languages and RTL.

Which currencies are available?Copy Anchor Link

settings.currencies is an object keyed by currency code. amount is the exchange rate against the store currency (in the demo, USD.amount is 0.267589 and SAR.amount is 1). To format prices, use useMoney.

const { store, settings } = useTwilight();
const codes = store.settings?.currencies_enabled ? Object.keys(settings.currencies ?? {}) : [];
// ["AED", "AUD", "BHD", …, "SAR", "USD"]

Do customers sign in by email or mobile?Copy Anchor Link

const { auth } = useStore().settings;
const methods = [auth.email_allowed && 'email', auth.mobile_allowed && 'mobile'].filter(Boolean);
// demo store: ["email"]

When force_login is true, send visitors to sign in before they browse.

Is the store open right now?Copy Anchor Link

opening_hours is passed to useOpeningHours, which returns isOpen, isEnabled, nextOpen and nextOpenFormatted. It treats the store as open when opening hours are not enabled.

import { useStore } from '@salla.sa/twilight-theme-engine/hooks/useStore';
import { useOpeningHours } from '@salla.sa/twilight-theme-engine/hooks';

function ClosedNotice() {
  const { settings } = useStore();
  const { isOpen, nextOpenFormatted } = useOpeningHours(settings.opening_hours);
  return isOpen ? null : <p>We are closed. We open {nextOpenFormatted}.</p>;
}

Is the store in maintenance?Copy Anchor Link

When the merchant closes the store from the dashboard (or the platform closes it, or one market is closed), the settings response carries maintenance: true and maintenance_details: the merchant's title and message (plain text), and button_* fields that are null for customers.

You do not have to handle it. The engine decides per request who sees what, the way the Twig storefront does: a customer gets the maintenance page (MaintenancePage from @salla.sa/twilight-theme-engine/store) in place of your layout, with a 503 status, and nothing else renders, not even the Salla SDK. The merchant gets the store as usual, with the SDK's maintenance bar on top.

const { settings } = useTwilight();
settings.maintenance; // true while the store is closed, for the merchant too
settings.maintenance_details?.title; // what the merchant wrote

A store that has not launched yetCopy Anchor Link

Until the merchant finishes launching the store, the settings say maintenance: true too, but maintenance_details then holds the merchant's own "finish launching" notice, which the API sends to every visitor. The engine marks these settings launched: false, and MaintenancePage shows customers the platform's launching-soon page instead: the store's logo, "The store is launching soon" in the platform's words, and the store's contacts. It never shows them that notice.

settings.launched; // false while the store has not launched yet; absent otherwise

How the engine tells the merchant from a customerCopy Anchor Link

The decision is made once per request, in the root route's beforeLoad, from the settings and the request alone:

1. The dashboard's "view store" button (and the partners portal) opens the store with ?utm_source=dashboard&identifier=<store id> (portal for the portal). When identifier is this store's store.id, the request is the merchant's. The engine answers with the store and sets a session cookie, salla_view_as=<store id>, so the browser is remembered as the merchant until it closes, as the Twig storefront's PHP session was.
2. A request carrying that cookie for this store is the merchant's too. The cookie opens only the store it was set for.
3. A session the backend marks as a theme preview (theme.mode === 'preview') always sees the store.
4. Anything served from the preview host (preview.salla.design) always sees the store, closed or not launched yet. The dashboard's theme editor frames your theme there, and a frame on another site carries neither the link from step 1 nor the cookie from step 2, so the host is what says it is a preview. It holds on every page of the preview, not only the first, as the Twig storefront's own preview hosts do. A merchant's domain, salla.sa and a dev server are not the preview host, so they are decided by the other steps. On the preview host the engine also initialises the Salla SDK with maintenance: false, so the SDK's merchant maintenance bar is not drawn over the page being edited. Only the SDK's copy changes: the settings you read with useTwilight() stay as the API sent them, maintenance: true included.
5. Everyone else gets the maintenance page and a 503, so search engines keep the store indexed as temporarily unavailable.

While you developCopy Anchor Link

Your dev server renders against a real store, so a closed store shows you the maintenance page too. In development the engine pins a bar to the top of it with a link, "View the store as the merchant": the dashboard's link from step 1, for this store. Click it once, and the rest of the browser session renders the store. A private window gives you the customer's page back, which is how you check your own maintenancePage below. The bar exists only on the dev server; production builds drop it.

Your own maintenance pageCopy Anchor Link

To show your own page instead of the engine's, pass it to the provider beside layout. It takes no props and renders alone: no layout, no route, no SDK. It renders for a store that has not launched yet too, so check settings.launched before you show maintenance_details.

import { TwilightProvider, useTwilight } from '@salla.sa/twilight-theme-engine';

function ClosedPage() {
  const { store, settings } = useTwilight();
  return (
    <main>
      <img src={store.logo} alt={store.name} />
      {settings.launched === false ? (
        <h1>Launching soon</h1>
      ) : (
        <>
          <h1>{settings.maintenance_details?.title}</h1>
          <p>{settings.maintenance_details?.message}</p>
        </>
      )}
    </main>
  );
}

<TwilightProvider translations={themeTranslations} layout={MainLayout} maintenancePage={ClosedPage}>
  <Outlet />
</TwilightProvider>;

Which payment methods and features are on?Copy Anchor Link

const { settings, features = [] } = useStore();
const acceptsCash = settings.payments?.includes('cod');
const guestCheckout = features.includes('guest-checkout');

Free shipping and cart settingsCopy Anchor Link

Free shipping progress is part of the cart, not the store. See Cart data. Store-level cart switches are in settings.cart, for example settings.cart.apply_coupon_enabled.

GotchasCopy Anchor Link

• Many fields are optional. slogan, about, favicon, api, scope, opening_hours, social.* and contacts.* can be missing. Use optional chaining and test for presence before you render a link.
• Types are looser than the data. Several settings (filters, buy_now, installments) are unions of a boolean or string, an object and null, so narrow them before use. Some real fields are not typed at all.
• store.id is a number, but ids on other objects, such as certificate.id, are strings. Compare with the right type, or convert before you compare.
• Some setting keys are not valid identifiers. settings.product['product-recommendation-type'] and settings.features['pre-order-campaigns'] need bracket access.
• Flags that are numbers. settings.product.total_sold_enabled is 1 or 0.
• Language-dependent values. The API response follows the page language, so url carries the language prefix (/en/). name and description are what the merchant typed and are not translated.
• description is HTML. Sanitise it or render it with care.
• Empty store object. If the provider is created without settings, store is {} until settings arrive, so store.settings is undefined. Use store.settings?.… in code that can run that early.
• Server and browser see the same store. It comes from the settings loaded for the request, so server and first browser render match. refresh() only exists in the browser, because it needs the Salla SDK.
• useStore() returns a new object on every render. Use useTwilight().store, which keeps its identity until refresh(), or depend on the fields you read, in effect and memo dependencies.
• settings on useTwilight() is not store.settings. useTwilight().settings is the whole settings response (store, theme, languages, currencies, and more). store.settings is only the store-level settings group.

NextCopy Anchor Link

• useStore is the hook reference.
• Theme data describes the theme object next to the store.
• Product data and Cart data describe the other objects your components read.