Skip to main content

BigCommerce Middleware for Narvar

Order tracking and shipment integration between BigCommerce and Narvar's post-purchase platform.

Overview​

BigCommerce Middleware for Narvar acts as a bridge between BigCommerce e-commerce stores and Narvar's post-purchase customer experience platform. The plugin receives order and shipment webhooks from BigCommerce, formats the data, and submits it to Narvar for order tracking, delivery notifications, and customer communication.

Current Version: 1.2.20
Requires: WordPress 4.7+, PHP 8.0+
Text Domain: bc2narvar

Key Features​

Webhook Processing​

  • BigCommerce Webhooks — Receives order and shipment webhooks from BigCommerce
  • Automated Sync — Real-time data submission to Narvar on order events
  • Queue System — Processes webhooks asynchronously for reliability
  • Retry Logic — Automatic retry for failed submissions

Order Synchronization​

  • Order Creation — Send new orders to Narvar immediately
  • Order Updates — Sync status changes and modifications
  • Shipment Tracking — Submit tracking numbers and carrier info
  • Refund Processing — Handle order refunds and cancellations

Data Management​

  • Webhook Logging — Complete audit trail of all webhook activity
  • Error Tracking — Log failed submissions with error details
  • Admin Interface — WordPress dashboard for monitoring sync status
  • Reporting — Daily summary reports of webhook activity

Reliability Features​

  • Automatic Retry — Up to 3 retry attempts for failed orders
  • Cron Jobs — Multiple scheduled tasks for processing and cleanup
  • Missing Order Detection — Identify and queue orders that failed to sync
  • Email Notifications — Alert administrators of persistent failures

BigCommerce Integration​

  • Order API — Fetch complete order details from BigCommerce
  • Shipment API — Retrieve shipping and tracking information
  • Product API — Access product details for line items
  • Customer API — Get customer information for orders

How It Works​

Order Submission Flow​

BigCommerce Order Placed
    ↓
BigCommerce Webhook Fired
    ↓
WordPress REST Endpoint Receives Webhook
    ↓
Order Data Fetched from BigCommerce API
    ↓
Data Formatted for Narvar
    ↓
Submitted to Narvar API
    ↓
Response Logged in WordPress
    ↓
Success or Queued for Retry

Shipment Tracking Flow​

BigCommerce Shipment Created
    ↓
Shipment Webhook Received
    ↓
Tracking Number Extracted
    ↓
Shipment Data Sent to Narvar
    ↓
Customer Receives Tracking Email (via Narvar)

Architecture Overview​

BigCommerce Store
    ↓
Webhooks (Orders, Shipments, Refunds)
    ↓
WordPress REST API Endpoints
    ↓
Webhook Queue System
    ↓
BigCommerce API Client
    ↓
Data Formatter
    ↓
Narvar API Client
    ↓
Logging System

Use Cases​

  • Order Tracking — Provide customers with real-time shipping updates
  • Delivery Notifications — Automated delivery status emails
  • Post-Purchase Experience — Enhance customer communication after checkout
  • Returns Management — Streamline return and refund processes
  • Customer Service — Reduce "Where is my order?" support tickets

Technical Requirements​

  • WordPress 6.4 or higher
  • PHP 8.0 or higher with cURL extension
  • BigCommerce store (any plan)
  • BigCommerce API credentials (Store Hash, Client ID, Access Token)
  • Active Narvar account
  • Narvar API credentials (URL, Username, Password)
  • Publicly accessible WordPress installation (for webhooks)

BigCommerce API Requirements​

Required API Credentials​

  • Store Hash — Unique identifier for your BigCommerce store
  • Store URL — Full store URL (e.g., https://store.mybigcommerce.com)
  • Client ID — OAuth client ID from BigCommerce API account
  • Access Token — OAuth access token with required scopes

Required API Scopes​

  • store_v2_orders — Read order data
  • store_v2_orders_read_only — Read-only access to orders
  • store_v2_shipments — Read shipment data
  • store_v2_shipments_read_only — Read-only shipments

How to create API credentials: BigCommerce API Documentation

Narvar API Requirements​

Required Credentials​

  • API URL — Narvar API endpoint URL
  • Username — Narvar API username
  • Password — Narvar API password

Contact Narvar support for API access.

Webhook Endpoints​

The plugin registers these REST API endpoints:

Order Processing​

Endpoint: /wp-json/suma/v1/bc-webhooks-process?type=ORDER
Method: POST
Schedule: Every 10 minutes
Purpose: Process queued order webhooks

Shipment Processing​

Endpoint: /wp-json/suma/v1/bc-webhooks-process?type=SHIPMENT
Method: POST
Schedule: Every 10 minutes
Purpose: Process queued shipment webhooks

Refund Processing​

Endpoint: /wp-json/suma/v1/bc-webhooks-process?type=REFUND
Method: POST
Schedule: Every 10 minutes
Purpose: Process queued refund webhooks

Missing Orders Queue​

Endpoint: /wp-json/suma/v1/bc-orders-missing-shipments-prep
Method: POST
Schedule: Once daily
Purpose: Find orders missing shipments and queue for processing

Endpoint: /wp-json/suma/v1/bc-orders-missing-shipments-process
Method: POST
Schedule: Every 15 minutes
Purpose: Process orders identified as missing shipments

Daily Reporting​

Endpoint: /wp-json/suma/v1/bc-webhooks-daily-report
Method: POST
Schedule: Once daily
Purpose: Generate summary report of webhook responses

Setup Process​

1. Install Plugin​

Upload and activate plugin via WordPress admin.

2. Configure API Credentials​

Navigate to Settings > BC/Narvar Settings and enter:

  • BigCommerce Store Hash
  • BigCommerce Store URL
  • BigCommerce Client ID
  • BigCommerce Access Token
  • Narvar API URL
  • Narvar Username
  • Narvar Password

3. Create BigCommerce Webhook​

After saving credentials, click "Set BigCommerce Webhook" button in admin notice.

This creates a webhook in BigCommerce pointing to your WordPress installation.

4. Configure Cron Jobs​

Set up external cron jobs (via cPanel, hosting panel, or service like EasyCron) to hit the REST endpoints at recommended intervals.

5. Test Integration​

Place a test order in BigCommerce and verify:

  • Order appears in WordPress middleware admin
  • Order marked as successfully sent to Narvar
  • No error messages logged

Admin Interface​

Webhook Response Logs​

The WordPress admin displays:

  • Order ID — BigCommerce order number
  • Status — Success/Failed
  • Retry Count — Number of submission attempts
  • Timestamp — When request was made
  • Error Details — Error messages for failed submissions

Actions Available​

  • View complete webhook payload
  • Manually retry failed orders
  • Delete webhook log entries
  • Export logs for analysis

Error Handling​

Automatic Retry​

Failed orders retry automatically up to 3 times:

  1. First Failure — Retry after 10 minutes
  2. Second Failure — Retry after 1 hour
  3. Third Failure — Email notification sent

Email Notifications​

Administrators receive email alerts when:

  • Order fails 3 times (cannot sync)
  • Daily error count exceeds threshold
  • Critical API errors occur

Error Types​

  • API Connection Error — Cannot reach BigCommerce or Narvar
  • Authentication Error — Invalid API credentials
  • Data Validation Error — Missing required fields
  • Rate Limit Error — API rate limit exceeded

Data Flow​

Order Data Format​

{
  "order_id": "12345",
  "order_number": "ORD-12345",
  "customer": {
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe"
  },
  "items": [
    {
      "sku": "PROD-123",
      "name": "Product Name",
      "quantity": 2,
      "price": "49.99"
    }
  ],
  "shipping": {
    "carrier": "USPS",
    "tracking_number": "9400111899223467890",
    "address": {...}
  }
}

Performance Considerations​

  • Webhook Queue — Prevents blocking during high-traffic periods
  • Batch Processing — Processes multiple webhooks per cron run
  • API Rate Limiting — Respects BigCommerce and Narvar rate limits
  • Database Optimization — Regular cleanup of old webhook logs

Monitoring & Maintenance​

Daily Checks​

  • Review webhook response logs
  • Check for failed orders
  • Monitor error notifications
  • Verify cron jobs running

Weekly Tasks​

  • Review sync success rate
  • Clean up old webhook logs
  • Check API credential expiration
  • Update plugin if available

Third-Party Libraries​

The plugin uses these libraries:

  • cURL Wrapper — By Sean Huber (GitHub)
  • BigCommerce API Library — By Aligent (GitHub)