Skip to main content

WooCommerce Order Sync

Configure and manage order synchronization from WooCommerce stores.

Overview​

The WooCommerce Order Sync fetches orders via the WooCommerce REST API v3 and processes them through the middleware pipeline. It handles WooCommerce-specific features like smart coupons, gift cards, and custom order meta.

Prerequisites​

API Credentials​

You need WooCommerce API keys with Read/Write permissions.

Required WooCommerce Version:

  • WooCommerce 3.0+ (REST API v3)
  • WordPress 5.0+
  • Pretty permalinks enabled

Generating API Keys​

  1. Log in to WordPress admin
  2. Go to WooCommerce → Settings → Advanced → REST API
  3. Click "Add key"
  4. Fill in form: 
    Description: GSM Middleware
    User: [Select admin user]
    Permissions: Read/Write
  5. Click "Generate API Key"
  6. Copy keys immediately (shown only once!):
    • Consumer Key: ck_abc123...
    • Consumer Secret: cs_xyz789...

Configuration​

Add WooCommerce Site​

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

Basic Info:

Site Name: WooCommerce Main Store
Platform: WooCommerce
Site URL: https://woostore.com

API Credentials:

Consumer Key: ck_abc123def456...
Consumer Secret: cs_xyz789ghi012...

Advanced:

API Version: wc/v3 (default)
☑ Verify SSL (uncheck for self-signed certs)

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' => 'processing',
    'orderby' => 'date',
    'order' => 'asc',
    'per_page' => 100,
    'after' => $last_sync_time,  // ISO 8601 format
];

Order Statuses​

WooCommerce order status flow:

StatusDescriptionSync Action
processingPayment complete, readySync from here
exportedCustom status after syncMark as exported
pendingAwaiting paymentSkip
on-holdOn hold by adminSkip
completedFulfilled and deliveredSkip

Custom Status "Exported"​

Optional: Create custom status for exported orders

Add to functions.php or plugin:

add_action('init', function() {
    register_post_status('wc-exported', [
        'label' => 'Exported to Middleware',
        'public' => true,
        'exclude_from_search' => false,
        'show_in_admin_all_list' => true,
        'show_in_admin_status_list' => true,
        'label_count' => _n_noop(
            'Exported <span class="count">(%s)</span>',
            'Exported <span class="count">(%s)</span>'
        ),
    ]);
});

add_filter('wc_order_statuses', function($statuses) {
    $statuses['wc-exported'] = 'Exported to Middleware';
    return $statuses;
});

WooCommerce-Specific Features​

Smart Coupons​

WooCommerce Smart Coupons plugin support:

Gift card coupons:

// Smart Coupon balance deducted
$coupon_amount = get_post_meta($coupon_id, 'coupon_amount', true);
$coupon_type = $order->get_coupon_codes();

Middleware handling:

  • Gift card coupons create "COUPON" line items
  • Amount is negative (credit)
  • Coupon code stored in coupon_code field

Example:

INSERT INTO rm_lineitems (
    sku, 
    line_number, 
    unit_price, 
    quantity,
    coupon_code
) VALUES (
    'COUPON',
    5,
    -25.00,
    1,
    'GIFT-CARD-ABC123'
);

PW Gift Cards​

PW Gift Cards plugin support:

Gift card payment method:

$gift_card_amount = $order->get_meta('_pw_gift_card_amount');
$gift_card_number = $order->get_meta('_pw_gift_card_number');

Middleware handling:

  • Creates negative line item for gift card amount
  • Similar to store credit handling
  • Card number stored in order notes

WooCommerce Subscriptions​

Subscription orders:

Subscription products are handled like regular products:

  • Initial subscription order syncs normally
  • Renewal orders sync if status = "processing"
  • Subscription parent order tracked in meta

Identify subscription:

$is_subscription = $order->get_meta('_subscription_renewal');
if ($is_subscription) {
    // Flag in order notes
    $normalized->staff_notes = "Subscription renewal order";
}

Custom Order Meta​

Capture custom fields:

WooCommerce allows custom order meta. Common fields:

$custom_fields = [
    '_billing_vat_number' => 'VAT Number',
    '_shipping_delivery_date' => 'Requested Delivery',
    '_order_special_instructions' => 'Special Instructions',
];

Store in rm_order notes:

foreach ($custom_fields as $meta_key => $label) {
    $value = $order->get_meta($meta_key);
    if ($value) {
        $notes .= "$label: $value\n";
    }
}

Order Notes​

WooCommerce order notes:

$notes = wc_get_order_notes([
    'order_id' => $order_id,
    'type' => 'customer',  // Only customer notes
]);

Added to rm_order:

UPDATE rm_order 
SET staff_notes = 'Customer Note: Please ship ASAP'
WHERE number = 'BGM-12345';

Variable Products​

WooCommerce variation handling:

$product_id = $line_item->get_product_id();
$variation_id = $line_item->get_variation_id();

if ($variation_id) {
    // Get variation SKU
    $product = wc_get_product($variation_id);
    $sku = $product->get_sku();
} else {
    // Simple product
    $product = wc_get_product($product_id);
    $sku = $product->get_sku();
}

Variation attributes stored:

-- Example: T-Shirt (Size: L, Color: Blue)
INSERT INTO rm_lineitems (
    sku,
    opt_name1, opt_value1,
    opt_name2, opt_value2
) VALUES (
    'TSHIRT-001',
    'Size', 'L',
    'Color', 'Blue'
);

Shipping Methods​

WooCommerce Shipping​

Shipping method format:

$shipping_method = $order->get_shipping_method();
// Examples:
// "Flat Rate"
// "Free Shipping"
// "Local Pickup"
// "USPS Priority Mail" (if using extension)

Mapping to Navision Carriers​

Configure mapping:

$shipping_mapping = [
    'Flat Rate' => 'USPS',
    'Free Shipping' => 'USPS',
    'USPS Priority Mail' => 'USPS',
    'USPS First Class' => 'USPS',
    'FedEx 2Day' => 'FEDEX',
    'FedEx Ground' => 'FEDEX',
    'UPS Ground' => 'UPS',
    'Local Pickup' => 'PICKUP',
];

Per-site override:

UPDATE rm_sites 
SET shipping_method_mapping = JSON_OBJECT(
    'Flat Rate', 'USPS',
    'Free Shipping', 'USPS'
)
WHERE id = 10;

Shipping Extensions​

Popular shipping plugins supported:

  • WooCommerce Shipping: Built-in
  • USPS Shipping Plugin: Auto-mapped
  • FedEx Shipping: Auto-mapped
  • Table Rate Shipping: Custom mapping

Payment Gateways​

Supported Gateways​

GatewayPluginFlag Field
StripeWooCommerce Stripestripe = 1
PayPalWooCommerce PayPalpaypal = 1
KlarnaKlarna Paymentsklarna = 1
SquareWooCommerce SquareCustom
Authorize.netWC Authorize.netCustom

Payment Method Detection​

Logic:

$payment_method = $order->get_payment_method();
$payment_title = $order->get_payment_method_title();

if ($payment_method === 'stripe') {
    $normalized->stripe = true;
    $normalized->trans_id = $order->get_transaction_id();
}

if ($payment_method === 'paypal') {
    $normalized->paypal = true;
    $normalized->trans_id = $order->get_transaction_id();
}

Transaction ID​

WooCommerce transaction ID:

$trans_id = $order->get_transaction_id();
// Stored in rm_order.trans_id

Updating Order Status​

After Successful Sync​

Add order meta (hidden):

update_post_meta($order_id, 'sumatra_wc_integrator_exported', 1);
update_post_meta($order_id, 'sumatra_wc_integrator_exported_date', current_time('mysql'));

Optional: Change status:

$order->update_status('exported', 'Exported to middleware');

Why Order Meta?​

  • Non-intrusive: Doesn't change visible order status
  • Reliable: Prevents re-syncing
  • Queryable: Easy to find exported orders
  • Compatible: Works with all WooCommerce versions

Coupons & Discounts​

Coupon Handling​

WooCommerce coupon data:

$coupons = $order->get_coupons();
foreach ($coupons as $coupon) {
    $code = $coupon->get_code();
    $discount = $coupon->get_discount();
    // Create COUPON line item
}

Line-item discounts:

$item_discount = $line_item->get_discount();
// Applied to unit_price or separate discount_amount field

Fee Lines​

Custom fees:

$fees = $order->get_fees();
foreach ($fees as $fee) {
    // Add as separate line item
    $sku = 'FEE';  // Synthetic SKU
    $amount = $fee->get_total();
}

Kit Handling​

WooCommerce Product Bundles​

If using "WooCommerce Product Bundles" plugin:

Bundle detection:

$is_bundle = $product->is_type('bundle');
if ($is_bundle) {
    $bundle_items = $product->get_bundled_items();
}

Middleware kit expansion:

  1. Define bundle in rm_kits (same as BigCommerce)
  2. Parent SKU expands automatically
  3. Components added as separate line items

Configuration:

INSERT INTO rm_kits (site_id, parent_sku, child_sku, quantity)
VALUES 
    (10, 'BUNDLE-CAMPING-01', 'TENT-2PERSON', 1),
    (10, 'BUNDLE-CAMPING-01', 'SLEEPBAG-001', 2),
    (10, 'BUNDLE-CAMPING-01', 'FLASHLIGHT-001', 2);

Tax Handling​

WooCommerce Tax​

Tax calculation:

$tax_total = $order->get_total_tax();
$shipping_tax = $order->get_shipping_tax();

Tax line item:

INSERT INTO rm_lineitems (sku, unit_price, quantity)
VALUES ('SALES TAX', 15.50, 1);

State-based tax:

  • Checks ship_state against configured tax states
  • Only creates tax line if state requires tax
  • Combines product + shipping tax

Error Handling​

Common WooCommerce Errors​

401 Unauthorized​

Cause: Invalid consumer key/secret

Solution:

  1. Regenerate API keys in WooCommerce
  2. Update in GSM Middleware
  3. Test connection

404 Not Found​

Causes:

  • REST API disabled
  • Pretty permalinks not enabled
  • Wrong site URL
  • SSL certificate issues

Solutions:

  1. Enable REST API: WooCommerce → Settings → Advanced → REST API
  2. Enable permalinks: Settings → Permalinks → "Post name"
  3. Verify site URL (with/without www)
  4. Check SSL certificate

403 Forbidden​

Cause: API user lacks permissions

Solution:

  1. Use admin user for API keys
  2. Check WooCommerce → Settings → Advanced → REST API permissions
  3. Verify .htaccess not blocking API requests

Debug Mode​

Enable WooCommerce logging:

// In wp-config.php
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);

Check logs:

tail -f /path/to/wp-content/debug.log

Performance Optimization​

Batch Processing​

Pagination:

$page = 1;
do {
    $params['page'] = $page;
    $orders = $api->get('orders', $params);
    // Process orders...
    $page++;
} while (count($orders) === $params['per_page']);

Caching​

Cache product data:

$product_cache = wp_cache_get('products', 'gsm_middleware');
if (!$product_cache) {
    $product_cache = [];
    wp_cache_set('products', $product_cache, 'gsm_middleware', 300);
}

Testing​

Test with Single Order​

  1. Create test order in WooCommerce
  2. Note order number
  3. Go to GSM Middleware → Test Order
  4. Enter order number (e.g., "BGM-12345")
  5. Click "Test Order Import"
  6. Review results

Test Smart Coupons​

  1. Install WooCommerce Smart Coupons
  2. Create gift card coupon
  3. Apply to order
  4. Sync order
  5. Verify "COUPON" line item created

Test Variable Products​

  1. Create variable product with variations
  2. Order specific variation
  3. Sync order
  4. Verify correct variation SKU captured
  5. Check variation attributes stored

Troubleshooting​

Orders Not Syncing​

Check:

  1. Order status is "processing"
  2. API keys have Read/Write permissions
  3. REST API enabled
  4. Pretty permalinks enabled
  5. Order not already synced (sumatra_wc_integrator_exported meta)

Missing SKUs​

Check:

  1. Product has SKU assigned
  2. Variation has SKU (if variable product)
  3. SKU not empty string
  4. SKU exists in Business Central

Tax Not Calculated​

Check:

  1. WooCommerce tax enabled
  2. Ship state in configured tax states
  3. Tax classes configured
  4. Customer tax exempt flag

Best Practices​

  1. API Keys: Use dedicated admin account for API
  2. SSL: Always use HTTPS for WooCommerce REST API
  3. Permalinks: Keep "Post name" permalink structure
  4. Testing: Test in staging environment first
  5. Monitoring: Watch for failed API requests

Next Steps​