SKU aliases

The problem

A retailer's typical SKU surface looks like this:

Canonical part number

The manufacturer's published SKU, e.g. 55716013. This is what PowersportOS stores as the canonical identifier on the central catalog.

POS internal code

Generated by the retailer's point-of-sale system at the time the SKU was first carried, e.g. LP-12345. Often shorter, often opaque, often impossible to change without ripple effects.

Distributor SKU

The wholesaler's own identifier on invoices, e.g. DIST-AC-7788. May or may not match the manufacturer's canonical.

Legacy supplier code

From a previous supplier the retailer used. Still appears on old invoices and stock records that legacy systems are pulling from.

Each of these identifies the same physical part. Without aliases, the retailer would have to migrate every internal system to use the same identifier, which means rewriting accounting integrations, supplier-side communications, customer-facing receipts, historical reports. Painful, error-prone, often impossible.

The solution

PowersportOS's TenantSkuAlias table is a per-tenant lookup of alternate identifiers to canonical parts. One row per (alias, canonical-part) pair. The tenant adds rows for whatever alternate identifiers their systems use; PowersportOS does the resolution wherever it matters.

Two flows currently consume aliases:

Stock-feed pushes

When a POS posts to /api/integrations/stock-feed with a row like { partNumber: "LP-12345", stock: 7 }, the resolver tries:

1. Direct match against the tenant's activated central catalog
2. Direct match against the tenant's own proprietary TenantParts
3. Alias-table lookup, resolve LP-12345 to its canonical part and update that part's stock

First hit wins. Result includes resolvedViaAlias as a separate counter so the retailer can monitor how many of their pushes went through the alias path.

Storefront product-page lookups

A Shopify theme calling /api/t/parts/:partNumber follows the same fall-through. A product URL like /products/LP-12345 resolves to the central Part even though the canonical SKU on the manufacturer side is 55716013. The customer-facing URL stays whatever the retailer's e-commerce platform has historically used.

Per-tenant scope

Aliases are scoped to the tenant that created them. Different tenants can use the same alias for different parts, your alias table is private. There's no global "alias namespace" that could collide.

Adding aliases requires a portal user (or admin acting on the tenant's behalf). There's no public API for alias management today, it lives in the customer portal at the SKU Aliases page in the sidebar.

When to add aliases vs. rename your codes

Renaming your POS codes to match canonical PowersportOS part numbers is sometimes feasible (small catalog, modern POS, no legacy systems). For most retailers it's not, too many downstream dependencies. Aliases are the lower-cost solution: one row per mismatched identifier, no other system touched.

Limitations in v1

• No bulk import. Aliases are added one at a time in the portal. A CSV importer for aliases would be straightforward to add but hasn't been needed at typical retailer scale (≤ 50 mappings total).
• No public API for management. Reading aliases works fine for storefront flows, but creating / editing / deleting them requires the portal UI. We'll expose CRUD endpoints if a customer needs programmatic alias management.
• One alias → one canonical. If you've genuinely got the same alias string used for two different parts somewhere, that's a data conflict you have to resolve manually first.

Related concepts

• OEM cross-references, the inverse direction. A canonical PowersportOS part can list the original-equipment manufacturer's part numbers it replaces, so customers searching by OEM SKU find the aftermarket equivalent. Set per part in the admin; see the product-detail API for the field.
• OE catalog mapping, for some manufacturers, the central catalog already maps canonical SKUs to their OE counterparts. Aliases are the tenant-level layer for everything else.