> 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    | `business_stores:read` or `products:read` | List business stores              |
| `/api/v1/business_stores/{id}` | GET    | `business_stores:read` or `products:read` | Get business store details        |
| `/api/v1/business_stores`      | POST   | `business_stores:write`                   | Create a local business store     |
| `/api/v1/business_stores/{id}` | PATCH  | `business_stores:write`                   | Update an existing business store |
| `/api/v1/business_stores/{id}` | DELETE | `business_stores:write`                   | Soft-delete a business store      |

> **Backward-compatible read scope**: Both read endpoints accept either `business_stores:read` or `products:read`. The latter is retained because the list endpoint originally shipped as part of the products surface. New integrations should request `business_stores:read`.

***

### 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**: `business_stores:read` or `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 both accepted read scopes) 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"
```

***

### 5. Get Business Store

Retrieve details of a specific business store. The authenticated user or OAuth app must have access to the business that owns the store.

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

#### 5.1. Request Headers

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

#### 5.2. Path Parameters

| Parameter | Type   | Required | Description                            |
| --------- | ------ | -------- | -------------------------------------- |
| `id`      | string | ✅        | Encoded unique identifier of the store |

#### 5.3. Get Business Store Response

**Success Response**: `200 OK`

```json
{
  "id": "y8PDj8",
  "name": "My Online Store",
  "provider": "shopify",
  "currency": "USD",
  "url": "https://my-store.myshopify.com",
  "uid": "my-store.myshopify.com",
  "business_id": "J1BA8n",
  "store_type": "store"
}
```

The response includes the list fields plus these detail-only fields:

| Field         | Type   | Nullable | Description                                    |
| ------------- | ------ | -------- | ---------------------------------------------- |
| `uid`         | string | ✅        | Store identifier on the commerce platform      |
| `business_id` | string | ❌        | Encoded ID of the business that owns the store |

#### 5.4. Error Responses

| Status Code        | Description                                             |
| ------------------ | ------------------------------------------------------- |
| `400 Bad Request`  | Malformed encoded store ID                              |
| `401 Unauthorized` | Invalid or missing authentication token                 |
| `403 Forbidden`    | Insufficient scope or store belongs to another business |
| `404 Not Found`    | Business store not found                                |

#### 5.5. Example

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

***

### 6. Create Business Store

Create a Firework-native (`local`) business store under the authenticated business. Platform stores such as Shopify and WooCommerce must be provisioned through their integration installation flows because they require provider credentials.

**Endpoint**: `POST /api/v1/business_stores`\
**Authentication**: Bearer token required (OAuth 2.0 Client Credentials)\
**Required Scope**: `business_stores:write` (for OAuth apps)\
**Content Type**: `application/json`

#### 6.1. Request Headers

| Name            | Description                           | Required |
| --------------- | ------------------------------------- | -------- |
| `Authorization` | Bearer token: `Bearer {ACCESS_TOKEN}` | ✅        |
| `Content-Type`  | Must be `application/json`            | ✅        |

#### 6.2. Request Body

| Parameter     | Type   | Required | Default        | Description                                                                                             |
| ------------- | ------ | -------- | -------------- | ------------------------------------------------------------------------------------------------------- |
| `business_id` | string | ❌        | Token business | Encoded business ID. Optional for app tokens; required when a user token can access multiple businesses |
| `name`        | string | ✅        | None           | Display name of the store                                                                               |
| `currency`    | string | ✅        | None           | Three-letter ISO 4217 currency code (for example, `"USD"` or `"EUR"`)                                   |
| `url`         | string | ❌        | None           | Store URL                                                                                               |
| `uid`         | string | ❌        | None           | Unique store identifier on the commerce platform                                                        |
| `provider`    | string | ❌        | `"local"`      | Only `"local"` is accepted; platform integrations cannot be created through this endpoint               |

#### 6.3. Response

**Success Response**: `201 Created`

```json
{
  "id": "5nqjQv",
  "name": "Clothing Store",
  "provider": "local",
  "currency": "USD",
  "url": "https://my-clothing-store.com",
  "uid": null,
  "business_id": "J1BA8n",
  "store_type": "store"
}
```

#### 6.4. Error Responses

| Status Code                | Description                                                                |
| -------------------------- | -------------------------------------------------------------------------- |
| `400 Bad Request`          | Missing required fields or invalid parameters                              |
| `401 Unauthorized`         | Invalid or missing authentication token                                    |
| `403 Forbidden`            | Insufficient scope or no access to the specified business                  |
| `422 Unprocessable Entity` | Validation errors, a duplicate `uid`, or a `provider` other than `"local"` |

#### 6.5. Example

```bash
curl -X POST "https://api.firework.com/api/v1/business_stores" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "business_id": "J1BA8n",
    "name": "Clothing Store",
    "currency": "USD",
    "url": "https://my-clothing-store.com"
  }'
```

***

### 7. Update Business Store

Update an existing business store's metadata. Only provided fields are updated; omitted fields remain unchanged.

**Endpoint**: `PATCH /api/v1/business_stores/{id}`\
**Authentication**: Bearer token required (OAuth 2.0 Client Credentials)\
**Required Scope**: `business_stores:write` (for OAuth apps)\
**Content Type**: `application/json`

#### 7.1. Path Parameters

| Parameter | Type   | Required | Description                            |
| --------- | ------ | -------- | -------------------------------------- |
| `id`      | string | ✅        | Encoded unique identifier of the store |

#### 7.2. Request Body

| Parameter  | Type   | Required | Description                                                |
| ---------- | ------ | -------- | ---------------------------------------------------------- |
| `name`     | string | ❌        | Display name of the store                                  |
| `currency` | string | ❌        | Three-letter ISO 4217 currency code (for example, `"USD"`) |
| `url`      | string | ❌        | Store URL                                                  |

The `provider`, `uid`, `business_id`, and `store_type` fields cannot be changed after creation.

#### 7.3. Response

**Success Response**: `200 OK`

```json
{
  "id": "5nqjQv",
  "name": "Updated Clothing Store",
  "provider": "local",
  "currency": "CAD",
  "url": "https://my-clothing-store.ca",
  "uid": null,
  "business_id": "J1BA8n",
  "store_type": "store"
}
```

#### 7.4. Error Responses

| Status Code                | Description                                             |
| -------------------------- | ------------------------------------------------------- |
| `400 Bad Request`          | Invalid parameters, malformed JSON, or malformed ID     |
| `401 Unauthorized`         | Invalid or missing authentication token                 |
| `403 Forbidden`            | Insufficient scope or store belongs to another business |
| `404 Not Found`            | Business store not found                                |
| `422 Unprocessable Entity` | Validation errors, such as an invalid currency          |

#### 7.5. Example

```bash
curl -X PATCH "https://api.firework.com/api/v1/business_stores/5nqjQv" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Clothing Store",
    "currency": "CAD",
    "url": "https://my-clothing-store.ca"
  }'
```

***

### 8. Delete Business Store

Soft-delete a business store. The disabled store no longer appears in listings.

**Endpoint**: `DELETE /api/v1/business_stores/{id}`\
**Authentication**: Bearer token required (OAuth 2.0 Client Credentials)\
**Required Scope**: `business_stores:write` (for OAuth apps)

> **Important**: A business store cannot be deleted if its products are linked to a domain assistant (AVA knowledge base). Remove the product associations first.

#### 8.1. Path Parameters

| Parameter | Type   | Required | Description                            |
| --------- | ------ | -------- | -------------------------------------- |
| `id`      | string | ✅        | Encoded unique identifier of the store |

#### 8.2. Response

**Success Response**: `204 No Content` with an empty body.

#### 8.3. Error Responses

| Status Code                | Description                                                                         |
| -------------------------- | ----------------------------------------------------------------------------------- |
| `400 Bad Request`          | Malformed encoded store ID                                                          |
| `401 Unauthorized`         | Invalid or missing authentication token                                             |
| `403 Forbidden`            | Insufficient scope or store belongs to another business                             |
| `404 Not Found`            | Business store not found                                                            |
| `422 Unprocessable Entity` | Store cannot be deleted, for example when products are linked to a domain assistant |

#### 8.4. Example

```bash
curl -X DELETE "https://api.firework.com/api/v1/business_stores/5nqjQv" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```