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

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

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