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 API | SDK actions | |
|---|---|---|
| Runs on | Your server | The user's browser |
| Scope | Global: affects all users | One session: affects the current user only |
| Persistent | Yes | No. It resets when the plugin reloads. |
| Use for | Creating products, uploading images, base prices, global stock | Store 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 })),
});
}
}
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
| Goal | Action |
|---|---|
| Define the full list of available variants | updateCatalogWithCustomValues |
| Enable or disable a few variants | setVariantsStatus |
| Remove variants from the UI completely | setVariantsVisibility |
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.