API Reference

Commerce Connect provides REST API endpoints for retrieving product, brand, and collection data, plus a GraphQL proxy for cart and checkout operations.

Overview

Base URL:

https://your-site.com/wp-json/wpe-commerce/v1/

Available APIs:

• Products API - Retrieve product data (REST)
• Brands API - Retrieve brand data (REST)
• Collections API - Retrieve collection/category data (REST)
• GraphQL Proxy - Cart, checkout, and customer operations (GraphQL)

Note: Cart, checkout, and customer operations use GraphQL, not REST endpoints. See GraphQL Proxy section below.

---

Products API

Retrieve product data for headless implementations or custom frontends.

Get Products

Retrieve a list of products with filtering and pagination.

Endpoint: GET /wp-json/wpe-commerce/v1/products

Authentication: None required (public endpoint)

Query Parameters:

• per_page (int) - Products per page (default: 10, max: 100)
• page (int) - Page number (default: 1)
• category (string) - Filter by category slug
• search (string) - Search products by title/description
• orderby (string) - Sort field: title, date, price (default: date)
• order (string) - Sort direction: asc or desc (default: desc)

Example Request:

curl -X GET "https://your-site.com/wp-json/wpe-commerce/v1/products?category=shoes&per_page=20&orderby=price&order=asc"

Example Response:

{
  "products": [
    {
      "id": 123,
      "name": "Running Shoes",
      "slug": "running-shoes",
      "price": 89.99,
      "sale_price": null,
      "description": "Comfortable running shoes...",
      "images": [
        {
          "url": "https://cdn.example.com/shoe-1.jpg",
          "alt": "Running Shoes - Front View"
        }
      ],
      "categories": ["shoes", "athletic"],
      "in_stock": true,
      "permalink": "https://your-site.com/product/running-shoes"
    }
  ],
  "total": 42,
  "pages": 3
}

Get Product by Slug

Retrieve a single product by its WordPress slug.

Endpoint: GET /wp-json/wpe-commerce/v1/products/{slug}

Authentication: None required

Example Request:

curl -X GET "https://your-site.com/wp-json/wpe-commerce/v1/products/running-shoes"

Example Response:

{
  "id": 123,
  "name": "Running Shoes",
  "slug": "running-shoes",
  "price": 89.99,
  "description": "Comfortable running shoes for everyday wear...",
  "images": [...],
  "variants": [
    {
      "id": 456,
      "name": "Size: 10",
      "price": 89.99,
      "in_stock": true
    }
  ],
  "categories": ["shoes", "athletic"],
  "tags": ["running", "sports"],
  "meta": {
    "sku": "SHOE-RUN-001",
    "weight": "1.2 lbs"
  }
}

Get Related Products

Retrieve products related to a specific product.

Endpoint: GET /wp-json/wpe-commerce/v1/products/{slug}/related

Authentication: None required

Query Parameters:

• per_page (int) - Number of related products (default: 4, max: 20)

Example Request:

curl -X GET "https://your-site.com/wp-json/wpe-commerce/v1/products/running-shoes/related?per_page=6"

---

Brands API

Retrieve brand data for filtering or navigation.

Get Brands

Retrieve all product brands.

Endpoint: GET /wp-json/wpe-commerce/v1/brands

Authentication: None required

Example Response:

{
  "brands": [
    {
      "id": 789,
      "name": "Nike",
      "slug": "nike",
      "product_count": 42
    },
    {
      "id": 790,
      "name": "Adidas",
      "slug": "adidas",
      "product_count": 38
    }
  ]
}

Get Brand by ID

Retrieve a single brand with its products.

Endpoint: GET /wp-json/wpe-commerce/v1/brands/{id}

Authentication: None required

Example Response:

{
  "id": 789,
  "name": "Nike",
  "slug": "nike",
  "description": "Leading athletic brand...",
  "products": [
    {
      "id": 123,
      "name": "Running Shoes",
      "slug": "running-shoes",
      "price": 89.99
    }
  ]
}

---

Collections API

Retrieve collection/category data.

Note: In BigCommerce terminology, “collections” are equivalent to “categories” in WordPress.

Get Collections

Retrieve all collections.

Endpoint: GET /wp-json/wpe-commerce/v1/collections

Authentication: None required

Example Response:

{
  "collections": [
    {
      "id": 101,
      "name": "Athletic Shoes",
      "slug": "athletic-shoes",
      "product_count": 28
    },
    {
      "id": 102,
      "name": "Casual Wear",
      "slug": "casual-wear",
      "product_count": 56
    }
  ]
}

---

GraphQL Proxy

Important: Commerce Connect uses BigCommerce’s GraphQL API for cart, checkout, and customer operations. There are no REST endpoints for these functions.

GraphQL Endpoint

Endpoint: POST /wp-json/wpe-commerce/v1/graphql

Authentication: None required (uses BigCommerce storefront token internally)

How it works:

1. Your JavaScript sends GraphQL queries to the WordPress proxy endpoint
2. The proxy forwards them to BigCommerce’s GraphQL API
3. BigCommerce handles cart, checkout, and customer operations
4. The proxy returns BigCommerce’s response

Request Format:

const response = await fetch('/wp-json/wpe-commerce/v1/graphql', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    query: `YOUR_GRAPHQL_QUERY`,
    variables: {
      // Query variables
    },
  }),
});

Example: Get Cart

const getCart = async () => {
  const response = await fetch('/wp-json/wpe-commerce/v1/graphql', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      query: `
        query GetCart($entityId: String!) {
          site {
            cart(entityId: $entityId) {
              entityId
              lineItems {
                physicalItems {
                  name
                  quantity
                  productEntityId
                  variantEntityId
                  extendedListPrice {
                    currencyCode
                    value
                  }
                }
              }
              amount {
                currencyCode
                value
              }
            }
          }
        }
      `,
      variables: {
        entityId: 'cart-id-from-cookie',
      },
    }),
  });

  return await response.json();
};

Example: Add to Cart

const addToCart = async (productId, variantId, quantity) => {
  const response = await fetch('/wp-json/wpe-commerce/v1/graphql', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      query: `
        mutation AddCartLineItems($input: AddCartLineItemsInput!) {
          cart {
            addCartLineItems(input: $input) {
              cart {
                entityId
                lineItems {
                  physicalItems {
                    name
                    quantity
                  }
                }
              }
            }
          }
        }
      `,
      variables: {
        input: {
          cartEntityId: 'cart-id-from-cookie',
          data: {
            lineItems: [
              {
                productEntityId: productId,
                variantEntityId: variantId,
                quantity: quantity,
              },
            ],
          },
        },
      },
    }),
  });

  return await response.json();
};

GraphQL Schema Reference

For complete GraphQL schema documentation, see:

• BigCommerce GraphQL Storefront API

Common operations:

• Cart: createCart, addCartLineItems, updateCartLineItem, deleteCartLineItem
• Checkout: createCheckout, addCheckoutShippingConsignments, completeCheckout
• Customer: login, register, requestPasswordReset, resetPassword
• Products: Get product details, variants, options, modifiers

---

Error Handling

All endpoints return consistent error responses:

{
  "code": "error_code",
  "message": "Human-readable error message",
  "data": {
    "status": 400
  }
}

Common HTTP Status Codes:

• 200 - Success
• 400 - Bad Request (invalid parameters)
• 404 - Not Found (product/brand/collection doesn’t exist)
• 500 - Server Error (WordPress or BigCommerce error)
• 502 - Bad Gateway (BigCommerce API unavailable)

JavaScript Error Handling:

async function apiCall(endpoint, data) {
  try {
    const response = await fetch(endpoint, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(data),
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.message || `HTTP ${response.status}`);
    }

    return await response.json();
  } catch (error) {
    console.error('API Error:', error.message);
    throw error;
  }
}

---

Rate Limiting

REST Endpoints: No specific rate limiting enforced by Commerce Connect. Standard WordPress REST API rate limiting applies (typically handled by hosting provider).

GraphQL Proxy: Subject to BigCommerce’s GraphQL API rate limits:

• Storefront API: 20 requests per second per store
• Exceeding limits returns 429 Too Many Requests

Best Practices:

• Implement client-side request throttling
• Cache product data when possible
• Use batch operations for multiple cart updates

---

CORS Configuration

REST and GraphQL endpoints support CORS for headless implementations:

Default behavior:

• Same-origin requests: Allowed by default
• Cross-origin requests: Must be explicitly allowed

Enable CORS for headless frontend:

Add to your theme’s functions.php or custom plugin:

<?php
add_filter('rest_pre_serve_request', function($served, $result, $request, $server) {
  // Allow specific origin (replace with your frontend domain)
  header('Access-Control-Allow-Origin: https://your-frontend-domain.com');
  header('Access-Control-Allow-Methods: GET, POST, OPTIONS');
  header('Access-Control-Allow-Headers: Content-Type, X-WP-Nonce');
  header('Access-Control-Allow-Credentials: true');

  return $served;
}, 10, 4);

Production recommendations:

• Only allow specific trusted origins
• Use environment variables for domain configuration
• Enable credentials only when necessary

---

Related Resources

• BigCommerce GraphQL API Documentation
• Hooks & Filters - Customize API behavior
• Custom Blocks - Build custom product displays
• Architecture Overview - Understanding the plugin structure