Skip to main content

BigCommerce Order Sync

Configure and manage order synchronization from BigCommerce stores.

Overview​

The BigCommerce Order Sync fetches orders via the BigCommerce v3 API and processes them through the middleware pipeline. It handles BigCommerce-specific features like store credit, custom fields, and staff notes.

Prerequisites​

API Credentials​

You need a BigCommerce API account with the following scopes:

Required OAuth Scopes:

  • Orders: Modify (read orders, update status)
  • Products: Read-only (verify product data)
  • Customers: Read-only (customer information)
  • Store Information: Read-only (store details)

Creating API Account​

  1. Log in to BigCommerce store admin
  2. Go to Settings → API Accounts → Create API Account
  3. Select V3 API Tokens
  4. Name: GSM Middleware
  5. Select scopes (as listed above)
  6. Click Save
  7. Copy credentials immediately (shown only once!):
    • Client ID
    • Access Token
    • Store Hash

Configuration​

Add BigCommerce Site​

  1. Go to GSM Middleware → Control Panel
  2. Click "Add Site"
  3. Fill in the form:

Basic Info:

Site Name: Main BigCommerce Store
Platform: BigCommerce
Site URL: https://mainstore.com
Store Hash: abc123xyz

API Credentials:

Client ID: abc123def456...
Access Token: xyz789ghi012...

Sync Settings:

☑ Enable Order Sync
☑ Enable Inventory Sync
☑ Enable Tracking Sync
  1. Click "Test Connection"
  2. If successful, click "Save"

Order Fetching​

Fetch Criteria​

Default query parameters:

$params = [
    'status_id' => 11,  // Awaiting Processing
    'sort' => 'date_modified:asc',
    'limit' => 100,
    'min_date_modified' => $last_sync_time,
];

Order Statuses​

BigCommerce order status flow:

Status IDStatus NameDescription
11Awaiting ProcessingNew orders (sync from here)
9Awaiting ShipmentAfter successful sync
2Awaiting FulfillmentAlternative processing status
10CompletedAfter shipping

Customizing Fetch Query​

Filter by date range:

// Only sync orders from last 7 days
'min_date_modified' => date('c', strtotime('-7 days')),

Limit results:

'limit' => 50,  // Fetch only 50 orders per run

Multiple statuses:

'status_id:in' => '11,2',  // Awaiting Processing OR Awaiting Fulfillment

BigCommerce-Specific Features​

Store Credit​

How it works:

  1. BigCommerce sends store_credit_amount at order level
  2. Middleware distributes proportionally across line items
  3. Separate "STORE CREDIT" line item created with negative amount

Example:

Order subtotal: $100.00
Shipping: $10.00
Tax: $9.00
Store credit: -$11.90 (10% of total)

Line items:
- Product A: $50.00 (credit: -$5.00)
- Product B: $50.00 (credit: -$5.00)
- Shipping: $10.00 (credit: -$1.00)
- Tax: $9.00 (credit: -$0.90)
- STORE CREDIT: -$11.90

Total: $107.10

Custom Fields​

Product-level custom fields:

BigCommerce allows custom fields on products. These are captured and stored:

$line_item->custom_fields = [
    'Engraving Text' => 'John Doe',
    'Gift Wrap' => 'Yes',
];

Stored in rm_lineitems:

INSERT INTO rm_lineitems (
    sku, 
    opt_name1, opt_value1,
    opt_name2, opt_value2
) VALUES (
    'PRODUCT-SKU',
    'Engraving Text', 'John Doe',
    'Gift Wrap', 'Yes'
);

Supported fields (up to 10):

  • opt_name1 / opt_value1
  • opt_name2 / opt_value2
  • ... through opt_name10 / opt_value10

Staff Notes​

Adding export confirmation:

After successful sync, a staff note is added:

Exported to middleware on 2026-03-17 10:30:45 UTC
Order Number: BGM-12345

Visible to:

  • Store administrators only
  • Not visible to customers
  • Appears in order notes section

Applied Discounts​

BigCommerce tracks promotions and discounts:

Coupon codes:

$order->coupon_discount // Total coupon discount
$order->coupons         // Array of applied coupons

Automatic promotions:

$line_item->discount_amount  // Line-level discount
$line_item->coupon_amount    // Coupon applied to line

Middleware handling:

  • Coupon codes stored in rm_lineitems.coupon_code
  • Discount amounts in rm_lineitems.discount_amount
  • Separate "COUPON" line items for order-level coupons

Shipping Methods​

BigCommerce provides:

$order->shipping_addresses[0]->shipping_method

Example values:

  • "USPS Priority Mail"
  • "FedEx 2Day"
  • "Free Shipping"
  • "Flat Rate"

Mapped to Navision carriers:

$shipping_mapping = [
    'USPS Priority Mail' => 'USPS',
    'FedEx 2Day' => 'FEDEX',
    'FedEx Ground' => 'FEDEX',
    'UPS Ground' => 'UPS',
    'Free Shipping' => 'USPS',  // Default
];

Configure mapping per site:

UPDATE rm_sites 
SET shipping_method_mapping = JSON_OBJECT(
    'USPS Priority Mail', 'USPS',
    'FedEx 2Day', 'FEDEX'
)
WHERE id = 5;

Kit Handling​

BigCommerce Kits vs. Product Options​

Important distinction:

  • BigCommerce "Product Options": Variants (size, color) - NOT kits
  • Middleware Kits: Parent SKU that expands to components - defined in rm_kits

Configuring Kits​

If you sell kits/bundles:

  1. Define in rm_kits table:
INSERT INTO rm_kits (site_id, parent_sku, child_sku, quantity)
VALUES 
    (5, 'KIT-HUNTING-01', 'KNIFE-001', 1),
    (5, 'KIT-HUNTING-01', 'FLASHLIGHT-001', 1),
    (5, 'KIT-HUNTING-01', 'ROPE-50FT', 1);
  1. When order contains KIT-HUNTING-01, it's automatically expanded
  2. Parent SKU remains (line_type: 1), components added (line_type: 2)

Parent SKU Handling​

Zero out parent price:

$parent_line->unit_price = 0.00;  // Price moved to components
$parent_line->line_type = 1;      // Mark as kit parent

Components inherit:

  • Customer's ordered quantity × component quantity
  • Pro-rated pricing
  • Parent line number reference

Payment Gateways​

Supported Gateways​

BigCommerce supports many payment gateways. Middleware identifies and flags:

GatewayFlag FieldTrans ID Source
Stripestripe = 1payment_provider_id
Klarnaklarna = 1payment_provider_id
Sezzlesezzle = 1payment_provider_id
Credovacredova = 1payment_provider_id
PayPalpaypal = 1payment_provider_id
NMInmi = 1Custom field

Payment Method Detection​

Logic:

if (stripos($order->payment_method, 'stripe') !== false) {
    $normalized->stripe = true;
    $normalized->trans_id = $order->payment_provider_id;
}

Multiple flags possible:

  • Order can have multiple payment methods (split payment)
  • All applicable flags set to true
  • Trans ID captures primary payment

Transaction ID​

Stored in rm_order.trans_id:

  • Used for refunds
  • Customer service reference
  • Payment reconciliation

Updating Order Status​

After Successful Sync​

Status update to "Awaiting Shipment" (9):

PUT /stores/{store_hash}/v3/orders/{order_id}
{
    "status_id": 9
}

Staff note added:

POST /stores/{store_hash}/v3/orders/{order_id}/messages
{
    "message": "Exported to middleware on 2026-03-17 10:30:45 UTC\nOrder Number: BGM-12345",
    "is_staff_only": true
}

Why Status 9?​

  • 11 (Awaiting Processing): Initial status, picked up by sync
  • 9 (Awaiting Shipment): Signals "exported and ready for fulfillment"
  • Prevents re-syncing same order
  • Clear workflow for warehouse

Error Handling​

Common BigCommerce Errors​

401 Unauthorized​

Cause: Invalid or expired access token

Solution:

  1. Regenerate API credentials in BigCommerce
  2. Update in GSM Middleware site settings
  3. Test connection

404 Not Found​

Cause: Wrong store hash or order doesn't exist

Solution:

  1. Verify store hash in API Path
  2. Check order exists in BigCommerce
  3. Verify order status is 11 (Awaiting Processing)

429 Too Many Requests​

Cause: API rate limit exceeded

BigCommerce limits:

  • Store API: 20 requests/second
  • All requests: 20,000/hour

Solution:

  1. Reduce sync frequency
  2. Decrease batch size
  3. Add delays between requests

422 Unprocessable Entity​

Cause: Invalid data in request (e.g., updating status)

Solution:

  1. Check order status can transition to 9
  2. Verify order not already in status 9
  3. Review API request payload

Debug Mode​

Enable verbose BigCommerce logging:

// In site settings (custom field)
'debug_api' => true

Logs will include:

  • Full API request URLs
  • Request headers (credentials redacted)
  • Response bodies
  • Execution times

Performance Optimization​

Batch Processing​

Parallel requests (use caution):

// Fetch orders in batches of 100
$page = 1;
do {
    $params['page'] = $page;
    $params['limit'] = 100;
    $orders = $api->getOrders($params);
    // Process orders...
    $page++;
} while (count($orders) === 100);

Caching​

Cache product data:

// Avoid repeated product lookups
$product_cache = [];
if (!isset($product_cache[$product_id])) {
    $product_cache[$product_id] = $api->getProduct($product_id);
}

Connection Pooling​

Reuse HTTP connections:

// Use persistent connections
$client = new GuzzleHttp\Client([
    'base_uri' => 'https://api.bigcommerce.com/',
    'timeout' => 30,
    'connect_timeout' => 10,
]);

Testing​

Test with Single Order​

  1. Create test order in BigCommerce
  2. Note order ID
  3. Go to GSM Middleware → Test Order
  4. Enter order ID
  5. Click "Test Order Import"
  6. Review results

Test Store Credit​

  1. Create BigCommerce order
  2. Apply store credit to order
  3. Sync order
  4. Verify rm_lineitems has negative "STORE CREDIT" line
  5. Verify proportional distribution

Test Kit Expansion​

  1. Define kit in rm_kits
  2. Create order with kit parent SKU
  3. Sync order
  4. Verify parent + components in rm_lineitems
  5. Check quantities calculated correctly

Troubleshooting​

Orders Not Syncing​

Check:

  1. Order status is 11 (Awaiting Processing)
  2. Order date > min_date_modified setting
  3. Order total > $1.00 (if skip test orders enabled)
  4. API credentials valid
  5. Site orders_sync enabled

Store Credit Not Applied​

Check:

  1. store_credit_amount present in API response
  2. Check rm_lineitems for "STORE CREDIT" line
  3. Verify negative amount
  4. Check distribution across line items

Kits Not Expanding​

Check:

  1. Kit definition exists in rm_kits
  2. parent_sku matches exactly (case-sensitive)
  3. Component SKUs verified in Business Central
  4. Site ID matches

Best Practices​

  1. API Credentials: Rotate every 90 days
  2. Rate Limiting: Monitor API usage in BigCommerce
  3. Testing: Always test in staging first
  4. Monitoring: Set up alerts for sync failures
  5. Documentation: Keep shipping method mapping updated

Next Steps​