Quick Start (Developer)

Get started with Commerce Connect development by building your first customization. This guide walks you through the architecture, hooks, and custom block development.

What You’ll Accomplish

By the end of this guide, you’ll have:

• ✅ Understanding of Commerce Connect architecture
• ✅ First custom hook implemented
• ✅ Custom block created and working
• ✅ Development environment configured

---

Prerequisites

• WordPress development environment (Local, Lando, or similar)
• Commerce Connect plugin installed and connected to BigCommerce
• Basic knowledge of WordPress hooks and React
• Code editor (VS Code, PHPStorm, etc.)

Need Installation Help?

See Installation Guide for setting up Commerce Connect first.

---

Step 1: Understand the Architecture

Commerce Connect creates a bridge between WordPress and BigCommerce:

┌──────────────┐     ┌────────────────────┐     ┌──────────────┐
│              │     │                    │     │              │
│  BigCommerce │────▶│ Commerce Connect  │────▶│  WordPress   │
│  (Source)    │     │  (Bridge + Cache) │     │  (Display)   │
│              │◀────│                    │◀────│              │
└──────────────┘     └────────────────────┘     └──────────────┘
     │                        │                         │
     │                        │                         │
  Products              Webhooks + API             FSE Blocks
  Checkout              Product Cache              Content Pages
  Orders                 Sync Engine                SEO Output

Key Concepts

Data Flow:

1. Products live in BigCommerce (source of truth)
2. Commerce Connect syncs product data to WordPress via BigCommerce API
3. Product data cached in WordPress custom post types
4. Blocks render cached data for fast page loads
5. “Add to Cart” / “Checkout” redirect to BigCommerce hosted checkout

Why This Architecture?

• BigCommerce strengths: Commerce, payments, PCI compliance, fraud protection
• WordPress strengths: Content, SEO, page building, marketing
• Commerce Connect: Combines both platforms’ strengths

---

Step 2: Explore the Hooks System

Commerce Connect provides 27+ hooks for customization. Let’s implement one.

Example: Modify Product Price Display

Goal: Add “(Special Offer!)” text to sale prices.

Hook: commerce_connect_product_price_html

Implementation:

<?php
/**
 * Plugin Name: Commerce Connect - Price Customization
 * Description: Add "Special Offer!" to sale prices
 * Version: 1.0.0
 */

add_filter('commerce_connect_product_price_html', 'add_special_offer_text', 10, 2);

function add_special_offer_text($price_html, $product) {
    // Check if product is on sale
    if ($product->sale_price && $product->sale_price < $product->calculated_price) {
        // Add special offer badge
        $price_html .= ' <span class="special-offer-badge" style="color: #e74c3c; font-weight: bold;">(Special Offer!)</span>';
    }

    return $price_html;
}

Install:

1. Create file: wp-content/mu-plugins/cc-price-customization.php
2. Paste code above
3. Reload any product page

Result: Sale prices now show “(Special Offer!)” badge.

Available Hook Categories

Product Hooks (9):

• commerce_connect_product_data - Modify product data before display
• commerce_connect_product_price_html - Customize price formatting
• commerce_connect_product_title - Modify product titles
• View all product hooks →

Block Hooks (7):

• commerce_connect_block_attributes - Modify block attributes
• commerce_connect_block_render - Customize block output
• View all block hooks →

Sync Hooks (6):

• commerce_connect_before_product_sync - Run code before sync
• commerce_connect_after_product_sync - Run code after sync
• View all sync hooks →

API Hooks (5):

• commerce_connect_api_request - Modify API requests
• commerce_connect_api_response - Process API responses
• View all API hooks →

Full reference: Hooks & Filters

---

Step 3: Build a Custom Block

Now create a custom block that displays product stock status.

Block Structure

my-custom-block/
├── src/
│   ├── index.js       # Block registration
│   ├── edit.js        # Editor component
│   ├── save.js        # Frontend output
│   └── style.scss     # Block styles
├── block.json         # Block metadata
└── package.json       # Dependencies

1. Create Block Directory

cd wp-content/plugins
mkdir cc-stock-status-block
cd cc-stock-status-block

2. Initialize Block

npm init -y
npm install @wordpress/scripts @wordpress/blocks @wordpress/block-editor --save-dev

3. Create block.json

{
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 3,
  "name": "commerce-connect/stock-status",
  "title": "Product Stock Status",
  "category": "commerce-connect",
  "icon": "products",
  "description": "Display product stock availability with visual indicator",
  "supports": {
    "html": false,
    "align": true
  },
  "attributes": {
    "productId": {
      "type": "number",
      "default": 0
    },
    "showQuantity": {
      "type": "boolean",
      "default": true
    }
  },
  "textdomain": "commerce-connect-stock",
  "editorScript": "file:./build/index.js",
  "editorStyle": "file:./build/index.css",
  "style": "file:./build/style-index.css"
}

4. Create src/index.js

import { registerBlockType } from '@wordpress/blocks';
import Edit from './edit';
import save from './save';
import './style.scss';

registerBlockType('commerce-connect/stock-status', {
  edit: Edit,
  save,
});

5. Create src/edit.js

import { useBlockProps, InspectorControls } from '@wordpress/block-editor';
import { PanelBody, ToggleControl } from '@wordpress/components';
import { useSelect } from '@wordpress/data';

export default function Edit({ attributes, setAttributes }) {
  const { productId, showQuantity } = attributes;

  // Get product data from Commerce Connect store
  const product = useSelect(
    (select) => {
      return select('commerce-connect/products').getProduct(productId);
    },
    [productId],
  );

  const blockProps = useBlockProps();

  return (
    <>
      <InspectorControls>
        <PanelBody title="Stock Status Settings">
          <ToggleControl
            label="Show Quantity"
            checked={showQuantity}
            onChange={(value) => setAttributes({ showQuantity: value })}
          />
        </PanelBody>
      </InspectorControls>

      <div {...blockProps}>
        {product ? (
          <div className="stock-status">
            <span className={`status-indicator ${product.inventory_level > 0 ? 'in-stock' : 'out-of-stock'}`}>
              {product.inventory_level > 0 ? '✓ In Stock' : '✗ Out of Stock'}
            </span>
            {showQuantity && product.inventory_level > 0 && (
              <span className="quantity">({product.inventory_level} available)</span>
            )}
          </div>
        ) : (
          <p>Select a product to display stock status</p>
        )}
      </div>
    </>
  );
}

6. Create src/save.js

import { useBlockProps } from '@wordpress/block-editor';

export default function save({ attributes }) {
  const { productId, showQuantity } = attributes;

  return (
    <div {...useBlockProps.save()}>
      <div className="cc-stock-status" data-product-id={productId} data-show-quantity={showQuantity}>
        {/* Dynamic content rendered via PHP */}
      </div>
    </div>
  );
}

7. Create PHP Render Function

Create cc-stock-status-block.php:

<?php
/**
 * Plugin Name: Commerce Connect - Stock Status Block
 * Description: Display product stock availability
 * Version: 1.0.0
 */

// Register block
function cc_stock_status_register_block() {
    register_block_type(__DIR__ . '/build', [
        'render_callback' => 'cc_stock_status_render',
    ]);
}
add_action('init', 'cc_stock_status_register_block');

// Render callback
function cc_stock_status_render($attributes) {
    $product_id = $attributes['productId'] ?? 0;
    $show_quantity = $attributes['showQuantity'] ?? true;

    if (!$product_id) {
        return '<p>No product selected</p>';
    }

    // Get product from Commerce Connect
    $product = \WP_Engine\CommerceConnect\Products\Product::get($product_id);

    if (!$product) {
        return '<p>Product not found</p>';
    }

    $in_stock = $product->inventory_level > 0;
    $status_class = $in_stock ? 'in-stock' : 'out-of-stock';
    $status_text = $in_stock ? '✓ In Stock' : '✗ Out of Stock';

    $html = sprintf(
        '<div class="cc-stock-status"><span class="status-indicator %s">%s</span>',
        esc_attr($status_class),
        esc_html($status_text)
    );

    if ($show_quantity && $in_stock) {
        $html .= sprintf(
            ' <span class="quantity">(%d available)</span>',
            absint($product->inventory_level)
        );
    }

    $html .= '</div>';

    return $html;
}

8. Build Block

npm run build

9. Activate Plugin

1. Navigate to Plugins in WordPress admin
2. Find “Commerce Connect - Stock Status Block”
3. Click Activate

Result: New block available in block inserter under “Commerce Connect” category.

---

Step 4: Test Your Customization

Test the Hook

1. Open any product page with a sale price
2. Verify “(Special Offer!)” text appears after price
3. Inspect element to confirm custom HTML

Test the Block

1. Create a new page
2. Add “Product Stock Status” block
3. Select a product
4. Toggle “Show Quantity” setting
5. Publish and verify frontend display

---

What’s Next?

Explore More Hooks

Recommended hooks to try:

• commerce_connect_add_to_cart_url - Customize cart behavior
• commerce_connect_product_image_size - Control image sizes
• commerce_connect_sync_batch_size - Optimize sync performance

Full list: Hooks & Filters Reference

Build Advanced Blocks

Ideas for custom blocks:

• Product comparison table
• Recently viewed products
• Custom product filters
• Personalized product recommendations

Guide: Custom Blocks

Work with the API

Query product data directly:

// Get single product
$product = \WP_Engine\CommerceConnect\API\Client::get_product(123);

// Search products
$results = \WP_Engine\CommerceConnect\API\Client::search_products([
    'keyword' => 'shoes',
    'category' => 'footwear',
    'min_price' => 50,
]);

// Get variants
$variants = \WP_Engine\CommerceConnect\API\Client::get_product_variants(123);

Documentation: API Reference

Debug and Troubleshoot

Enable debug mode:

wp-config.php

define('CC_DEBUG', true);
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);

View debug logs:

tail -f wp-content/debug.log

Common issues:

• Block not appearing
• Products not syncing
• API errors

---

Development Resources

Official Documentation

• Architecture Overview - System design and data flow
• Hooks & Filters - Complete hooks reference (27+)
• Custom Blocks - Block development guide
• API Reference - REST API and PHP classes

Code Examples

Browse real-world examples in the plugin source:

# Product blocks
wp-content/plugins/commerce-connect/blocks/product-*

# Sync engine
wp-content/plugins/commerce-connect/includes/sync/

# API client
wp-content/plugins/commerce-connect/includes/api/

Community Support

• WP Engine Support - Official support channel
• GitHub Issues - Bug reports and feature requests
• Developer Forums - Community discussions

---

Need Help?

Common developer questions:

• How do I debug sync issues?
• How do I customize block styling?
• How do I optimize performance?

Still stuck? Contact WP Engine Support with your development question.