Skip to main content

Per-user catalog customization

Your global catalog is managed in PulpoAR Studio or with the Partner API. For how Status and Stock Status work, see Stock and status. With SDK actions you can change it for one user session only, for example to show store-specific stock, personal prices or region-specific products.

SDK actions vs Partner API​

Partner APISDK actions
Runs onYour serverThe user's browser
ScopeGlobal: affects all usersOne session: affects the current user only
PersistentYesNo. It resets when the plugin reloads.
Use forCreating products, uploading images, base prices, global stockStore stock, loyalty prices, A/B tests, regional visibility

A common setup uses both: the Partner API keeps your master catalog in sync, and SDK actions personalize it for each user.

Why client-side?​

  • Per-user customization: different prices, stock or visibility per user, without changing global data.
  • Real-time updates: reflect inventory changes or promotions instantly, without a server round trip.
  • Regional and store variations: stock and prices based on location, loyalty tier or store.
  • A/B testing: test different product selections or pricing on the client.

Example: store inventory and loyalty pricing​

A user visits from Store #42 with a gold loyalty tier:

const userContext = {
storeId: 'store-42',
loyaltyTier: 'gold',
region: 'EU',
};

async function initializeVTOForUser() {
// Your own APIs
const storeInventory = await fetchStoreInventory(userContext.storeId);
const userPrices = await fetchUserPricing(userContext.loyaltyTier);

// Only these variants stay available; all others show as out of stock
pulpoar.updateCatalogWithCustomValues({
variants: storeInventory
.filter((item) => item.inStock)
.map((item) => ({
slug: item.sku,
price: userPrices[item.sku] || item.basePrice,
name: item.localizedName,
web_link: `/store/${userContext.storeId}/product/${item.sku}`,
})),
outOfStockText: 'Not available at this location',
});

// Hide region-restricted products completely
const restricted = storeInventory.filter(
(item) => !item.availableRegions.includes(userContext.region)
);

if (restricted.length) {
pulpoar.setVariantsVisibility({
variants: restricted.map((item) => ({ slug: item.sku, hidden: true })),
});
}
}
tip

Variant slugs must match between your system and PulpoAR. A common approach is to use your SKU as the variant slug.

Example: real-time stock changes​

React to inventory updates, for example from a WebSocket:

function onInventoryUpdate(item) {
if (item.inStock) {
// Back in stock: enable it
pulpoar.setVariantsStatus({
variants: [{ slug: item.sku, price: item.price }],
isDisabled: false,
});
} else {
// Out of stock: disable it
pulpoar.setVariantsStatus({
variants: [{ slug: item.sku }],
isDisabled: true,
outOfStockText: 'Just sold out!',
});
}
}

Example: visibility control​

// Hide discontinued or seasonal items
pulpoar.setVariantsVisibility({
variants: [
{ slug: 'discontinued-product', hidden: true },
{ slug: 'seasonal-winter-only', hidden: true },
],
});

// Show a previously hidden variant
pulpoar.setVariantsVisibility({
variants: [{ slug: 'seasonal-winter-only', hidden: false }],
});

// Reset: show all variants
pulpoar.setVariantsVisibility({ variants: [], mode: 'replace' });

Which action to use​

GoalAction
Define the full list of available variantsupdateCatalogWithCustomValues
Enable or disable a few variantssetVariantsStatus
Remove variants from the UI completelysetVariantsVisibility

Out of stock vs hidden: out-of-stock variants are still shown, but can't be applied, with your outOfStockText. Hidden variants don't appear at all.