Storefront API: product detail
Two different questions, two endpoints. Once a customer is on a product page the storefront needs richer content than the cascade returned, so single-part lookup serves that. A customer who arrives holding the old part and a number off its housing needs the opposite: find me whatever replaces this. Reference search answers that one. There's also a flat-tree categories endpoint for navigation.
GET /api/t/parts/:partNumber
Returns a single part by part number, scoped to what the tenant has activated. The path parameter is URL-encoded, if your SKU contains slashes, dots, or spaces, encode them client-side before fetching.
GET /api/t/parts/55716013
X-API-Key: pst_live_xxx
{
"partNumber": "55716013",
"oemPartNumber": "703501249",
"brand": "Alphatrac",
"name": "Air Filter G3",
"category": "AIR FILTERS",
"description": "<p>Heavy-duty paper element designed for the Can-Am Outlander G3 platform...</p>",
"imageUrl": "https://hel1.your-objectstorage.com/powersportos-assets/...",
"manualUrl": "https://hel1.your-objectstorage.com/powersportos-assets/...",
"weightKg": 0.45,
"price": 24.90,
"stock": 12
} Response fields
- partNumber
- Canonical SKU. Always the central catalog's part number, even if you requested via an alias, this field returns the canonical.
- oemPartNumber
- OEM cross-reference number (or
null). Useful for 'Replaces OEM:' messaging on the product page. - brand
- Brand name as a string.
- name
- Product name.
- category
- Free-text category string on the part itself. For structured navigation use
/api/t/categoriesinstead. - description
- Long-form description. Stored as sanitized HTML, render with
set:htmlor equivalent, do not double-escape. - imageUrl
- Primary product image URL (or
null). Hosted on PowersportOS object storage. - manualUrl
- Owner's manual / install instructions PDF URL (or
null). Driver for the manual-link section in the PowersportOS Shopify theme. - weightKg
- Part weight as a decimal number of kilograms (or
null). - price
- Per-tenant retail price (or
null). Comes from the tenant's TenantCatalogItem row, not a central price, different tenants can have different prices for the same central part. - stock
- Per-tenant stock count (or
null). Same source as price, comes from TenantCatalogItem.
SKU alias resolution
The endpoint does two passes:
- Direct match on
Part.partNumber, the canonical SKU. - Alias fallback, if the direct match misses, look the value up in the tenant's
TenantSkuAliastable. If a row exists pointing at a central part the tenant has activated, return that part.
This means a storefront URL like /products/LP-12345 can resolve to the correct central part even though the canonical SKU is the manufacturer's 55716013, the tenant just needs to register LP-12345 as an alias in their portal. The response always returns the canonical partNumber, never the alias.
Not-found behaviour
If neither pass resolves to an active TenantCatalogItem, the endpoint returns:
HTTP 404 Not Found
{ "error": "Not found" }
This is the one endpoint in the /api/t/* surface that returns 404 for missing data, the list endpoints always return []. Treat 404 here as "this SKU is not in the tenant's catalog" and render the page without the enriched fields (the PowersportOS theme silently hides the manual-link section, for example).
Note what this endpoint deliberately does not do: it never resolves OEM or competitor cross-references. Asking it for an OE number returns 404 even when a part in the catalog replaces that number. That is correct for a product page, which must show the part its URL names and not a different one. To search by cross-reference, use the endpoint below.
Caching
Cache-Control is private, max-age=60, shorter than the YMM catalog endpoints because the response carries price and stock, which change more often than catalog shape.
GET /api/t/parts/search
Finds parts by any reference the visitor is holding: your part number, one of the tenant's aliases, or an OEM or competitor cross-reference. This is the entry point for someone who is replacing a part and reading a number off the old one, who knows neither your SKU nor, on a second-hand machine, the model year the YMM chain needs.
GET /api/t/parts/search?q=HF138&limit=25
X-API-Key: pst_live_xxx
[
{
"partNumber": "55716105",
"oemPartNumber": "3470-014",
"brand": "Alphatrac",
"name": "Air filter",
"category": "Air filters",
"description": null,
"imageUrl": null,
"manualUrl": null,
"weightKg": null,
"price": 18.50,
"stock": 4,
"matchedOn": "crossReference",
"matchedNumber": "HFF3022",
"matchedBrand": "Hiflofiltro"
}
] Matching ignores punctuation and case
HF138, HF 138 and hf-138 are one query. This is not a convenience: the same number is printed differently by everyone who prints it, and catalog data read out of supplier PDFs is inconsistent for the same reason. Comparison happens on alphanumerics only, in both directions.
Always a list, never one row
One reference can legitimately lead to several parts. An OE code gets superseded, or the same code covers both an air and an oil filter on the same machine. Render the results and let the visitor choose. Auto-selecting the first entry will sooner or later put the wrong part in a basket.
- q
- The number the visitor typed. Required. Queries shorter than three characters after punctuation is stripped return
[]rather than scanning the catalog; a missingqreturns 400. - limit
- Maximum results. Defaults to 25, capped at 100.
- matchedOn
- Which kind of reference was hit:
partNumber,alias, orcrossReference. Results are ordered by this, exact SKU matches first. - matchedNumber
- The reference as stored, which may differ from what was typed since matching is punctuation-insensitive.
- matchedBrand
- Brand on the matched cross-reference (
Hiflofiltro,K&N, the vehicle maker for an OE number), ornull.
Cache-Control is private, max-age=60, the same window as single-part lookup, since the response carries price and stock. Debounce the input by 250 to 300 ms rather than firing per keystroke.
GET /api/t/categories
Returns the full part-category tree as a flat array. Order is parent-first, then by the order field, then alphabetical. Build the tree client-side from the parentId pointers.
GET /api/t/categories
X-API-Key: pst_live_xxx
[
{ "id": "cm...", "name": "Engine", "slug": "engine", "parentId": null, "order": 1 },
{ "id": "cm...", "name": "Air filters", "slug": "air-filters", "parentId": "cm...", "order": 1 },
{ "id": "cm...", "name": "Oil filters", "slug": "oil-filters", "parentId": "cm...", "order": 2 },
...
]
Cache-Control is private, max-age=300. The tree is global (shared across tenants), not per-tenant, so it's safe to cache aggressively.
Recommended client-side behaviour
- 404 means "hide enrichment", not "broken page". A product page should render fine with just the Shopify-side data when the API misses; the API just adds extras when they're available.
- Re-fetch on variant change. The PowersportOS Shopify theme dispatches a
powersportos:variant:changeCustomEvent when a variant selector changes the SKU. Subscribe to it and call/api/t/parts/:partNumberagain with the new SKU. - Prefer Shopify metafields when present. The PowersportOS theme checks the
custom.manual_pdfmetafield first and only falls back to the API if it's missing, that pattern saves a round trip and works offline of the API. - Don't double-escape the description. It's already sanitized HTML, so rendering with
set:html(Astro) orv-html(Vue) ordangerouslySetInnerHTML(React) is the correct approach. Plain-text rendering will leave literal HTML tags visible.