General Concepts

What you'll learn

• How the API uses JSON format for requests and responses
• How store-scoping works via headers
• How identifiers (UUID, slug) work across resources
• How pagination, sorting, and filtering work
• How errors are structured
• Which endpoints require authentication and which don't

Prerequisites

• A store UUID (ask your account manager or check your Blaze ECOM dashboard)
• Basic familiarity with REST APIs and JSON

JSON Format

All API requests and responses follow the JSON specification.

Content Type

All requests must include the following headers:

Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

Response Structure

Every response wraps data in a JSON envelope:

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "type": "store_products",
    "attributes": {
      "name": "Blue Dream",
      "price": 45.0,
      "category": "flower"
    },
    "relationships": {
      "brand": {
        "data": { "id": "brand-uuid", "type": "brands" }
      }
    }
  },
  "included": [
    {
      "id": "brand-uuid",
      "type": "brands",
      "attributes": { "name": "Premium Farms" }
    }
  ]
}

• data: The primary resource(s) — a single object or an array
• included: Sideloaded related resources (brands, categories, etc.)
• meta: Pagination metadata (on list endpoints)

Request Body Structure

For POST, PUT, and PATCH requests, wrap your data in a JSON envelope:

{
  "data": {
    "type": "users",
    "attributes": {
      "email": "jane@example.com",
      "password": "securepassword123"
    }
  }
}

For updates, include the resource id:

{
  "data": {
    "id": "user-uuid",
    "type": "users",
    "attributes": {
      "first_name": "Jane"
    }
  }
}

Store-Scoping Headers

Most endpoints are scoped to a specific store. You must include the X-Store header:

Example:

curl -X GET https://ecom-api.staging.blaze.me/api/v1/store \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -H "X-Store: e87437f2-3e35-4738-af5e-6307e368255c"

If you omit a required header, the API returns:

{
  "errors": [
    {
      "code": "bad_request",
      "status": "400",
      "detail": "Missing X-Store header."
    }
  ]
}

Identifiers

Resources are identified by either:

• UUID (id): Platform-assigned unique identifier (e.g., a1b2c3d4-e5f6-7890-abcd-ef1234567890)
• Slug: URL-friendly human-readable identifier (e.g., blue-dream-flower)

Many endpoints accept either format in the URL path. For example:

GET /api/v1/products/a1b2c3d4-e5f6-7890-abcd-ef1234567890
GET /api/v1/products/blue-dream-flower

Both return the same product.

Pagination

List endpoints return paginated results using limit and offset query parameters:

The response includes pagination metadata in the meta object:

{
  "data": [ ... ],
  "meta": {
    "total": 150,
    "limit": 20,
    "offset": 40
  }
}

Example — page 3 of 20 results per page:

GET /api/v1/products?limit=20&offset=40

Sorting

Use the order query parameter to sort results:

GET /api/v1/products?order=price_asc
GET /api/v1/products?order=name_desc

Available sort options vary by endpoint. Common values:

• name_asc, name_desc
• price_asc, price_desc
• created_at_asc, created_at_desc

Filtering

Product listing endpoints support query parameter filters:

GET /api/v1/products?category=flower&brand=premium-farms&min_price=20&max_price=100

Use the Filters endpoint (GET /api/v1/products/filters) to discover which filter options are available for the current store. This returns the categories, types, brands, tags, and price ranges that have products.

Error Format

All errors follow the JSON error format:

{
  "errors": [
    {
      "code": "bad_login",
      "status": "401",
      "detail": "Wrong Credentials",
      "source": {
        "pointer": "/data/attributes/password"
      },
      "extra_info": {
        "api_error_code": "AUTH_001"
      }
    }
  ]
}

Common HTTP status codes:

Tokenless vs Authenticated Access

Endpoints fall into three authentication levels:

This means a frontend can display the entire product catalog, filters, and store info without any user authentication. Authentication is only required when the user interacts with their account (cart, checkout, profile).

Access Tiers

Beyond authentication, some operations are restricted by integration tier. The API Reference marks these inline with badges, so you can tell at a glance what an endpoint needs.

Certified Partner operations

Completing a checkout through the API — creating the order and taking payment yourself — is restricted to certified partners. 7 operations carry the badge:

Everything else, including the entire cart lifecycle, is open to any integration. That is deliberate: it means an uncertified storefront can still build a full cart and complete the purchase via the Checkout Handoff, which needs no certification.

If you are not certified, use the handoff. To apply, contact your Blaze account manager or ecomsupport@blaze.me.