Skip to main content
Status Sign in
News Live: EU EPR compliance. Packaging, WEEE and batteries, aggregated per country, export-ready. Read more →

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/categories instead.
description
Long-form description. Stored as sanitized HTML, render with set:html or 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:

  1. Direct match on Part.partNumber, the canonical SKU.
  2. Alias fallback, if the direct match misses, look the value up in the tenant's TenantSkuAlias table. 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 missing q returns 400.
limit
Maximum results. Defaults to 25, capped at 100.
matchedOn
Which kind of reference was hit: partNumber, alias, or crossReference. 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), or null.

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:change CustomEvent when a variant selector changes the SKU. Subscribe to it and call /api/t/parts/:partNumber again with the new SKU.
  • Prefer Shopify metafields when present. The PowersportOS theme checks the custom.manual_pdf metafield 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) or v-html (Vue) or dangerouslySetInnerHTML (React) is the correct approach. Plain-text rendering will leave literal HTML tags visible.