Changelog

What's new in the Harmon Storefront API and this developer portal. The API is at v1 (info.version 1.0.0); the API Reference is generated from the live contract, so it always reflects what the API serves today.

Subscribe to changes

Breaking changes ship under a new major API version (see Versioning below). To track catalog/stock/order changes programmatically, use webhooks and the updated_sincedelta sync.

API - v1

Removed - vehicle catalog & fitment

The vehicle catalog and fitment endpoints (/v1/vehicles/years, /v1/vehicles/makes, /v1/vehicles/models, /v1/vehicles/{vehicle_id}/products, and /v1/products/{sku}/fitments) have been retired, along with the vehicle_id filter on GET /v1/products and the fitment_enabled response flag. If you filtered your catalog by vehicle, list products with GET /v1/products and filter on your own attributes instead.

Additive - rich product detail

GET /v1/products/{sku} now returns the full authored product detail page: a long-form body (CommonMark Markdown - render it client-side; description stays the product's name/label), a plain-text short_description summary (handy for cards and listings), and a store-defined specs store ({ "groups": [ { "label", "rows": [ { "label", "value", "highlight" } ] } ] } - the highlight rows back a quick-glance grid). Both the list and detail also carry derived marketing badges (ON_SALE, LOW_STOCK) and sale pricing - compare_at_unit_price (the strike-through list price) plus a derived discount_percent. The product gallery (media[]) now includes YouTube/Vimeo video embeds: a MediaRefOut carries kind (IMAGE or VIDEO) and, for a video, provider + embed_url + poster_url + duration_seconds. A product hidden on the storefront is absent from the list and 404s on detail. All of this is additive (clients that ignore unknown fields are unaffected); authoring any of it changes the product's ETag, so If-None-Match revalidation picks up the change automatically.

Additive - product media

GET /v1/products and GET /v1/products/{sku} now carry product imagery: a single resolved cover (or null) plus a cover-first media[] gallery. Each entry (MediaRefOut) carries the presentation metadata and the resolved public WebP derivative URLs - thumb_url (small, for grids) and large_url (for viewing) - so you render images without a second request. A product with no imagery returns cover: null and media: []. This is an additive change (clients that ignore unknown fields are unaffected); adding, removing, or reordering a product's media changes its ETag, so If-None-Match revalidation picks up the new gallery automatically.

v1.0.0 - initial public release

The first public, machine-authenticated commerce API for building your own storefront on Harmon.

• Auth - store-scoped API keys with a hard publishable/secret split, plus shopper tokens for customer-scoped reads and checkout. See Authentication & keys.
• Sandbox & live - hk_test_ keys run in sandbox; mode is echoed on every response. See Sandbox vs live.
• Catalog - products, categories, coarse availability bands, and vehicle fitment, with ETag/If-None-Match revalidation and updated_since deltas. See Pagination & caching.
• Commerce - cart → cash-on-delivery / credit-terms checkout, customer-scoped orders, invoices, and credit status.
• Webhooks - HMAC-signed delivery of order.confirmed, order.shipped, order.cancelled, invoice.issued, product.created, product.updated, and stock.changed events. See Verify webhook signatures.

Portal

This branded developer portal ships alongside v1:

• Quickstart, guides, and a recipes cookbook with copy-paste, multi-language snippets (cURL · JavaScript · Python · PHP/Laravel).
• An embedded, OpenAPI-driven API Reference with a sandbox-default Try it console.
• LLM-native artifacts - llms.txt, llms-full.txt, per-page "copy as Markdown," and one-click OpenAPI / Postman downloads.

Versioning

The Storefront API is versioned in the URL path (/v1/…). The contract follows these rules:

• Additive changes are not breaking. New endpoints, new optional request fields, and new response fields can appear within v1 at any time - write clients that ignore unknown fields.
• Breaking changes ship under a new major version (/v2/…). The previous major stays available through its announced deprecation window.
• info.version (currently 1.0.0) tracks the contract's semantic version; the API Reference and the downloadable OpenAPI are always generated from the live spec, so they never drift from what the API serves.

When a v2 contract exists, the version switcher in the top navigation will let you read the v1 and v2 references side by side. Today only v1 is published.