> For the complete documentation index, see [llms.txt](https://docs.firework.com/firework-for-developers/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.firework.com/firework-for-developers/api/business-stores.md).

# Business Stores

### 1. Overview

The Firework Business Store API allows you to manage business stores for your business. Business stores represent e-commerce storefronts connected to your Firework account. Each store groups products together and corresponds to a native store on your commerce platform.

Use the business store `id` returned by these endpoints as the `business_store_id` parameter in other APIs (e.g., `POST /api/v1/videos` for product tagging, `GET /api/v1/products/{product_id}/videos` for product lookup).

**Base URL**: `https://api.firework.com`

### 2. Authentication

The Firework Business Store API uses OAuth 2.0 for authentication. Before using this API, you must obtain an access token.

**Authentication Methods Supported:**

* **Client Credentials**: OAuth 2.0 Client Credentials flow for server-to-server authentication (machine-to-machine)

> 📖 **Documentation:**
>
> * [Client Credentials OAuth](/firework-for-developers/api/authentication.md) - Server-to-server authentication for OAuth apps

***

### 3. Endpoint Summary

| Endpoint                  | Method | Scope           | Notes                |
| ------------------------- | ------ | --------------- | -------------------- |
| `/api/v1/business_stores` | GET    | `products:read` | List business stores |

> **Note on scope**: The List Business Stores endpoint is authorized with the **`products:read`** scope (stores are part of the commerce/products surface), not a dedicated `business_stores:read` scope.

***

### 4. List Business Stores

Retrieve all business stores belonging to the specified business. The authenticated user or OAuth app must have access to the business. Results are ordered by store ID descending (newest first). Only active (non-disabled) stores are returned.

**Endpoint**: `GET /api/v1/business_stores` **Authentication**: Bearer token required (OAuth 2.0 Client Credentials) **Required Scope**: `products:read` (for OAuth apps)

#### 4.1. Request Headers

| Name            | Description                           | Required |
| --------------- | ------------------------------------- | -------- |
| `Authorization` | Bearer token: `Bearer {ACCESS_TOKEN}` | ✅        |

#### 4.2. Query Parameters

| Parameter     | Type    | Required | Description                                                                                                                                                         |
| ------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `business_id` | string  | ❌        | Encoded business ID to list stores for. Optional for app tokens (defaults to the token's business); a user token that can access multiple businesses must supply it |
| `after`       | string  | ❌        | Opaque cursor for the next page (from `pagination.cursor` or `links.next`). Ascending order                                                                         |
| `before`      | string  | ❌        | Opaque cursor for the previous page. Descending order                                                                                                               |
| `page_size`   | integer | ❌        | Number of stores per page (default: 10, max: 100). Values above the max are clamped                                                                                 |

> **Note**: There is no `provider` query filter on this endpoint — all of the business's active stores are returned regardless of commerce platform.

#### 4.3. List Business Stores Response

**Success Response**: `200 OK`

The stores are keyed under `stores` (not `business_stores`), and the response carries the standard `links` + `pagination` envelope.

```json
{
  "stores": [
    {
      "id": "y8PDj8",
      "name": "My Online Store",
      "url": "https://my-store.myshopify.com",
      "currency": "USD",
      "provider": "shopify",
      "store_type": "store"
    }
  ],
  "links": {
    "next": "/api/v1/business_stores?business_id=J1BA8n&page_size=10&before=Q3Vyc29yOjEyMw"
  },
  "pagination": {
    "cursor": "Q3Vyc29yOjEyMw",
    "has_more": true
  }
}
```

On the last page, `links.next` and `pagination.cursor` are `null` and `pagination.has_more` is `false`.

> **Note**: This is a forward-only cursor feed, so `links` omits `prev`. Stores are ordered by ID descending (newest first), so the `next` link advances with the `before` cursor. A deprecated `paging` object (`{"next": ...}`) is also returned during the pagination migration window; prefer `links` + `pagination` and do not build on `paging`.

**Business Store Fields**

Each entry in `stores` has the following fields.

| Field        | Type   | Nullable | Description                                                           |
| ------------ | ------ | -------- | --------------------------------------------------------------------- |
| `id`         | string | ❌        | Encoded unique identifier. Use as `business_store_id` in other APIs   |
| `name`       | string | ✅        | Display name of the store                                             |
| `url`        | string | ✅        | Store URL                                                             |
| `currency`   | string | ❌        | Three-letter ISO 4217 currency code (e.g., `"USD"`, `"EUR"`, `"GBP"`) |
| `provider`   | string | ❌        | Commerce platform provider (see Provider Values below)                |
| `store_type` | string | ❌        | Type of store (see Store Type Values below)                           |

**Provider Values**

| Provider          | Description                     |
| ----------------- | ------------------------------- |
| `local`           | Firework native store (default) |
| `shopify`         | Shopify integration             |
| `woocommerce`     | WooCommerce integration         |
| `magento`         | Magento integration             |
| `salesforce`      | Salesforce Commerce Cloud       |
| `bigcommerce`     | BigCommerce integration         |
| `duda`            | Duda integration                |
| `ecwid`           | Ecwid integration               |
| `boutir`          | Boutir integration              |
| `google_merchant` | Google Merchant Center          |
| `generic_oms`     | Generic OMS integration         |

**Store Type Values**

| Store Type              | Description                               |
| ----------------------- | ----------------------------------------- |
| `store`                 | Standard e-commerce store (default)       |
| `creator-store`         | Creator/social commerce store             |
| `b2b-syndication-store` | B2B syndication store for product sharing |

#### 4.4. List Business Stores Error Responses

| Status Code        | Description                                                                                                                       |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| `400 Bad Request`  | Malformed `business_id`, `business_id` required (a user token that maps to multiple businesses), or invalid pagination parameters |
| `401 Unauthorized` | Invalid or missing authentication token                                                                                           |
| `403 Forbidden`    | Insufficient scope (missing `products:read`) or no access to the business                                                         |

**Error Response Format**:

```json
{
  "error": "Error Message"
}
```

#### 4.5. Examples

**CURL Request**

```bash
curl -X GET "https://api.firework.com/api/v1/business_stores?business_id=J1BA8n&page_size=10" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

**App token (business\_id omitted, defaults to the token's business)**

```bash
curl -X GET "https://api.firework.com/api/v1/business_stores?page_size=10" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

**Next page (using cursor from previous response)**

```bash
curl -X GET "https://api.firework.com/api/v1/business_stores?business_id=J1BA8n&page_size=10&before=Q3Vyc29yOjEyMw" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```