BazaarVoice Integration

GSM Middleware integrates with BazaarVoice to sync product reviews across your BigCommerce stores using three methods: the Authentic Discovery API, SFTP Standard Client Feed import, and automated Schema.org markup generation.

Overview

The BazaarVoice integration provides:

Authentic Discovery API — Pull reviews from BazaarVoice's SEO-friendly API endpoint
SFTP Feed Import — Parse BazaarVoice Standard Client Feed XML files from SFTP
Schema.org Markup — Generate and sync JSON-LD review markup to BigCommerce custom fields
Individual Review Storage — Store each review in rm_item_reviews with SHA-256 hash deduplication
Aggregate Ratings — Track average rating, review count, and last sync per product

Version Added: 1.16.0 (Discovery API), 1.17.0 (SFTP Feed), 1.18.15 (Schema Markup)

Site Configuration

BazaarVoice settings are configured per-site in the Site Form Modal → BazaarVoice tab (BigCommerce sites only).

Sync Toggles

Three independent sync methods can be enabled:

Toggle	Label	Purpose
`bazaarvoice_sync`	Enable Product Sync to SFTP	Export product data TO BazaarVoice via SFTP
`bv_sftp_sync`	Enable Feed Review Import	Import reviews FROM BazaarVoice SFTP feed
`bv_discovery_sync`	Enable Authentic Discovery API Sync	Pull reviews via BazaarVoice SEO API

Shared Settings

Field	Description
Name / Client ID	BazaarVoice client identifier (shared across Discovery API and SFTP)
Product ID Mapping	How to match BV products to middleware items: `prod_id`, `sku`, or `upc`

SFTP Configuration

Visible when either SFTP-based sync method is enabled:

Field	Description
SFTP Host	BazaarVoice SFTP server hostname
SFTP Username	SFTP login username
SFTP Password	SFTP login password (encrypted at rest)

Discovery API Settings

Field	Description
Environment	`staging` or `production` (determines API endpoint and rate limits)
API Key (Production)	BazaarVoice API key for production (encrypted)
API Key (Staging)	BazaarVoice API key for staging (encrypted)

Authentic Discovery API

How It Works

Iterates through all active items (rm_items) for the site
Calls the BazaarVoice Authentic Discovery API for each product
Deduplicates reviews using SHA-256 hash of product_id|review_id|submission_time
Inserts new reviews into rm_item_reviews
Recalculates aggregate ratings from actual stored reviews (not BV's aggregates)
Updates rm_items with bv_rating_value, bv_review_count, bv_last_synced

Environment-Specific Endpoints

Environment	Base URL	Rate Limit
Staging	`https://seo-stg.bazaarvoice.com`	1,200 req/min
Production	`https://seo.bazaarvoice.com`	3,000 req/min

Rate-limit-aware request delays are applied automatically with a 10% safety margin.

REST API

GET /wp-json/gsm-middleware/v1/items/{id}/reviews

Returns paginated reviews with aggregate data for a specific item.

Admin Testing Tool

Navigate to Tools → Testing → BazaarVoice Authentic Discovery API to manually trigger a review sync:

Select a site from the dropdown
Reviews are processed in chunks (10 products per batch) with real-time progress
Progress bar shows products processed, reviews found, new reviews, and errors
Environment badge (staging/production) displayed during sync
Abort button stops processing after the current batch completes

Cron Setup

External cron script for automated sync:

/usr/bin/php /path/to/plugins/gsm-middleware/cron/bv-discovery-sync.php --site=57

Configurable intervals via Crontab Generator: 1h, 24h, 3d, 7d, 14d, 30d.

SFTP Feed Import

How It Works

Connects to BazaarVoice SFTP server using PHP ssh2 extension
Downloads the latest .gz feed file from the /feeds directory
Extracts and parses BazaarVoice Standard Client Feed 14.8 XML
Processes both ReviewStatistics (aggregates) and individual <Review> elements
Matches products using the configured bv_product_id_field with UPC array fallback
Inserts reviews into rm_item_reviews with deduplication
Recalculates aggregate ratings from stored reviews (database-derived, not feed-derived)
Tracks last processed feed to skip already-imported files

Requirements

PHP ssh2 extension (pecl install ssh2)
BazaarVoice SFTP credentials configured per-site
Standard Client Feed enabled in your BazaarVoice account

Feed Tracking

Column	Description
`bv_sftp_last_feed_date`	Date of the last successfully processed feed file
`bv_sftp_last_processed_file`	Filename of the last processed feed

Cron Setup

/usr/bin/php /path/to/plugins/gsm-middleware/cron/bv-sftp-sync.php --site=57

Typically scheduled daily via the Crontab Generator.

Schema.org JSON-LD Markup

How It Works

After the SFTP feed import completes, the system automatically generates Schema.org compliant JSON-LD markup for product reviews:

Schema_Markup_Generator queries rm_item_reviews for each product
Generates two separate JSON-LD blocks per product:
- Individual Reviews — Array of schema.org/Review objects (configurable, defaults to 50 most recent)
- Aggregate Rating — schema.org/AggregateRating object (matches Google's rich snippet requirements)
Stores generated markup in rm_item_schema_markup with generation timestamp
Optionally syncs markup to BigCommerce product custom fields

BigCommerce Custom Field Sync (Legacy)

When enabled, the system automatically pushes JSON-LD to BigCommerce custom fields after generation:

Custom Field	Content
`bazaarvoice_schema_reviews_jsonld`	Individual reviews JSON-LD
`bazaarvoice_schema_aggregate_jsonld`	Aggregate rating JSON-LD

Incremental sync — Only updates products where schema was generated/updated since last sync
Batch processing — 50 products per batch for API efficiency
Sync time tracked via bv_schema_last_synced column in rm_sites

Preferred Method

For new implementations, use the Metafield Sync method below which combines reviews and aggregate into a single metafield with dynamic size management.

BazaarVoice Metafield Sync

Version Added: 1.18.37

The Metafield Sync pushes combined BazaarVoice review JSON-LD (individual reviews + aggregate rating) to BigCommerce product metafields using the suma namespace. This is the preferred method for making review data available to headless storefronts.

How It Works

Queries rm_item_schema_markup for products with review data that has changed since last sync
Builds combined JSON-LD payload containing both individual reviews and aggregate rating
Dynamically reduces review count if payload exceeds the 65,535-byte metafield limit
Upserts to BigCommerce product metafield (namespace: suma, key: bazaarvoice_reviews)
Updates metafield_last_synced timestamp in rm_item_schema_markup

Metafield Details

Property	Value
Namespace	`suma`
Key	`bazaarvoice_reviews`
Permission Set	`read` (accessible via Storefront API)
Max Size	65,535 bytes

Dynamic Size Reduction

The sync starts with up to 50 reviews per product. If the resulting JSON exceeds the 65,535-byte metafield limit:

Reduces the review count iteratively until the payload fits
The aggregate rating always reflects ALL reviews (not just those in the payload)
This ensures accurate aggregate data while fitting within BigCommerce's constraints

Per-Site Toggle

Enable via Site Form Modal → BazaarVoice tab:

Toggle	Column	Description
Enable Review Sync to BigCommerce	`bv_metafield_sync`	Controls whether the daily cron pushes combined review JSON-LD to product metafields

This toggle is only visible for BigCommerce sites.

Staleness Detection

The sync only pushes data when reviews have actually changed since the last push:

Compares generated_at (from rm_item_schema_markup) against metafield_last_synced
Products with unchanged reviews are skipped, reducing unnecessary API calls

REST API

Push Reviews Manually

POST /wp-json/gsm-middleware/v1/items/push-reviews

Authentication: Requires manage_options capability.

Push review metafields for a specific site or set of items on demand.

Items Page Integration

The Items page includes BV Metafield Sync controls:

Checkbox selection — Select multiple items for bulk operations
Per-row "Push Reviews" button — Push reviews for a single product
Bulk "Push Reviews to BC" action bar — Push reviews for all selected items

See Items Page for details.

Cron Entry Point

/usr/bin/php /path/to/plugins/gsm-middleware/cron/bv-metafield-sync.php --site=57

Runs daily (configurable hour in Crontab Generator)
Automatically triggered after SFTP feed sync completes
Only processes sites with bv_metafield_sync enabled

Dry Run Mode

Preview what would be synced without pushing to BigCommerce:

/usr/bin/php /path/to/plugins/gsm-middleware/cron/bv-metafield-sync.php --site=57 dry_run=1

Outputs all items needing sync with their review count, rating, JSON size, and a preview of the JSON-LD payload.

Database

New column on rm_item_schema_markup (Migration 022):

Column	Type	Description
`metafield_last_synced`	DATETIME	When metafield was last pushed to BigCommerce

New column on rm_sites (Migration 023):

Column	Type	Description
`bv_metafield_sync`	TINYINT	Enable BV Metafield Sync for this site (default: 0)

REST API Endpoints

Get Schema Markup

GET /wp-json/gsm-middleware/v1/items/{id}/schema-markup

Query Parameters:

Parameter	Type	Default	Description
`format`	string	`json`	`json` for structured data, `html` for ready-to-use `<script>` tags

JSON Response:

{
  "success": true,
  "data": {
    "reviews_jsonld": { "@context": "https://schema.org", ... },
    "aggregate_jsonld": { "@context": "https://schema.org", ... },
    "generated_at": "2026-05-12 14:30:00",
    "review_count": 47
  }
}

HTML Response: Returns ready-to-embed <script type="application/ld+json"> tags for direct frontend use.

Regenerate Markup

POST /wp-json/gsm-middleware/v1/items/{id}/schema-markup/regenerate

Authentication: Requires manage_options capability.

Manually regenerates the JSON-LD markup for a specific item from current review data.

Database Table

Table: rm_item_schema_markup (Migration 020)

Column	Type	Description
`id`	INT	Auto-increment primary key
`item_id`	INT	Foreign key to `rm_items`
`reviews_jsonld`	LONGTEXT	Individual reviews JSON-LD
`aggregate_jsonld`	LONGTEXT	Aggregate rating JSON-LD
`review_count`	INT	Number of reviews included
`generated_at`	DATETIME	Last generation timestamp

Database Schema

`rm_item_reviews`

Stores individual reviews (created by Migration 016):

Column	Type	Description
`id`	INT	Auto-increment primary key
`item_id`	INT	Foreign key to `rm_items`
`review_id`	VARCHAR(128)	BazaarVoice review identifier
`rating`	TINYINT	Star rating (1-5)
`title`	VARCHAR(500)	Review title
`review_text`	TEXT	Full review content
`reviewer_name`	VARCHAR(255)	Reviewer display name
`submission_time`	DATETIME	When the review was submitted
`hash`	VARCHAR(64)	SHA-256 deduplication hash
`source`	VARCHAR(32)	Source (`discovery_api` or `sftp_feed`)
`created_at`	TIMESTAMP	Row creation time

Index: Unique index on hash for deduplication.

Aggregate Columns on `rm_items`

Column	Type	Description
`bv_rating_value`	DECIMAL(3,2)	Average review rating
`bv_review_count`	INT	Total review count
`bv_last_synced`	DATETIME	Last sync timestamp

Items Page Integration

The Items page detail modal includes a BazaarVoice Reviews card showing:

Aggregate star rating visualization
Total review count
Last sync timestamp
Scrollable list of individual reviews with pagination

Items Page — View products and BV review data
Crontab Generator — Schedule BV sync cron jobs

Overview​

Site Configuration​

Sync Toggles​

Shared Settings​

SFTP Configuration​

Discovery API Settings​

Authentic Discovery API​

How It Works​

Environment-Specific Endpoints​

REST API​

Admin Testing Tool​

Cron Setup​

SFTP Feed Import​

How It Works​

Requirements​

Feed Tracking​

Cron Setup​

Schema.org JSON-LD Markup​

How It Works​

BigCommerce Custom Field Sync (Legacy)​

BazaarVoice Metafield Sync​

How It Works​

Metafield Details​

Dynamic Size Reduction​

Per-Site Toggle​

Staleness Detection​

REST API​

Push Reviews Manually​

Items Page Integration​

Cron Entry Point​

Dry Run Mode​

Database​

REST API Endpoints​

Get Schema Markup​

Regenerate Markup​

Database Table​

Database Schema​

rm_item_reviews​

Aggregate Columns on rm_items​

Items Page Integration​

Related Documentation​

Overview

Site Configuration

Sync Toggles

Shared Settings

SFTP Configuration

Discovery API Settings

Authentic Discovery API

How It Works

Environment-Specific Endpoints

REST API

Admin Testing Tool

Cron Setup

SFTP Feed Import

How It Works

Requirements

Feed Tracking

Cron Setup

Schema.org JSON-LD Markup

How It Works

BigCommerce Custom Field Sync (Legacy)

BazaarVoice Metafield Sync

How It Works

Metafield Details

Dynamic Size Reduction

Per-Site Toggle

Staleness Detection

REST API

Push Reviews Manually

Items Page Integration

Cron Entry Point

Dry Run Mode

Database

REST API Endpoints

Get Schema Markup

Regenerate Markup

Database Table

Database Schema

`rm_item_reviews`

Aggregate Columns on `rm_items`

Items Page Integration

Related Documentation