Catalog & discovery

Public, read-only catalog endpoints. No authentication is required. All return the standard { status, data } envelope.

Products

GET/storefront/productsList products

Returns published products with pagination. Supports filtering, search, and sorting.

curl "https://your-store-api.example.com/api/v1/storefront/products?category_slug=running-shoes&sort=price_asc&page=1&limit=24"

{
  "status": "success",
  "data": {
    "products": [
      {
        "id": 412,
        "name": "Trail Runner Edition 02",
        "slug": "trail-runner-edition-02",
        "description": "...",
        "price": "96.00",
        "sale_price": "79.00",
        "sku": "TR-02",
        "status": "published",
        "product_type": "simple",
        "is_featured": true,
        "stock_status": "instock",
        "age_restricted": false,
        "category": { "id": 8, "name": "Running shoes", "slug": "running-shoes" },
        "brand": { "id": 3, "name": "Northwind", "slug": "northwind" },
        "images": [{ "id": 1, "url": "https://.../tr02.jpg", "alt": "Trail Runner", "order": 0 }],
        "variants": [],
        "tags": [{ "id": 5, "name": "New", "slug": "new" }],
        "popularity_score": 42
      }
    ],
    "total": 137,
    "page": 1,
    "limit": 24
  }
}

A variable product (product_type: "variable") includes a variants[] array; each variant has its own price, sale_price, sku, and attributes_json.

Branch prices and availability

When the branches addon is on and you pass branch_id, the list, by-ids and single-product endpoints apply that branch's options:

• Per-branch pricing on: price, sale_price and the sale dates on the product and its variants are the branch's own, and branch_price: true marks them.
• branch_status on each product: available, not_carried or sold_out at that branch.
• Products the branch doesn't carry are left out when the shop hides them, or listed with branch_status: "not_carried" when it shows them sold out.

Without branch_id you get the shop-wide prices, as before.

GET/storefront/branch-stockLive availability for a branch

Uncached, so a statically rendered page can poll it.

{
  "status": "success",
  "data": {
    "enabled": true,
    "branch_id": 2,
    "out_of_stock_product_ids": [118, 240],
    "unavailable_product_ids": [77],
    "sold_out_product_ids": [69],
    "prices": { "84": { "price": "950.00", "sale_price": null, "sale_price_end_date": null } }
  }
}

• out_of_stock_product_ids: leave these out at this branch.
• unavailable_product_ids: show these marked sold out at this branch.
• sold_out_product_ids: sold out shop-wide.
• prices: only when per-branch pricing is on. Variable products carry a variants map keyed by variant id.

GET/storefront/branchesBranches

Active branches. When the shop uses ordering hours, each branch also has ordering_hours and:

"ordering": { "accepting_now": false, "reason": "closed", "next_open_at": "2026-09-16T08:00:00.000Z", "message": null }

reason is paused or closed; message is the branch's own note for customers.

popularity_score is the number of units sold across paid, non-cancelled orders. It is what sort=best_sellers orders by, and it is recalculated nightly rather than live — so it will not change between a purchase and the next run. Ties fall back to newest first.

GET/storefront/products/by-idsGet several products by ID

Fetch a specific set of products, preserving the order of the ids you pass. Handy for "recently viewed" or rebuilding a cart from local storage.

curl "https://your-store-api.example.com/api/v1/storefront/products/by-ids?ids=412,87,209"

GET/storefront/products/:slugGet a single product

Fetch one published product by slug (a numeric id is accepted as a fallback). Includes full details: category, categories, brand, images, variants, tags, and approved reviews (with the reviewer's first/last name).

curl "https://your-store-api.example.com/api/v1/storefront/products/trail-runner-edition-02"

Returns 404 if the product does not exist or is not published.

Categories

GET/storefront/categoriesCategory tree

Returns the full category tree (root categories with nested children). When branches are enabled, categories disabled for a branch_id are excluded.

{
  "status": "success",
  "data": {
    "categories": [
      { "id": 1, "name": "Footwear", "slug": "footwear", "children": [
        { "id": 8, "name": "Running shoes", "slug": "running-shoes", "children": [] }
      ] }
    ]
  }
}

GET/storefront/categories/:slugCategory by slug

Returns the category, a sample of its published products (up to 20, newest first), and an optional category banner.

{
  "status": "success",
  "data": {
    "category": { "id": 8, "name": "Running shoes", "slug": "running-shoes", "parent": null, "children": [] },
    "products": [ /* up to 20 products */ ],
    "banner": null
  }
}

For a full, paginated product listing in a category, use GET /storefront/products?category_slug=... instead.

Brands

GET/storefront/brandsList brands

Returns all brands, sorted by name. (Hidden in your UI when the brands_enabled setting is off.)

{ "status": "success", "data": { "brands": [{ "id": 3, "name": "Northwind", "slug": "northwind" }] } }

Tags

GET/storefront/tagsList tags

Returns all product tags, sorted by name.

{ "status": "success", "data": { "tags": [{ "id": 5, "name": "New", "slug": "new" }] } }

Currencies

GET/storefront/currenciesSupported currencies and rates

Returns the store's enabled currencies and exchange rates so your storefront can offer a currency switcher.

{
  "status": "success",
  "data": {
    "base": "KES",
    "currencies": [
      { "code": "KES", "symbol": "KSh", "rate": 1 },
      { "code": "USD", "symbol": "$", "rate": 0.0077 }
    ]
  }
}

GET/storefront/locations/countriesCountries & states

Returns the list of countries and their states/regions for address forms and shipping selectors.