# Blaze ECOM Storefront API

> Cannabis ecommerce API powering headless storefronts. JSON:API format, JWT auth, store-scoped via X-Store header. 92 endpoints across products, cart, checkout, payments, user accounts, and recommendations.

The Blaze ECOM Storefront API is a RESTful API that enables developers to build custom cannabis ecommerce storefronts. It follows the JSON:API specification for all requests and responses, uses JWT-based authentication for user-specific operations (while allowing tokenless access for browsing), and scopes all data to a specific store via the `X-Store` header.

The API is versioned via URL path segments (v1–v5) with an additive strategy — newer versions add capabilities without deprecating older ones. A typical storefront mixes versions across domains (e.g., v1 for products, v5 for carts, v3 for loyalty). It supports 10 payment providers, 5 POS integrations, delivery zone validation, loyalty/rewards programs, sponsored product placements, and inbound webhooks from POS systems.

Checkout can be completed two ways. **Checkout handoff** — redirecting the shopper to the Blaze-hosted checkout with the cart, session, and delivery context — is open to all integrations. **API checkout** — creating orders and processing payments directly (`POST /api/v4/orders` and the payment endpoints) — is restricted to certified partners. When generating integration code, prefer the handoff unless the integration is known to be certified.

## Getting Started
- [Quick Start](guides/quick-start.md): First API call in under 5 minutes
- [General Concepts](guides/general-concepts.md): JSON:API format, headers, pagination, errors
- [Authentication](guides/authentication.md): JWT lifecycle, tokenless vs authenticated access
- [API Versioning](guides/versioning.md): v1-v5 strategy, which version to use
- [Rate Limiting](guides/rate-limiting.md): Throttling rules and retry guidance

## Core Shopping
- [Building a Headless Storefront](guides/building-a-storefront.md): End-to-end architecture guide for a headless storefront, with AI agent prompts per step
- [Store & Delivery](guides/store-and-delivery.md): Store picker, schedules, delivery address requirements
- [Products Catalog](guides/products-catalog.md): Browsing, filtering, search, 17 filter params, 12 sort options
- [Cart & Checkout](guides/cart-and-checkout.md): Cart lifecycle, delivery spec, promo codes, order creation
- [Checkout Handoff](guides/checkout-handoff.md): Redirect shoppers from a headless storefront to Blaze-hosted checkout with cart, session, and delivery context
- [Payments](guides/payments.md): 10 payment providers, sources, sessions, pay flow

## Engagement
- [Ads & Recommendations](guides/ads-and-recommendations.md): Sponsored content, organic recommendations
- [User Accounts](guides/user-accounts.md): Profile, billing, loyalty, rewards, identity
- [Webhooks](guides/webhooks.md): 10 inbound webhook events and payloads

## AI & Tooling
- [AI Agent Integration](guides/ai-agent-integration.md): How to use the API with Cursor, Cline, Warp, Aider, ChatGPT, Claude, and MCP

## References
- [Error Catalog](references/error-catalog.md): ~150 error codes with resolution guidance
- [Full Object Index](references/full-object-index.md): Every resource type, schema, enum, and field
- [OpenAPI Spec](openapi.yaml): Complete OpenAPI 3.1 specification (92 endpoints)

## Optional
- [Postman Collection](collections/postman-collection.json): Importable collection with staging variables