Best Sellers catalog.
Best Sellers is the curated house catalog for bulk swag. It comes from Swell, not from the regional supplier APIs, and can be surfaced inside some regional tabs when fulfillment assumptions are safe.
Snapshot
| Customer-facing tab | Best Sellers, plus surfaced results in some regional tabs. |
| Catalog ID | BEST_SELLERS |
| Main input | Swell storefront API and Swell product webhooks. |
| Default visibility | Active Swell products are published after they are normalized. |
| Hidden from | Mexico, India, and MEA regional tabs. |
Input Sources
Swell is the source for this catalog. PerkUp fetches active Swell products, variants, images, tags, categories, and custom product attributes. Webhooks update products when Swell sends product or variant changes.
Unlike Sage or OneSource, Swell is more curated and PerkUp-controlled. It acts like a house catalog: cleaner and smaller, but dependent on Swell product setup quality.
Available vs Stored Data
| Source data available | What PerkUp stores |
|---|---|
| Swell product name, description, SKU, active status, product tags, product category tree, images, variants, options, and option values. | Cleaned product name, description, SKU, categories, images, colors, color options, sizes, provider, catalog ID, and published visibility. |
| Swell price tiers and product attributes such as decoration level, personalization threshold, decorations included, and other custom attributes. | USD price breaks, decoration level, personalization threshold, decorations included, and custom attributes used for catalog display and buying flows. |
| Category/category-parent data can require special handling from Swell. | PerkUp stores a normalized category list and resolves a brand from product naming when possible. |
AI Enrichment
- AI helps determine package size for products that need shipping-size cleanup.
- AI can provide fallback imprint locations for full-decoration and super-decoration products.
- Best Sellers does not use the same broad supplier image triage pipeline as Sage, OneSource, XD, or Eventgift. The Swell catalog is expected to be more curated at the source.
Audit Notes
- Best Sellers can appear alongside US, EU & UK, and Canada results, but is hidden from Mexico, India, and MEA.
- The private catalog can confine starred products to their own catalog so staff curation does not accidentally mix regions.
- Swell has daily product update jobs and product webhooks, plus scheduled AI enrichment for this catalog.
- Audit Swell setup quality carefully: product attributes, tags, categories, and variant options directly affect the final catalog record.
Source: functions/src/catalogs/bulk-swag/swell · functions/src/catalogs/ai · proto/perkup/v1/cart.proto · apps/frontend/src/pages/bulk-swag