BigCommerce Product API Guide: Working With Product Data and Custom Fields

Managing product data programmatically is critical for scaling your BigCommerce store. The BigCommerce product API allows developers to automate product creation, updates, and custom field management without manual data entry. Whether you’re syncing inventory from an ERP system or building custom integrations, understanding how the API handles product data will save you countless hours while reducing errors.

This guide covers everything you need to work effectively with the BigCommerce product API, including practical implementation strategies for both API v2 and v3.

Summary

• API version differences: Learn when to use BigCommerce product API v3 versus legacy v2 endpoints and their unique capabilities
• Authentication setup: Establish secure OAuth connections and manage API credentials for production environments
• Product creation workflows: Build automated processes for adding new products with complete attribute sets
• Custom field implementation: Store and retrieve additional product metadata beyond standard fields
• Error handling strategies: Implement robust validation and recovery mechanisms for API operations

Now that you understand what we’ll cover, let’s examine the core differences between BigCommerce’s API versions.

Understanding BigCommerce Product API Versions

BigCommerce offers two primary API versions for working with product data, each designed for different use cases and development approaches.

BigCommerce Product API v2: Legacy Foundation

The BigCommerce API product v2 launched in 2013 as the platform’s first RESTful interface. This version provides straightforward XML/JSON responses with basic authentication using API keys. Many existing integrations still rely on v2 endpoints due to their stability and extensive community documentation.

Key characteristics of API v2 include rate limits of 20,000 requests per hour, simple authentication patterns, and widespread third-party tool support. The v2 architecture works well for basic product CRUD operations where advanced features aren’t required.

BigCommerce Product API v3: Modern Standards

Released in 2020, the BigCommerce product API v3 represents the platform’s current recommended approach. This version implements OAuth 2.0 security, GraphQL query support, and more granular endpoint structures. BigCommerce actively develops v3 with new features and improvements.

The v3 API introduces better performance through optimized data structures, enhanced security with token-based authentication, and more flexible query parameters. Rate limits increase to 450 requests per 30 seconds for standard stores, providing better throughput for high-volume operations.

Comparing API Architecture

When choosing between versions, consider your security requirements and feature needs. New projects should default to v3 unless specific v2 functionality is absolutely necessary. Some integrations may use both APIs simultaneously when accessing features unique to each version.

Now let’s explore how to properly authenticate your API requests.

Setting Up BigCommerce API Authentication

Proper authentication ensures secure access to your store’s product data while preventing unauthorized modifications. The process differs significantly between API v2 and v3.

Generating API Credentials

Navigate to your BigCommerce control panel and access Advanced Settings > API Accounts. Click “Create API Account” and select “V2/V3 API Token” to generate credentials for both versions simultaneously.

You’ll need to configure OAuth scopes during credential generation. For product management, enable the following minimum scopes:

• Products: read-only or modify
• Content: read-only (for linked resources)
• Information & Settings: read-only

BigCommerce generates three critical values: your Client ID, Client Secret, and Access Token. Store these securely in environment variables rather than hardcoding them in your application. Never commit API credentials to version control systems.

Implementing OAuth Authentication for BigCommerce Product API v3

The BigCommerce API product v3 requires OAuth headers in every request. Your application must include the X-Auth-Token header with your access token value:

X-Auth-Token: your_access_token_here

Content-Type: application/json

Accept: application/json

Unlike traditional OAuth flows, BigCommerce uses a simplified approach where you receive permanent access tokens during credential generation. These tokens don’t expire unless you regenerate or delete the API account. This design eliminates the complexity of token refresh mechanisms common in other OAuth implementations.

For production environments, implement request signing to verify webhook authenticity and protect against replay attacks. Use HTTPS exclusively when transmitting API credentials or making requests.

Rate Limiting Considerations

The BigCommerce product API v3 enforces rate limits to maintain platform stability. Standard stores receive 450 requests per 30-second window, while Plus and Enterprise tiers receive higher allocations. When you exceed the limit, the API returns a 429 status code.

Implement exponential backoff when receiving rate limit errors. Start with a 1-second delay, doubling it with each subsequent failure up to a maximum of 60 seconds. This approach prevents overwhelming the API while maximizing your request throughput.

Monitor the X-Rate-Limit-Remaining header in API responses to track your current allocation. When this value drops below 50, implement request queuing to prevent hitting the limit.

With authentication configured, you’re ready to create your first product.

Creating Products With the BigCommerce Product API

Product creation forms the foundation of catalog management through the API. Understanding required fields, optional attributes, and data validation ensures successful product additions.

Required Product Attributes

Every BigCommerce API product creation requires four mandatory fields: name, type, price, and weight. The name field accepts up to 250 characters and serves as the primary product identifier. Product type must be either “physical” for shippable items or “digital” for downloadable content.

Price values should be submitted as decimal strings (e.g., “29.99”) rather than floats to prevent rounding errors. The weight field requires a numeric value based on your store’s default weight unit, typically pounds or kilograms.

Building a Product Creation Request

The /v3/catalog/products endpoint accepts POST requests with a JSON payload containing product attributes. Here’s a minimal viable product:

json

{

  “name”: “Premium Wireless Headphones”,

  “type”: “physical”,

  “sku”: “WH-2024-001”,

  “price”: “149.99”,

  “weight”: 0.75,

  “categories”: [23],

  “description”: “High-fidelity audio with 30-hour battery life”,

  “inventory_level”: 50,

  “inventory_tracking”: “product”

}

This example creates a physical product with inventory tracking enabled. The categories array accepts category IDs from your store’s existing category tree. Omitting this field creates an uncategorized product.

Advanced Product Attributes

Beyond the basics, the BigCommerce product API supports numerous optional fields for comprehensive product definitions:

Pricing Fields:

• cost_price: Your wholesale cost for margin calculations
• retail_price: Original MSRP for displaying savings
• sale_price: Discounted price that overrides the base price
• map_price: Minimum advertised price for compliance

SEO Optimization:

• page_title: Custom HTML title tag (70 characters maximum)
• meta_description: Search result snippet text (160 characters maximum)
• meta_keywords: Legacy SEO field, minimal impact
• search_keywords: Internal site search terms

Visibility Controls:

• is_visible: Boolean controlling storefront display
• is_featured: Flags product for homepage/special sections
• availability: Values include “available”, “preorder”, or “disabled”

Product Creation Response Handling

Successful creation returns HTTP 201 with the complete product object, including the generated product ID. This ID is essential for subsequent operations like adding images, custom fields, or variants.

json

{

  “data”: {

    “id”: 234,

    “name”: “Premium Wireless Headphones”,

    “sku”: “WH-2024-001”,

    “calculated_price”: 149.99,

    “date_created”: “2026-01-19T10:30:00Z”,

    “base_variant_id”: 512

  }

}

Store the returned product ID and base_variant_id in your system for future reference. The base_variant_id represents the default variant automatically created for each product.

Now let’s examine how to modify existing products.

Updating Product Data

Updating products through the BigCommerce product API allows you to modify attributes, adjust pricing, and maintain accurate inventory without manual control panel access.

Partial vs. Complete Updates

The BigCommerce API product v3 supports partial updates using PUT requests to /v3/catalog/products/{product_id}. You only need to include fields you want to modify—unchanged attributes remain intact.

For example, updating only the price and inventory:

json

{

  “price”: “139.99”,

  “inventory_level”: 35

}

This approach minimizes request payload sizes and reduces the risk of accidentally modifying fields. Complete product replacements are rarely necessary unless performing major restructuring.

Batch Product Updates

When updating multiple products, use the batch update endpoint rather than individual requests. This method processes up to 10 products per request, significantly reducing API calls:

PUT /v3/catalog/products

The payload accepts an array of product objects, each requiring an ID field to identify which product to update. BigCommerce processes these atomically—all updates succeed or all fail together.

Handling Update Conflicts

When multiple systems update the same product simultaneously, use the date_modified field to implement optimistic locking. Before submitting updates, verify the current date_modified matches your cached value. If they differ, another process has modified the product since you last retrieved it.

This pattern prevents accidentally overwriting changes from other integrations or admin panel updates. Implement a refresh-and-retry mechanism when conflicts are detected.

Inventory Management

Inventory updates deserve special attention due to their business impact. The BigCommerce product API provides two fields for stock management:

• inventory_level: Current stock quantity for the product
• inventory_warning_level: Threshold triggering low-stock notifications

Set inventory_tracking to “product” to enable stock decrements during checkout. Use “none” for services or made-to-order items where stock doesn’t apply. Never use “variant” when products lack options—this causes API errors.

With updates covered, let’s explore product deletion and archival strategies.

Managing Product Lifecycle

Beyond creation and updates, effective product management includes deletion, archival, and bulk operations for efficient catalog maintenance.

Soft Deletion vs. Hard Deletion

The BigCommerce product API treats deletion as permanent removal. Unlike some platforms, there’s no built-in trash or recovery mechanism. Before deleting products, consider setting is_visible to false as a soft-delete alternative.

Soft deletion preserves product data, order history, and customer reviews while hiding items from the storefront. This approach maintains referential integrity and allows future product reinstatement without data recreation.

Bulk Deletion Operations

To delete multiple products efficiently, send DELETE requests to /v3/catalog/products with a query parameter array:

DELETE /v3/catalog/products?id:in=234,235,236

This endpoint removes up to 250 products per request. For larger deletion operations, implement batching logic to process products in chunks while respecting rate limits.

Product Variant Deletion

When products have variants, deleting the parent product automatically removes all associated variants, images, and custom fields. This cascading deletion simplifies cleanup but requires careful planning.

To remove individual variants without affecting the parent product, use the variant-specific endpoint:

DELETE /v3/catalog/products/{product_id}/variants/{variant_id}

Now that we’ve covered basic product operations, let’s explore how custom fields extend product data.

Define Custom Product Fields BigCommerce API

Custom fields allow you to store additional product information beyond BigCommerce’s standard attributes. These fields power everything from specification tables to integration metadata.

What Are BigCommerce Custom Fields?

Custom fields consist of name-value pairs attached to products. Each field has a maximum value length of 250 characters, making them suitable for short text, codes, or simple data points. The BigCommerce API product supports unlimited custom fields per product, though practical performance limits suggest keeping counts under 50 fields.

Common use cases include:

• Product specifications (dimensions, materials, certifications)
• Integration identifiers (ERP SKUs, warehouse codes)
• Display flags (badges, special handling indicators)
• External references (manufacturer part numbers, UPC codes)

Creating Custom Fields

To define custom product fields BigCommerce API operations use the endpoint /v3/catalog/products/{product_id}/custom-fields with a POST request:

json

{

  “name”: “Warranty Period”,

  “value”: “2 Years Limited”

}

Each name-value pair must be unique within the product. Attempting to create duplicate combinations returns a 422 error. Update existing fields instead of creating duplicates.

Retrieving Custom Field Data

Fetch all custom fields for a product using GET requests:

GET /v3/catalog/products/{product_id}/custom-fields

The response includes an array of field objects, each containing an ID, name, and value. Use the custom_field_id for subsequent update or delete operations.

Response pagination applies when products have many custom fields. The default page size returns 50 fields; adjust using the limit parameter up to 250.

Updating Custom Fields

Modify existing custom fields with PUT requests to the field-specific endpoint:

PUT /v3/catalog/products/{product_id}/custom-fields/{custom_field_id}

You can update either the name, value, or both fields in a single request:

json

{

  “name”: “Warranty Period”,

  “value”: “3 Years Extended”

}

Remember that name-value pairs must remain unique after updates. Changing a name to match an existing field causes validation failures.

Custom Fields vs. Metafields

While custom fields excel at simple data storage, BigCommerce also offers metafields for more complex scenarios. The key differences:

Choose custom fields when:

• Data length stays under 250 characters
• Non-technical staff need admin panel access
• Simple key-value storage suffices
• Enterprise plan filtering features are required

Select metafields when:

• Storing extensive descriptions or specifications
• Managing multi-language content variants
• Implementing complex data structures
• SEO content blocks are needed

Now let’s examine practical implementation patterns.

Working With Product Variants and Options

Products with multiple configurations require variant and option management through the BigCommerce product API. Understanding these relationships is critical for complex catalog structures.

Option Sets and Product Options

Options define the characteristics customers select (size, color, material). Option sets group related options for reuse across multiple products. When working with the BigCommerce API product operations, you’ll typically reference existing option sets rather than creating them per product.

Create products with options by specifying an option_set_id during product creation or through subsequent updates. Each option can have multiple values (e.g., the “Size” option might include Small, Medium, Large values).

Creating Product Variants

Variants represent specific combinations of option values. A t-shirt with three sizes and four colors generates 12 variants (3 × 4). The API automatically creates these combinations when you define options, or you can create them individually for precise control.

Each variant maintains its own:

• SKU identifier
• Price adjustments (positive or negative)
• Inventory levels
• Weight specifications
• Image associations

Variant-Level Inventory Management

When products use variant-level inventory tracking, set inventory_tracking to “variant” on the parent product. Each variant then maintains independent stock counts, allowing precise inventory control for specific configurations.

This approach is essential for products where certain combinations (e.g., Red/Large) might stock out while others remain available.

Let’s now explore error handling and troubleshooting strategies.

Error Handling and Troubleshooting

Robust error handling separates production-ready integrations from fragile implementations. The BigCommerce product API uses standard HTTP status codes with detailed error messages.

Common API Errors

422 Unprocessable Entity occurs when request data fails validation rules. The response includes specific field errors:

json

{

  “status”: 422,

  “title”: “The product was not valid”,

  “errors”: {

    “price”: “Price must be greater than 0”

  }

}

Address each error in the errors object before retrying the request.

404 Not Found indicates the requested product ID doesn’t exist. Verify IDs before operations and implement existence checks for critical workflows.

409 Conflict signals constraint violations, typically unique field duplicates like SKUs. Ensure SKU uniqueness across your catalog or leave the field empty for auto-generation.

Validation Best Practices

Implement client-side validation before sending API requests:

1. Verify required fields are present and non-empty
2. Check string lengths against maximum values
3. Validate numeric ranges for price and weight
4. Ensure array fields contain valid IDs
5. Confirm boolean fields use proper true/false values

This proactive approach reduces unnecessary API calls and improves response times.

Request Timeout Handling

Network issues or high server load can cause request timeouts. Implement retry logic with exponential backoff:

Attempt 1: Immediate

Attempt 2: Wait 2 seconds

Attempt 3: Wait 4 seconds

Attempt 4: Wait 8 seconds

Set a maximum retry count (typically 3-5) to prevent infinite loops. Log failures that exceed retry limits for manual investigation.

Logging and Monitoring

Comprehensive logging helps diagnose integration issues. Capture:

• Request timestamps and endpoints
• Complete request payloads (excluding sensitive data)
• Response status codes and bodies
• Error messages and stack traces
• Correlation IDs for tracking request chains

Use structured logging formats (JSON) for easier analysis and alerting. Monitor error rates to detect degraded API performance or systematic integration problems.

With error handling covered, let’s examine performance optimization techniques.

Optimizing API Performance

Efficient API usage improves integration speed, reduces costs, and provides better user experiences. Several strategies help maximize BigCommerce product API performance.

Request Batching

Instead of individual product operations, batch related requests together. The BigCommerce API product v3 supports batch endpoints for creating and updating multiple products:

POST /v3/catalog/products

Send an array of product objects rather than making 100 individual requests for 100 products. Each batch can contain up to 10 products, reducing total request counts by 90%.

Field Filtering

The BigCommerce product API allows you to request only needed fields using the include_fields parameter:

GET /v3/catalog/products/234?include_fields=id,name,price,inventory_level

This reduces response payload sizes, accelerating data transfer and JSON parsing. Particularly valuable when fetching product lists where you only need specific attributes.

Pagination Strategies

When retrieving product catalogs, implement cursor-based pagination instead of offset-based approaches. Cursor pagination handles large datasets more efficiently and avoids the “page shift” problem when products are added during multi-page retrievals.

Caching Strategies

Implement response caching to minimize redundant API calls. Product data typically changes infrequently, making it ideal for caching. Use cache expiration times based on your update frequency:

• Static products: 24-hour cache
• Regular updates: 1-hour cache
• Real-time inventory: 5-minute cache

Include cache-control headers in your requests and respect ETags returned by the API for conditional requests.

Webhook Integration

Rather than polling for changes, implement webhooks to receive real-time notifications. BigCommerce sends webhook events when products are created, updated, or deleted. This event-driven approach eliminates unnecessary API requests while maintaining data synchronization.

Configure webhooks through the BigCommerce API integration setup to receive product change notifications directly in your application.

Now let’s explore practical implementation examples.

Practical Implementation Examples

Real-world scenarios demonstrate how to combine BigCommerce product API capabilities into functional integrations.

Example 1: Product Import From CSV

Many businesses need to import products from spreadsheets or legacy systems. Here’s a pattern for CSV-to-API conversion:

1. Parse CSV file and validate required fields
2. Map CSV columns to BigCommerce product attributes
3. Batch products into groups of 10
4. Submit each batch with error handling
5. Log successful imports and failures
6. Generate summary report with product IDs

This workflow handles thousands of products efficiently while providing visibility into the import process. Implement resume capability to handle interrupted imports without reprocessing successfully created products.

Example 2: Price Synchronization

E-commerce operations often require automated pricing updates from ERP or pricing management systems. Effective synchronization:

1. Query external system for price changes
2. Fetch affected BigCommerce products by SKU
3. Compare current prices with new prices
4. Batch update only products with price differences
5. Log price history for audit purposes

This selective update approach minimizes API calls compared to full catalog updates. Schedule price synchronization during low-traffic periods to optimize store performance.

Example 3: Inventory Management

Real-time inventory synchronization prevents overselling and maintains accurate stock levels:

1. Listen for webhooks from inventory management system
2. Map inventory SKU to BigCommerce product
3. Update inventory_level through API
4. Set inventory_warning_level based on reorder points
5. Trigger notifications when stock falls below threshold

Implement queue-based processing to handle high-volume inventory updates without overwhelming the API. This architecture provides resilience during traffic spikes.

These patterns apply to various e-commerce integrations across different platforms.

Advanced Topics and Best Practices

Taking your BigCommerce product API integration to the next level requires understanding advanced capabilities and following industry best practices.

Multi-Channel Product Management

When selling across multiple channels, maintain a single source of truth in BigCommerce. Use channel-specific fields for marketplace variations:

• Amazon listings require UPC codes (store in custom fields)
• eBay needs specific condition values
• Google Shopping demands GTIN compliance

Structure custom fields with channel prefixes to organize marketplace-specific data:

json

{

  “name”: “amazon_condition”,

  “value”: “New”

},

{

  “name”: “ebay_category_id”,

  “value”: “11450”

}

API Version Migration

If you’re currently using API v2, plan your migration to v3 carefully:

1. Audit current v2 endpoint usage
2. Identify v3 equivalents for each endpoint
3. Test v3 functionality in sandbox environment
4. Implement parallel requests during transition
5. Monitor error rates and performance metrics
6. Gradually shift traffic to v3 endpoints
7. Deprecate v2 code once v3 proves stable

Run both versions simultaneously during migration to enable quick rollback if issues arise. This dual-track approach minimizes business risk.

Security Considerations

Protect your API credentials and implement security best practices:

• Store credentials in environment variables or secret managers
• Use HTTPS exclusively for all API communications
• Implement IP whitelisting when possible
• Rotate access tokens periodically
• Monitor API access logs for unusual patterns
• Never log full request/response bodies containing sensitive data

For applications handling customer data, ensure compliance with PCI DSS, GDPR, and other relevant regulations.

Testing Strategies

Comprehensive testing prevents production issues:

Unit Tests: Mock API responses to test business logic without live API calls

Integration Tests: Use BigCommerce sandbox stores for end-to-end testing with real API endpoints

Load Tests: Simulate high-volume operations to verify rate limit handling and performance under stress

Error Scenario Tests: Intentionally trigger error conditions to validate error handling code paths

Maintain a dedicated test store that mirrors your production catalog structure. This environment enables safe experimentation with API features.

Similar testing approaches apply to BigCommerce migrations and integrations.

Key Takeaways

• Start with API v3 for all new integrations to leverage modern features, better security, and active development support
• Implement robust error handling with retry logic, validation, and comprehensive logging to build resilient integrations
• Use custom fields strategically for storing additional product metadata while understanding their 250-character limitation
• Optimize performance through request batching, field filtering, and webhook integration to minimize API calls
• Plan for scale with proper caching, pagination, and rate limit management as your catalog grows

Frequently Asked Questions

What Is the Difference Between BigCommerce API v2 and v3 for Products?

The BigCommerce product API v3 uses OAuth 2.0 authentication instead of basic auth, provides REST and GraphQL query options, and offers better rate limits at 450 requests per 30 seconds. V3 is actively maintained while v2 receives only critical security updates.

How Do I Define Custom Product Fields BigCommerce API?

Use POST requests to /v3/catalog/products/{product_id}/custom-fields with JSON payloads containing name and value fields. Each custom field can store up to 250 characters and must be unique within the product.

Can I Use Both BigCommerce Product API Versions Simultaneously?

Yes, you can make requests to both v2 and v3 endpoints from the same application using the same API credentials. Many integrations use v3 for standard operations while accessing v2 for features not yet available in v3.

What Rate Limits Apply to the BigCommerce API Product Endpoints?

Standard stores receive 450 requests per 30-second window for v3 endpoints. Plus stores get 600 requests, while Enterprise stores receive custom allocations. Monitor the X-Rate-Limit-Remaining header to track your current quota.

How Do I Handle Inventory Tracking for Product Variants?

Set the parent product’s inventory_tracking field to “variant” and manage stock levels individually for each variant through /v3/catalog/products/{product_id}/variants/{variant_id} endpoints. This enables precise inventory control for specific size/color combinations.

What’s the Maximum Character Limit for Custom Field Values?

Custom field values have a 250-character maximum in the BigCommerce product API. For longer content, use metafields instead, which support up to 65,535 characters and provide namespace organization.

How Do I Bulk Update Product Prices?

Send PUT requests to /v3/catalog/products with an array containing product IDs and new price values. Each batch can process up to 10 products simultaneously, minimizing the total number of API calls required.

Can I Retrieve Products by SKU Instead of ID?

Yes, use the query parameter sku=YOUR_SKU in GET requests to /v3/catalog/products. This returns products matching the specified SKU, allowing lookups without knowing internal product IDs.

Conclusion

The BigCommerce product API provides comprehensive capabilities for programmatic catalog management, from basic product creation to advanced custom field operations. Start with v3 for new projects, leverage custom fields for additional metadata, and follow best practices for security and performance.

Ready to build your BigCommerce integration? Contact our team of e-commerce development experts to discuss your specific requirements and explore how we can help optimize your online store’s API implementation.