Skip to content
AM

commerce-api (GraphQL + storefront + agentic)

Commerce exposes an authenticated product GraphQL API, authenticated import/product REST routes, storefront REST, and signed agentic-commerce protocols.

Runtime

PropertyCurrent contract
Production API originhttps://api.commerce.inblack.app
GraphQLPOST /graphql
Product REST/api/v1/*
Storefront REST/storefront/v1/*
Agentic commerce/agentic/ucp/{brand_id}/* and /agentic/acp/{brand_id}/*
GraphQL operations348: 134 queries, 211 mutations, 3 subscriptions
HTTP registrations159 total; 115 storefront/partner routes and 24 authenticated product routes

commerce.inblack.app is the Commerce SPA origin. Source-backed agentic profile examples may use it as a public protocol host, but admin API clients should use the deployed API origin supplied by configuration.

GraphQL example

Terminal window
curl https://api.commerce.inblack.app/graphql \
  -H "Authorization: Bearer <token>" \
  -H "X-Tenant-ID: <tenant-id>" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ products(limit: 5) { products { id sku name status } pageInfo { totalCount hasMore } } }"}'

The schema covers catalog, collections, categories, inventory, orders, pricing, bulk actions, customers, B2B, marketing, reports, billing, and tenant settings. See the GraphQL operation reference.

Storefront and partner routes

The generated HTTP route reference is canonical for registered methods and paths. It includes:

  • Storefront catalog, search, cart, checkout, customer account, forms, content, redirects, reviews, returns, and recommendations under /storefront/v1.
  • UCP offers, carts, checkout sessions, orders, and MCP under /agentic/ucp/{brand_id}.
  • ACP checkout sessions under /agentic/acp/{brand_id}.
  • Shopify installation/callback and provider webhook registrations.

Authentication differs by surface. Storefront SDK keys, customer tokens, channel OAuth, and signed UCP/ACP scope are not interchangeable with admin bearer credentials. Follow the dedicated storefront or agentic-commerce guide for the selected route.

Agent boundary

Storefront and signed shopping-agent protocols call their HTTP surfaces directly. Administrative agents default to Commerce MCP tools. Destructive public MCP actions remain blocked even when an administrative GraphQL mutation or provider callback exists.