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 - 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.

{
  "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:

{
  "error": "Error Message"
}

4.5. Examples

CURL Request

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)

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)

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

{
  "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

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

{
  "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

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

{
  "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

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

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