Status Sign in

API overview

PowersportOS exposes several API surfaces, each with its own authentication model and audience. This overview tours them and links into the per-surface detail pages. The detail articles linked below give endpoint-level request and response shapes, query parameters, error semantics, and recommended client-side behaviour.

Base URL

All API endpoints live under https://api.powersportos.com. HTTPS is required everywhere, HTTP requests redirect (in dev environments) or are rejected (in production). HSTS is preloaded for the domain.

The three public surfaces

/api/t/*
Storefront API. The endpoints the bundled PowersportOS Shopify theme (or any other storefront) calls to render YMM widgets, dealer maps, product detail content. Authenticated via per-tenant X-API-Key header. CORS open. Browser-callable.
/api/integrations/*
Integrations API. For pushing stock, prices, and inventory updates into PowersportOS from the customer's POS, ERP, WMS, or a small worker reading Shopify's Admin API. X-API-Key authenticated, designed to be called from server-side, not browser. The primary inbound path.
/api/contact
Contact form receiver. Public, unauthenticated, rate-limited. Used by the marketing site's apply / inquiry forms. Not something integrators typically touch.

Storefront API, by feature

The storefront surface is split into three feature areas in these docs:

<a href="/docs/api/storefront-ymm">YMM chain</a>
/years → /makes → /models → /vehicles → /parts. The five endpoints that power the Year/Make/Model dropdown cascade on a customer's storefront.
<a href="/docs/api/storefront-product">Product detail</a>
/parts/:partNumber + /categories. Single-part lookup for product-page enrichment (manual PDFs, OEM cross-references, prices), plus the flat-tree category list for navigation. SKU alias fallback included.
<a href="/docs/api/storefront-dealers">Dealers & stock locator</a>
/dealers, /dealers/stock, /config. The store-locator widget for a customer's website and the 'find this part at a reseller near you' widget for manufacturer brand sites.

Integrations API

<a href="/docs/api/integrations">Stock & location-stock</a>
/stock-feed + /location-stock. Server-to-server endpoints for bulk stock updates from a POS, ERP, or WMS. Idempotent, retry-safe.

Authentication

Every public surface uses X-API-Key auth. Each tenant has an API key generated when the tenant is created (and rotatable from the admin). Include it on every request: 

X-API-Key: pst_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keys are scoped to the tenant, they grant access to that tenant's data and the central catalog content the tenant has activated. They can be rotated without downtime; a rotation invalidates the previous key.

Outbound writes to Shopify

For features that write into the customer's Shopify store (see product push), the customer creates a Dev Dashboard app via Shopify's Dev Dashboard (developers.shopify.com), grants the scopes we publish, and provides the Client ID + Client Secret in the PowersportOS portal under Settings. We exchange those for short-lived OAuth tokens via the client_credentials grant on each call. The credential is fully customer-managed: revoke from the Dev Dashboard at any time and the connection cleanly stops working without any action on our side. Onboarding walks customers through the Dev Dashboard app setup once.

Stability and versioning

The public API surfaces follow a stability commitment:

  • Additive changes (new fields in responses, new optional request parameters) can happen without notice. Clients should ignore unknown fields gracefully.
  • Breaking changes (removed fields, changed semantics, renamed endpoints) get a minimum 90-day deprecation window with email notification to active integrators and a deprecation header on the response.
  • Versioning approach, currently unversioned (single live surface). When a breaking change actually warrants it, we'll move to URL-versioning (/api/v2/t/*) and run both for the deprecation window.

Rate limits

No formal published rate limits during early access. Practical guidance:

  • Storefront calls from a customer's Shopify theme, designed for browser-render rates, no realistic concern.
  • Server-side stock-feed pushes, batch into requests of ≤ 1000 items, throttle to one request per second if pushing continuously. Larger batches handled fine, but per-second throttle keeps us off each other's toes.

Rate limits will get formal documentation and per-tenant enforcement before public general availability.

Caching

The storefront endpoints set Cache-Control headers calibrated to how often the underlying data changes:

Catalog shape (<code>/years</code>, <code>/makes</code>, <code>/models</code>, <code>/vehicles</code>)
public, max-age=600, these change as the central catalog grows, but on the scale of hours to days, not minutes.
Categories, config, dealers (<code>/categories</code>, <code>/config</code>, <code>/dealers</code>)
public, max-age=300, slow-changing reference data.
Parts (<code>/parts</code>, <code>/parts/:partNumber</code>)
public, max-age=60, short because the response carries price and stock fields.
Stock locator (<code>/dealers/stock</code>)
public, max-age=60, same rationale.

Browser caches and edge caches both honour these. You typically don't need to layer your own sessionStorage cache on top; the HTTP layer handles it. The exception is application state like "the customer's chosen vehicle" or "the customer's resolved geolocation", those belong in sessionStorage.

Where to go from here

Pick the surface that matches what you're building:

If you need something not covered above, bidirectional sync, webhook receivers we run, an endpoint that doesn't exist yet, reach out at info@powersportos.com. We're working with integrators directly during early access and can prioritise based on real demand.

← Previous CSV import format Next Storefront API: YMM chain