Product

Overview

The Firework Product API provides access to product-related resources on the Firework platform.

Base URL: <https://api.firework.com>

---

Authentication

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

📖 Documentation:

• Client Credentials OAuth - Server-to-server authentication for OAuth apps

---

Endpoints

List Product Videos

Retrieve videos tagged with a specific product. Designed for PDP integration.

Endpoint: GET /api/v1/products/{product_id}/videos Authentication: Bearer token with products:read scope

Path Parameters:

Parameter	Type	Required	Description
product_id	string	Yes	Product identifier (see Product Identifiers section)

Query Parameters:

Parameter	Type	Required	Default	Description
channel_id	string	Yes	None	Firework encoded channel ID
business_store_id	string	No	None	Encoded business store ID for product lookup
before_id	string	No	None	Cursor for pagination (get entries before this video ID)
since_id	string	No	None	Cursor for pagination (get entries after this video ID)
page_size	integer	No	10	Number of videos per page (max: 100)

Product Identifiers

The product_id path parameter accepts multiple identifier types for flexibility:

• Firework encoded product ID - The internal Firework product identifier

• External product ID - Your system's product identifier

• External product unit ID - Your system's product variant/unit identifier

• Product unit GTIN - Global Trade Item Number (UPC, EAN, ISBN, etc.)

• Product unit SKU - Stock Keeping Unit

• Product unit MPN - Manufacturer Part Number

Product Lookup Rules:

• The system will attempt to resolve the product using each identifier type in sequence

• If business_store_id is provided, the lookup is scoped to that specific store

• If business_store_id is omitted, the system uses the first business store of the authenticated business

• If the product cannot be found using any identifier type, a 404 Not Found is returned

Examples:

# Using Firework product ID 
GET /api/v1/products/vWKDjg/videos?channel_id=z1xg8N 

# Using external product ID 
GET /api/v1/products/SHOE-001/videos?channel_id=z1xg8N&business_store_id=abc123 

# Using GTIN/UPC 
GET /api/v1/products/071249656457/videos?channel_id=z1xg8N 

# Using SKU 
GET /api/v1/products/SKU-12345/videos?channel_id=z1xg8N&business_store_id=abc123

Pagination

The API uses cursor-based pagination for efficient navigation through large result sets. This approach provides consistent results even when new videos are added.

How it works:

• Use before_id to get older entries (descending order by video ID)

• Use since_id to get newer entries (ascending order by video ID)

• The response includes a paging object with the next URL if more results exist

Pagination Examples:

# First page (no cursor needed) 
GET /api/v1/products/vWKDjg/videos?channel_id=z1xg8N&page_size=10 

# Next page using cursor from previous response 
GET /api/v1/products/vWKDjg/videos?channel_id=z1xg8N&before_id=2aicAl1K&page_size=10

Response: 200 OK

{
    "videos": [
    {
        "id": "xyz123",
        "caption": "Product Demo",
        "description": "See our product in action",
        "hashtags": ["demo", "product"],
        "access": "public",
        "audio_disabled": false,
        "archived_at": null,
        "product_ids": ["vWKDjg"],
        "custom_fields":
        {}
    }],
    "paging":
    {
        "next": "/api/v1/products/vWKDjg/videos?channel_id=z1xg8N&before_id=xyz123&page_size=10"
    }
}

Video Object:

Field	Type	Nullable	Description
id	string	❌	Encoded video ID
caption	string	❌	Video title/caption
description	string	✅	Video description
hashtags	string[]	❌	Array of hashtag strings (empty if none provided)
access	string	❌	Video visibility level ("public", "private", "unlisted")
audio_disabled	boolean	❌	Whether audio is disabled for the video (default: false)
archived_at	string	✅	ISO 8601 timestamp when video was archived
product_ids	string[]	❌	Array of Firework encoded product IDs
custom_fields	object	❌	Custom key-value metadata

Paging Object:

Field	Type	Nullable	Description
next	string	✅	URL to fetch the next page of results (null if no more results)

Authorization:

The channel_id must belong to the same business as the authenticated user or OAuth app. Attempting to access a channel from another business returns 403.

Errors:

Status	Description
400	Missing channel_id parameter or invalid pagination values
401	Missing or invalid token
403	Missing products:read scope or channel belongs to other business
404	Product or channel not found

Example Request:

curl -X GET "<https://api.firework.com/api/v1/products/vWKDjg/videos?channel_id=z1xg8N>" \ 
    -H "Authorization: Bearer {Access_Token}"

Example Response:

{
    "videos": [
    {
        "id": "Dux9vy8m",
        "caption": "Summer Collection Showcase",
        "description": "Check out our latest summer styles",
        "hashtags": ["summer", "fashion", "newcollection"],
        "access": "public",
        "audio_disabled": false,
        "archived_at": null,
        "product_ids": ["vWKDjg"],
        "custom_fields":
        {}
    },
    {
        "id": "2aicAl1K",
        "caption": "How to Style This Look",
        "description": null,
        "hashtags": [],
        "access": "public",
        "audio_disabled": false,
        "archived_at": null,
        "product_ids": ["vWKDjg"],
        "custom_fields":
        {}
    }],
    "paging":
    {
        "next": "/api/v1/products/vWKDjg/videos?channel_id=z1xg8N&before_id=2aicAl1K&page_size=10"
    }
}

Example Response (Last Page - No More Results):

{
    "videos": [
    {
        "id": "9xKmPq2r",
        "caption": "Product Unboxing",
        "description": "First look at the product",
        "hashtags": ["unboxing"],
        "access": "public",
        "audio_disabled": false,
        "archived_at": null,
        "product_ids": ["vWKDjg"],
        "custom_fields":
        {}
    }],
    "paging":
    {
        "next": null
    }
}