BigCommerce

BigCommerce Developer Documentation: Product Tagging & Enrichment Pipeline

Welcome to the Helium Pulse developer documentation for BigCommerce integration. This guide walks you through the end-to-end setup required to enable automated product tagging and enrichment for BigCommerce stores. Brands using this integration will create a Store API account, enabling our system to securely access their product data, enrich it using AI by flattening complex tag structures, and sync it back seamlessly as BigCommerce Product Custom Fields.

1. API Client Configuration

1.1 Creating Store API Account Credentials

To enable our integration, you will need to create a Store API Account within your BigCommerce store admin panel. This is typically found under Advanced Settings > API Accounts.
When creating the API Account, you will be prompted to specify OAuth Scopes (permissions).
Upon successful creation, BigCommerce will provide a Client ID, Client Secret, and an Access Token. These are displayed once and the Access Token and Client Secret should be securely copied and stored.
Helium Pulse will use the Access Token to authenticate with the BigCommerce REST API. The Client ID and Client Secret may be used for token management or specific OAuth flows if needed, but direct Access Token usage is common for server-to-server integrations.

1.2 Required OAuth Scopes

Our application requires the following OAuth Scopes to be enabled for the API Account:

Products:
- Read-only: To fetch product data, including existing custom fields.
- Modify: To create and update product information, including custom fields and product keywords.
Information & Settings (Optional, but recommended):
- Read-only: To fetch general store information like currency, which can be useful for context.
Webhooks (If using webhook-based sync):
- Modify: To create and manage webhook subscriptions for real-time product updates.

These scopes allow us to fetch products, create and update product custom fields with AI-generated data, and optionally manage product keywords.

2. Product Fetching

2.1 Fetch Products via BigCommerce REST API (v3)

We use BigCommerce's REST API (v3) to fetch your store’s products. Products are retrieved in batches using pagination (page and limit parameters). We also include custom_fields in the request to get existing enrichment data.

GET /stores/{store_hash}/v3/catalog/products?limit=250&page=1&include=custom_fields

2.2 Example Request (Conceptual Node.js)

const axios = require('axios');

async function fetchProducts(storeHash, accessToken, page = 1, limit = 250) {
  const url = `https://api.bigcommerce.com/stores/${storeHash}/v3/catalog/products?limit=${limit}&page=${page}&include=custom_fields`;

  const response = await axios.get(url, {
    headers: {
      'X-Auth-Token': accessToken,
      'Accept': 'application/json',
      'Content-Type': 'application/json'
    }
  });
  // Product data is in response.data.data
  // Pagination info is in response.data.meta.pagination
  return response.data;
}

// Example usage:
// const productData = await fetchProducts('YOUR_STORE_HASH', 'YOUR_ACCESS_TOKEN');

3. Change Detection & Sync Triggers

3.1 Webhook Support (Optional)

BigCommerce supports webhooks which can notify our system of product changes in near real-time.

Relevant webhook events include:

store/product/created
store/product/updated
store/product/deleted (for maintaining data consistency)

If webhooks are configured, BigCommerce sends an HTTP POST notification with a payload containing the product ID. We then use this ID to fetch the full product details.

3.2 Daily Sync Option (Filtering by Modification Date)

For stores not utilizing webhooks, or as a fallback, we perform a scheduled sync. We fetch products updated since the last successful sync using the date_modified:min filter.

GET /stores/{store_hash}/v3/catalog/products?date_modified:min=YYYY-MM-DDTHH:MM:SSZ&limit=250&include=custom_fields

4. Enrichment Pipeline & Data Flattening

Once products are fetched, our AI pipeline:

Analyzes product name, description, categories, brand, existing custom fields, and images.
Generates a rich, structured JSON object containing tags related to persona, usage, functional aspects, and visual details (see example below).
Flattens this JSON object: Nested keys are combined with underscores, and a prefix h_ is added to create unique custom field names. For example, tags.visual.color.primary.value becomes h_tags_visual_color_primary_value.

Example AI-Generated Tag Object:

{
    "sector": "apparel",
    "subcategory": "kurta",
    "category": "tops",
    "tags": {
        "persona": {
            "age_group": ["young adults", "adults"],
            "price_range": "mid-range",
            "gender": ["female"]
        },
        "usage": {
            "season": ["spring", "summer"],
            "occasions": ["everyday", "casual"]
        },
        "functional": {
            "eco_friendly": false
        },
        "visual": {
            "pattern": "checked",
            "material": ["viscose"],
            "color": {
                "primary": {
                    "value": "green",
                    "shade": "medium"
                }
            }
        }
    }
}

Flattened Attributes Ready for BigCommerce Custom Fields:

h_sector: "apparel"
h_subcategory: "kurta"
h_category: "tops"
h_tags_persona_age_group: "young adults, adults" (Arrays are typically joined into a string)
h_tags_persona_price_range: "mid-range"
h_tags_persona_gender: "female" (If single value array, just the value)
h_tags_usage_season: "spring, summer"
h_tags_usage_occasions: "everyday, casual"
h_tags_functional_eco_friendly: "false" (Boolean converted to string)
h_tags_visual_pattern: "checked"
h_tags_visual_material: "viscose"
h_tags_visual_color_primary_value: "green"
h_tags_visual_color_primary_shade: "medium"

5. Sync to BigCommerce (Product Custom Fields)

Enriched data, after flattening, is stored as Product Custom Fields in BigCommerce. Each flattened key-value pair becomes a custom field.

5.1 Managing Custom Fields

Fetching Existing Custom Fields: We fetch existing custom fields when retrieving product data (include=custom_fields) to compare and update efficiently.
Creating a New Custom Field: If a flattened attribute (e.g., h_tags_visual_color_primary_value) does not exist as a custom field for a product, we create it.
```
POST /stores/{store_hash}/v3/catalog/products/{product_id}/custom-fields
```
```
{
  "name": "h_tags_visual_color_primary_value",
  "value": "green"
}
```

Updating an Existing Custom Field: If a custom field already exists, we update its value.

PUT /stores/{store_hash}/v3/catalog/products/{product_id}/custom-fields/{custom_field_id}

{
  "name": "h_tags_visual_color_primary_value", // Name may or may not be updatable depending on specific needs, usually ID is key
  "value": "emerald" // New value
}

Batching Custom Field Updates: While BigCommerce API allows creating/updating custom fields one by one, for multiple changes on a single product, it's often more efficient to update the product object directly with an array of custom_fields if the API version and specific workflow support this. However, the dedicated custom field endpoints are standard. Self-correction: The primary way to add/update multiple custom fields is via the individual endpoints, or by updating the custom_fields array when updating the product itself, though the latter can be trickier with existing fields.

Note on Array Values: BigCommerce custom fields store string values. Arrays from the enrichment data (e.g., ["young adults", "adults"]) will be converted to a comma-separated string (e.g., "young adults, adults") or handled according to a defined strategy.

6. Optional: Native Tag Injection (Product Keywords)

BigCommerce has a keywords field on the product object which is an array of strings. This can be used for general SEO keywords or tag-like functionality. We can push the top 2-3 most salient keywords from our enrichment into this field.

This is done by updating the product:

PUT /stores/{store_hash}/v3/catalog/products/{product_id}
``````json
{
  "keywords": ["kurta", "green checked top", "casual wear", "apparel"]
  // ... other product fields if being updated simultaneously
}

The existing keywords should ideally be merged with the new ones to avoid overwriting.

7. Daily Enrichment Summary

7.1 Delta CSV & Summary Report

Every enrichment cycle generates a CSV file detailing the changes made (Product ID/SKU, updated custom field names (flattened codes), new values, timestamp).
A summary report is also created.

7.2 Email Notification

An automated summary email is sent daily to your brand team.
It includes the number of products enriched and a link to download the CSV report.

8. Best Practices

Rate Limits: BigCommerce APIs have rate limits (check the X-Rate-Limit-Requests-Left and X-Rate-Limit-Time-Reset-Ms headers). We implement request throttling and retry logic with exponential backoff.
Efficient Updates:
- Fetch only necessary data.
- Update custom fields by ID for precision.
- When updating multiple aspects of a product, a single PUT request to the product endpoint is preferable to multiple individual calls if possible.
Custom Field Naming: The h_ prefix ensures Helium Pulse-generated custom fields are easily identifiable and avoid conflicts with other apps or manual entries.
Error Resilience: Robust error handling and retry mechanisms are implemented for transient API issues.
Testing: All integrations are thoroughly tested on BigCommerce sandbox stores or development stores before deployment to production.

9. Technical References

This documentation can be extended to include:

Strategies for handling large arrays in custom fields (e.g., splitting into multiple fields if necessary).
Client-side SDK integration for deeper brand-side observability.
Webhook signature validation.
Advanced error logging and structured retry handling.

For any questions, please contact your Helium Pulse onboarding engineer.

PreviousKibo NextAkeneo

Last updated 14 days ago