A headless commerce product API exposes product data from a PIM or commerce platform to any front end, such as webshops, apps, kiosks and AI agents, independent of a presentation layer. Effective designs separate management and delivery APIs, publish changes through events or webhooks, cache delivery responses close to users and measure freshness and latency against defined service levels.
A headless commerce product API exposes product data from a PIM or commerce platform to any front end, such as webshops, mobile apps, in-store screens, partner portals and AI shopping agents, without tying that data to a presentation layer. Each front end requests attributes, prices, assets and relationships through standard web protocols and renders them its own way. Headless commerce is the "H" in MACH (microservices, API-first, cloud-native, headless), the architecture principle behind composable commerce.
How product data flows in a headless architecture
A typical headless product data flow has four layers:
- Master layer: PIM for product content, ERP for prices and stock, DAM for assets.
- Integration layer: events, webhooks or an integration platform that moves approved changes.
- Delivery layer: a commerce engine, search index or cached delivery API built for high request volumes.
- Experience layer: front ends that read the delivery layer.
Most PIM APIs are designed for managing data, with rate limits suited to integrations. Serving shoppers directly from the PIM at peak traffic risks latency and throttling, so most architectures publish to a delivery layer. A PIM delivery API can serve low-traffic, content-heavy experiences such as B2B portals or product configurators directly.
Which API styles to use for product data
| Style | Best use | Strengths | Points to check |
|---|---|---|---|
| REST | Integrations, simple lookups, CDN caching | Widely supported, easy to cache | Over-fetching, many calls for complex pages |
| GraphQL | Product pages and apps needing varied fields | Front end requests exact fields in one call | Query complexity limits, caching strategy |
| Webhooks and events | Propagating changes to downstream systems | Near real-time, no polling | Retry logic, ordering, idempotency |
| Bulk export | Initial loads, search indexing, feeds | Efficient for full catalogues | Batch latency |
Most architectures combine them: bulk export for the initial load, events for changes, and REST or GraphQL for on-demand reads.
Which design rules make a product API usable
Product APIs fail more often on data design than on protocol choice. Eight rules cover the main issues:
- Separate management and delivery APIs. Editors and integrations write through one, front ends read through the other.
- Scope by channel and locale. Requests carry a channel and locale parameter (for example de-DE), and the API returns only data approved for that combination.
- Publish only approved data. Delivery endpoints expose released versions, never drafts.
- Use stable identifiers. Key products on SKU and GTIN, and keep identifiers stable across versions.
- Return asset URLs from a CDN. The DAM supplies renditions by size and format, as described in DAM and PIM integration.
- Support delta queries. Endpoints that return changes since a timestamp reduce load and speed up synchronisation.
- Version the API. Breaking changes go into a new version with a published deprecation period. Channel providers do the same, as the sunset of Google's Content API for Shopping on 18 August 2026 showed.
- Secure access. Use OAuth 2.0 tokens or scoped API keys, with separate credentials per consuming system.
Structured, well-scoped APIs also prepare product data for AI shopping agents, covered in agentic commerce product data.
Which KPIs and service levels to set
Targets are typical estimates and depend on traffic and architecture.
| KPI | Definition | Typical target (estimate) |
|---|---|---|
| Data freshness | Time from approval in PIM to availability in delivery layer | Under 15 minutes for content, near real-time for price and stock |
| p95 latency | 95th percentile response time of delivery API | Under 200 ms |
| Error rate | Share of failed requests | Under 0.1% |
| Cache hit ratio | Share of requests served from cache | 80% or higher for product detail pages |
| Event delivery success | Share of change events processed without retry | 99% or higher |
How to evaluate PIM APIs during selection
Ask vendors to demonstrate these points with real data during the PIM selection process:
- Rate limits per endpoint and how they scale with subscription tier.
- GraphQL support, query depth limits and schema documentation.
- Webhook or event support, with retry and ordering guarantees.
- Delta and bulk export endpoints for full catalogues.
- Channel and locale scoping in delivery endpoints.
- API versioning policy and deprecation notice periods.
- Sandbox environments and SDKs.
Practical next steps
Map every front end and downstream system that consumes product data, with expected request volumes and freshness needs. Decide which layer serves each consumer: PIM delivery API, commerce engine or search index. Define service levels for freshness and latency before selecting tools, and test vendor APIs against them with a realistic catalogue. For independent comparisons of PIM platforms and their API capabilities, see PIM Vendors.
Frequently asked questions
What is a headless commerce product API?
It is an interface that delivers product data, such as attributes, prices, assets and relationships, to any front end through standard web protocols. The front end decides how to display the data, so the same API can serve a webshop, an app, a marketplace connector or an AI agent.
Should a PIM API serve the webshop directly?
Usually only for low-traffic or content-heavy use cases. At shopper scale, most architectures publish PIM data to a commerce engine, search index or cached delivery API that is built for high request volumes and low latency.
Is GraphQL better than REST for product data?
Neither is better in general. GraphQL lets front ends request exactly the fields they need in one call, which suits varied product pages. REST is simpler to cache and widely supported. Many platforms offer both.