US catalog.
The US bulk swag catalog is the largest regional catalog. It combines curated Sage products with a broad OneSource supplier network, then normalizes them into one searchable product list.
Snapshot
| Customer-facing tab | US |
| Catalog ID | US |
| Main inputs | Sage API and OneSource supplier APIs. |
| Default visibility | Sage products are generally publishable once selected. OneSource products default to hidden until PerkUp curates or overrides them. |
| Search | Final products are stored in bulkSwagProducts and indexed into Typesense for catalog search. |
Input Sources
Sage is a promo-products API. PerkUp does not ingest every Sage product. It starts from selected Sage product IDs, asks Sage for product details, pricing, images, decoration options, supplier information, packaging, inventory, and production details, then builds PerkUp products from that response.
OneSource is a supplier network. PerkUp tracks many OneSource suppliers, checks which products are sellable, and pulls product detail, media, pricing, warehouse/FOB points, decoration options, and inventory. OneSource products can also be added to Canada when the product has a Canadian warehouse or FOB point.
Available vs Stored Data
| Source data available | What PerkUp stores |
|---|---|
| Names, supplier SKUs, descriptions, categories, brand/supplier names, supplier keywords, production times, country of origin, and packaging details. | A cleaned product name, description, SKU, category/categories, provider, supplier, brand when available, material, country of origin, weight, and package size. |
| Images from Sage and OneSource media endpoints, including image type hints where the supplier provides them. | A normalized image list. PerkUp may tag images by color, view, print location, or usability so the catalog can choose better display images. |
| Price breaks, setup charges, decoration costs, and supplier net pricing. | PerkUp price tiers in USD, starting amount, decoration level, and decorations included when the source supports it. |
| Product options such as sizes, colors, part IDs, imprint methods, imprint locations, and inventory by part or warehouse. | Color options, color families, sizes, markings, variant inventory when reliable, stock status, and total quantity available. |
Raw and step-by-step supplier responses live in bulkSwagProductInputs. The customer-facing record is the final cleaned product in bulkSwagProducts.
AI Enrichment
- AI classifies product images so PerkUp can avoid bad images and understand clean, decorated, lifestyle, marketing, and unusable shots.
- AI helps identify product colors and connect images to color options when supplier color data is incomplete.
- AI helps standardize categories, package size, and imprint locations when supplier data is missing or inconsistent.
- OneSource AI enrichment is mainly used for products that are publishable or being curated, because the supplier universe is large.
Audit Notes
- The hidden
us-sageroute is a staff view for Sage-only review. It is not a separate customer catalog. - OneSource is powerful but uneven: some suppliers provide excellent inventory, color, and decoration data, while others require cleanup before publishing.
- Best Sellers can appear in the US tab as surfaced cross-catalog results. They come from Swell, not from Sage or OneSource.
- For audit questions, check both the final product and its input record. The final product shows what customers see; the input record shows what the supplier actually sent.
Source: functions/src/catalogs/bulk-swag/sage · functions/src/catalogs/bulk-swag/onesource · functions/src/catalogs/ai · proto/perkup/v1/cart.proto · apps/frontend/src/pages/bulk-swag