{"id":16788,"date":"2026-01-23T10:03:28","date_gmt":"2026-01-23T10:03:28","guid":{"rendered":"https:\/\/ecommerce.folio3.com\/blog\/?p=16788"},"modified":"2026-01-23T18:33:32","modified_gmt":"2026-01-23T18:33:32","slug":"bigcommerce-product-api","status":"publish","type":"post","link":"https:\/\/ecommerce.folio3.com\/blog\/bigcommerce-product-api\/","title":{"rendered":"BigCommerce Product API Guide: Working With Product Data and Custom Fields"},"content":{"rendered":"<p><span style=\"font-weight: 400;\">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&#8217;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.<\/span><\/p>\n<p><span style=\"font-weight: 400;\">This guide covers everything you need to work effectively with the BigCommerce product API, including practical implementation strategies for both API v2 and v3.<\/span><\/p>\n<h2><span style=\"font-weight: 400;\">Summary<\/span><\/h2>\n<ul>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><b>API version differences<\/b><span style=\"font-weight: 400;\">: Learn when to use BigCommerce product API v3 versus legacy v2 endpoints and their unique capabilities<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><b>Authentication setup<\/b><span style=\"font-weight: 400;\">: Establish secure OAuth connections and manage API credentials for production environments<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><b>Product creation workflows<\/b><span style=\"font-weight: 400;\">: Build automated processes for adding new products with complete attribute sets<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><b>Custom field implementation<\/b><span style=\"font-weight: 400;\">: Store and retrieve additional product metadata beyond standard fields<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><b>Error handling strategies<\/b><span style=\"font-weight: 400;\">: Implement robust validation and recovery mechanisms for API operations<\/span><\/li>\n<\/ul>\n<p><span style=\"font-weight: 400;\">Now that you understand what we&#8217;ll cover, let&#8217;s examine the core differences between BigCommerce&#8217;s API versions.<\/span><\/p>\n<h2><span style=\"font-weight: 400;\">Understanding BigCommerce Product API Versions<\/span><\/h2>\n<p><span style=\"font-weight: 400;\">BigCommerce offers two primary API versions for working with product data, each designed for different use cases and development approaches.<\/span><\/p>\n<h3><span style=\"font-weight: 400;\">BigCommerce Product API v2: Legacy Foundation<\/span><\/h3>\n<p><span style=\"font-weight: 400;\">The BigCommerce API product v2 launched in 2013 as the platform&#8217;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.<\/span><\/p>\n<p><span style=\"font-weight: 400;\">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&#8217;t required.<\/span><\/p>\n<h3><span style=\"font-weight: 400;\">BigCommerce Product API v3: Modern Standards<\/span><\/h3>\n<p><span style=\"font-weight: 400;\">Released in 2020, the BigCommerce product API v3 represents the platform&#8217;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.<\/span><\/p>\n<p><span style=\"font-weight: 400;\">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.<\/span><\/p>\n<h4><span style=\"font-weight: 400;\">Comparing API Architecture<\/span><\/h4>\n<table>\n<tbody>\n<tr>\n<td><b>Feature<\/b><\/td>\n<td><b>API v2<\/b><\/td>\n<td><b>API v3<\/b><\/td>\n<\/tr>\n<tr>\n<td><span style=\"font-weight: 400;\">Authentication<\/span><\/td>\n<td><span style=\"font-weight: 400;\">Basic (API Key)<\/span><\/td>\n<td><span style=\"font-weight: 400;\">OAuth 2.0<\/span><\/td>\n<\/tr>\n<tr>\n<td><span style=\"font-weight: 400;\">Rate Limit<\/span><\/td>\n<td><span style=\"font-weight: 400;\">20,000\/hour<\/span><\/td>\n<td><span style=\"font-weight: 400;\">450 per 30 seconds<\/span><\/td>\n<\/tr>\n<tr>\n<td><span style=\"font-weight: 400;\">Request Format<\/span><\/td>\n<td><span style=\"font-weight: 400;\">REST only<\/span><\/td>\n<td><span style=\"font-weight: 400;\">REST + GraphQL<\/span><\/td>\n<\/tr>\n<tr>\n<td><span style=\"font-weight: 400;\">Custom Fields<\/span><\/td>\n<td><span style=\"font-weight: 400;\">\/products\/{id}\/custom_fields<\/span><\/td>\n<td><span style=\"font-weight: 400;\">\/catalog\/products\/{id}\/custom-fields<\/span><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<p><span style=\"font-weight: 400;\">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.<\/span><\/p>\n<p><span style=\"font-weight: 400;\">Now let&#8217;s explore how to properly authenticate your API requests.<\/span><\/p>\n<h2><span style=\"font-weight: 400;\">Setting Up BigCommerce API Authentication<\/span><\/h2>\n<p><span style=\"font-weight: 400;\">Proper authentication ensures secure access to your store&#8217;s product data while preventing unauthorized modifications. The process differs significantly between API v2 and v3.<\/span><\/p>\n<h3><span style=\"font-weight: 400;\">Generating API Credentials<\/span><\/h3>\n<p><span style=\"font-weight: 400;\">Navigate to your BigCommerce control panel and access Advanced Settings &gt; API Accounts. Click &#8220;Create API Account&#8221; and select &#8220;V2\/V3 API Token&#8221; to generate credentials for both versions simultaneously.<\/span><\/p>\n<p><span style=\"font-weight: 400;\">You&#8217;ll need to configure OAuth scopes during credential generation. For product management, enable the following minimum scopes:<\/span><\/p>\n<ul>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Products: read-only or modify<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Content: read-only (for linked resources)<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Information &amp; Settings: read-only<\/span><\/li>\n<\/ul>\n<p><span style=\"font-weight: 400;\">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.<\/span><\/p>\n<h3><span style=\"font-weight: 400;\">Implementing OAuth Authentication for BigCommerce Product API v3<\/span><\/h3>\n<p><span style=\"font-weight: 400;\">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:<\/span><\/p>\n<p><span style=\"font-weight: 400;\">X-Auth-Token: your_access_token_here<\/span><\/p>\n<p><span style=\"font-weight: 400;\">Content-Type: application\/json<\/span><\/p>\n<p><span style=\"font-weight: 400;\">Accept: application\/json<\/span><\/p>\n<p><span style=\"font-weight: 400;\">Unlike traditional OAuth flows, BigCommerce uses a simplified approach where you receive permanent access tokens during credential generation. These tokens don&#8217;t expire unless you regenerate or delete the API account. This design eliminates the complexity of token refresh mechanisms common in other OAuth implementations.<\/span><\/p>\n<p><span style=\"font-weight: 400;\">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.<\/span><\/p>\n<h3><span style=\"font-weight: 400;\">Rate Limiting Considerations<\/span><\/h3>\n<p><span style=\"font-weight: 400;\">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.<\/span><\/p>\n<p><span style=\"font-weight: 400;\">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.<\/span><\/p>\n<table>\n<tbody>\n<tr>\n<td><b>Store Plan<\/b><\/td>\n<td><b>Requests Per 30 Seconds<\/b><\/td>\n<td><b>Burst Allowance<\/b><\/td>\n<\/tr>\n<tr>\n<td><span style=\"font-weight: 400;\">Standard<\/span><\/td>\n<td><span style=\"font-weight: 400;\">450<\/span><\/td>\n<td><span style=\"font-weight: 400;\">150<\/span><\/td>\n<\/tr>\n<tr>\n<td><span style=\"font-weight: 400;\">Plus<\/span><\/td>\n<td><span style=\"font-weight: 400;\">600<\/span><\/td>\n<td><span style=\"font-weight: 400;\">200<\/span><\/td>\n<\/tr>\n<tr>\n<td><span style=\"font-weight: 400;\">Enterprise<\/span><\/td>\n<td><span style=\"font-weight: 400;\">1,000+<\/span><\/td>\n<td><span style=\"font-weight: 400;\">300+<\/span><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<p><span style=\"font-weight: 400;\">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.<\/span><\/p>\n<p><span style=\"font-weight: 400;\">With authentication configured, you&#8217;re ready to create your first product.<\/span><\/p>\n<h2><span style=\"font-weight: 400;\">Creating Products With the BigCommerce Product API<\/span><\/h2>\n<p><span style=\"font-weight: 400;\">Product creation forms the foundation of catalog management through the API. Understanding required fields, optional attributes, and data validation ensures successful product additions.<\/span><\/p>\n<h3><span style=\"font-weight: 400;\">Required Product Attributes<\/span><\/h3>\n<p><span style=\"font-weight: 400;\">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 &#8220;physical&#8221; for shippable items or &#8220;digital&#8221; for downloadable content.<\/span><\/p>\n<p><span style=\"font-weight: 400;\">Price values should be submitted as decimal strings (e.g., &#8220;29.99&#8221;) rather than floats to prevent rounding errors. The weight field requires a numeric value based on your store&#8217;s default weight unit, typically pounds or kilograms.<\/span><\/p>\n<h3><span style=\"font-weight: 400;\">Building a Product Creation Request<\/span><\/h3>\n<p><span style=\"font-weight: 400;\">The <\/span><span style=\"font-weight: 400;\">\/v3\/catalog\/products<\/span><span style=\"font-weight: 400;\"> endpoint accepts POST requests with a JSON payload containing product attributes. Here&#8217;s a minimal viable product:<\/span><\/p>\n<p><span style=\"font-weight: 400;\">json<\/span><\/p>\n<p><span style=\"font-weight: 400;\">{<\/span><\/p>\n<p><span style=\"font-weight: 400;\">\u00a0\u00a0<\/span><span style=\"font-weight: 400;\">&#8220;name&#8221;<\/span><span style=\"font-weight: 400;\">:<\/span> <span style=\"font-weight: 400;\">&#8220;Premium Wireless Headphones&#8221;<\/span><span style=\"font-weight: 400;\">,<\/span><\/p>\n<p><span style=\"font-weight: 400;\">\u00a0\u00a0<\/span><span style=\"font-weight: 400;\">&#8220;type&#8221;<\/span><span style=\"font-weight: 400;\">:<\/span> <span style=\"font-weight: 400;\">&#8220;physical&#8221;<\/span><span style=\"font-weight: 400;\">,<\/span><\/p>\n<p><span style=\"font-weight: 400;\">\u00a0\u00a0<\/span><span style=\"font-weight: 400;\">&#8220;sku&#8221;<\/span><span style=\"font-weight: 400;\">:<\/span> <span style=\"font-weight: 400;\">&#8220;WH-2024-001&#8221;<\/span><span style=\"font-weight: 400;\">,<\/span><\/p>\n<p><span style=\"font-weight: 400;\">\u00a0\u00a0<\/span><span style=\"font-weight: 400;\">&#8220;price&#8221;<\/span><span style=\"font-weight: 400;\">:<\/span> <span style=\"font-weight: 400;\">&#8220;149.99&#8221;<\/span><span style=\"font-weight: 400;\">,<\/span><\/p>\n<p><span style=\"font-weight: 400;\">\u00a0\u00a0<\/span><span style=\"font-weight: 400;\">&#8220;weight&#8221;<\/span><span style=\"font-weight: 400;\">:<\/span> <span style=\"font-weight: 400;\">0.75<\/span><span style=\"font-weight: 400;\">,<\/span><\/p>\n<p><span style=\"font-weight: 400;\">\u00a0\u00a0<\/span><span style=\"font-weight: 400;\">&#8220;categories&#8221;<\/span><span style=\"font-weight: 400;\">:<\/span><span style=\"font-weight: 400;\"> [<\/span><span style=\"font-weight: 400;\">23<\/span><span style=\"font-weight: 400;\">],<\/span><\/p>\n<p><span style=\"font-weight: 400;\">\u00a0\u00a0<\/span><span style=\"font-weight: 400;\">&#8220;description&#8221;<\/span><span style=\"font-weight: 400;\">:<\/span> <span style=\"font-weight: 400;\">&#8220;High-fidelity audio with 30-hour battery life&#8221;<\/span><span style=\"font-weight: 400;\">,<\/span><\/p>\n<p><span style=\"font-weight: 400;\">\u00a0\u00a0<\/span><span style=\"font-weight: 400;\">&#8220;inventory_level&#8221;<\/span><span style=\"font-weight: 400;\">:<\/span> <span style=\"font-weight: 400;\">50<\/span><span style=\"font-weight: 400;\">,<\/span><\/p>\n<p><span style=\"font-weight: 400;\">\u00a0\u00a0<\/span><span style=\"font-weight: 400;\">&#8220;inventory_tracking&#8221;<\/span><span style=\"font-weight: 400;\">:<\/span> <span style=\"font-weight: 400;\">&#8220;product&#8221;<\/span><\/p>\n<p><span style=\"font-weight: 400;\">}<\/span><\/p>\n<p><span style=\"font-weight: 400;\">This example creates a physical product with inventory tracking enabled. The categories array accepts category IDs from your store&#8217;s existing category tree. Omitting this field creates an uncategorized product.<\/span><\/p>\n<h3><span style=\"font-weight: 400;\">Advanced Product Attributes<\/span><\/h3>\n<p><span style=\"font-weight: 400;\">Beyond the basics, the BigCommerce product API supports numerous optional fields for comprehensive product definitions:<\/span><\/p>\n<h4><span style=\"font-weight: 400;\">Pricing Fields:<\/span><\/h4>\n<ul>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">cost_price: Your wholesale cost for margin calculations<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">retail_price: Original MSRP for displaying savings<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">sale_price: Discounted price that overrides the base price<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">map_price: Minimum advertised price for compliance<\/span><\/li>\n<\/ul>\n<h4><span style=\"font-weight: 400;\">SEO Optimization:<\/span><\/h4>\n<ul>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">page_title: Custom HTML title tag (70 characters maximum)<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">meta_description: Search result snippet text (160 characters maximum)<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">meta_keywords: Legacy SEO field, minimal impact<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">search_keywords: Internal site search terms<\/span><\/li>\n<\/ul>\n<h4><span style=\"font-weight: 400;\">Visibility Controls:<\/span><\/h4>\n<ul>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">is_visible: Boolean controlling storefront display<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">is_featured: Flags product for homepage\/special sections<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">availability: Values include &#8220;available&#8221;, &#8220;preorder&#8221;, or &#8220;disabled&#8221;<\/span><\/li>\n<\/ul>\n<h3><span style=\"font-weight: 400;\">Product Creation Response Handling<\/span><\/h3>\n<p><span style=\"font-weight: 400;\">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.<\/span><\/p>\n<p><span style=\"font-weight: 400;\">json<\/span><\/p>\n<p><span style=\"font-weight: 400;\">{<\/span><\/p>\n<p><span style=\"font-weight: 400;\">\u00a0\u00a0<\/span><span style=\"font-weight: 400;\">&#8220;data&#8221;<\/span><span style=\"font-weight: 400;\">:<\/span><span style=\"font-weight: 400;\"> {<\/span><\/p>\n<p><span style=\"font-weight: 400;\">\u00a0\u00a0\u00a0\u00a0<\/span><span style=\"font-weight: 400;\">&#8220;id&#8221;<\/span><span style=\"font-weight: 400;\">:<\/span> <span style=\"font-weight: 400;\">234<\/span><span style=\"font-weight: 400;\">,<\/span><\/p>\n<p><span style=\"font-weight: 400;\">\u00a0\u00a0\u00a0\u00a0<\/span><span style=\"font-weight: 400;\">&#8220;name&#8221;<\/span><span style=\"font-weight: 400;\">:<\/span> <span style=\"font-weight: 400;\">&#8220;Premium Wireless Headphones&#8221;<\/span><span style=\"font-weight: 400;\">,<\/span><\/p>\n<p><span style=\"font-weight: 400;\">\u00a0\u00a0\u00a0\u00a0<\/span><span style=\"font-weight: 400;\">&#8220;sku&#8221;<\/span><span style=\"font-weight: 400;\">:<\/span> <span style=\"font-weight: 400;\">&#8220;WH-2024-001&#8221;<\/span><span style=\"font-weight: 400;\">,<\/span><\/p>\n<p><span style=\"font-weight: 400;\">\u00a0\u00a0\u00a0\u00a0<\/span><span style=\"font-weight: 400;\">&#8220;calculated_price&#8221;<\/span><span style=\"font-weight: 400;\">:<\/span> <span style=\"font-weight: 400;\">149.99<\/span><span style=\"font-weight: 400;\">,<\/span><\/p>\n<p><span style=\"font-weight: 400;\">\u00a0\u00a0\u00a0\u00a0<\/span><span style=\"font-weight: 400;\">&#8220;date_created&#8221;<\/span><span style=\"font-weight: 400;\">:<\/span> <span style=\"font-weight: 400;\">&#8220;2026-01-19T10:30:00Z&#8221;<\/span><span style=\"font-weight: 400;\">,<\/span><\/p>\n<p><span style=\"font-weight: 400;\">\u00a0\u00a0\u00a0\u00a0<\/span><span style=\"font-weight: 400;\">&#8220;base_variant_id&#8221;<\/span><span style=\"font-weight: 400;\">:<\/span> <span style=\"font-weight: 400;\">512<\/span><\/p>\n<p><span style=\"font-weight: 400;\">\u00a0\u00a0}<\/span><\/p>\n<p><span style=\"font-weight: 400;\">}<\/span><\/p>\n<p><span style=\"font-weight: 400;\">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.<\/span><\/p>\n<p><span style=\"font-weight: 400;\">Now let&#8217;s examine how to modify existing products.<\/span><\/p>\n<h2><span style=\"font-weight: 400;\">Updating Product Data<\/span><\/h2>\n<p><span style=\"font-weight: 400;\">Updating products through the BigCommerce product API allows you to modify attributes, adjust pricing, and maintain accurate inventory without manual control panel access.<\/span><\/p>\n<h3><span style=\"font-weight: 400;\">Partial vs. Complete Updates<\/span><\/h3>\n<p><span style=\"font-weight: 400;\">The BigCommerce API product v3 supports partial updates using PUT requests to <\/span><span style=\"font-weight: 400;\">\/v3\/catalog\/products\/{product_id}<\/span><span style=\"font-weight: 400;\">. You only need to include fields you want to modify\u2014unchanged attributes remain intact.<\/span><\/p>\n<p><span style=\"font-weight: 400;\">For example, updating only the price and inventory:<\/span><\/p>\n<p><span style=\"font-weight: 400;\">json<\/span><\/p>\n<p><span style=\"font-weight: 400;\">{<\/span><\/p>\n<p><span style=\"font-weight: 400;\">\u00a0\u00a0<\/span><span style=\"font-weight: 400;\">&#8220;price&#8221;<\/span><span style=\"font-weight: 400;\">:<\/span> <span style=\"font-weight: 400;\">&#8220;139.99&#8221;<\/span><span style=\"font-weight: 400;\">,<\/span><\/p>\n<p><span style=\"font-weight: 400;\">\u00a0\u00a0<\/span><span style=\"font-weight: 400;\">&#8220;inventory_level&#8221;<\/span><span style=\"font-weight: 400;\">:<\/span> <span style=\"font-weight: 400;\">35<\/span><\/p>\n<p><span style=\"font-weight: 400;\">}<\/span><\/p>\n<p><span style=\"font-weight: 400;\">This approach minimizes request payload sizes and reduces the risk of accidentally modifying fields. Complete product replacements are rarely necessary unless performing major restructuring.<\/span><\/p>\n<h3><span style=\"font-weight: 400;\">Batch Product Updates<\/span><\/h3>\n<p><span style=\"font-weight: 400;\">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:<\/span><\/p>\n<p><span style=\"font-weight: 400;\">PUT \/v3\/catalog\/products<\/span><\/p>\n<p><span style=\"font-weight: 400;\">The payload accepts an array of product objects, each requiring an ID field to identify which product to update. BigCommerce processes these atomically\u2014all updates succeed or all fail together.<\/span><\/p>\n<h3><span style=\"font-weight: 400;\">Handling Update Conflicts<\/span><\/h3>\n<p><span style=\"font-weight: 400;\">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.<\/span><\/p>\n<p><span style=\"font-weight: 400;\">This pattern prevents accidentally overwriting changes from other integrations or admin panel updates. Implement a refresh-and-retry mechanism when conflicts are detected.<\/span><\/p>\n<h3><span style=\"font-weight: 400;\">Inventory Management<\/span><\/h3>\n<p><span style=\"font-weight: 400;\">Inventory updates deserve special attention due to their business impact. The BigCommerce product API provides two fields for stock management:<\/span><\/p>\n<ul>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><b>inventory_level<\/b><span style=\"font-weight: 400;\">: Current stock quantity for the product<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><b>inventory_warning_level<\/b><span style=\"font-weight: 400;\">: Threshold triggering low-stock notifications<\/span><\/li>\n<\/ul>\n<p><span style=\"font-weight: 400;\">Set inventory_tracking to &#8220;product&#8221; to enable stock decrements during checkout. Use &#8220;none&#8221; for services or made-to-order items where stock doesn&#8217;t apply. Never use &#8220;variant&#8221; when products lack options\u2014this causes API errors.<\/span><\/p>\n<table>\n<tbody>\n<tr>\n<td><b>Inventory Tracking Mode<\/b><\/td>\n<td><b>Use Case<\/b><\/td>\n<td><b>Stock Decrements<\/b><\/td>\n<\/tr>\n<tr>\n<td><span style=\"font-weight: 400;\">product<\/span><\/td>\n<td><span style=\"font-weight: 400;\">Simple products<\/span><\/td>\n<td><span style=\"font-weight: 400;\">Yes<\/span><\/td>\n<\/tr>\n<tr>\n<td><span style=\"font-weight: 400;\">variant<\/span><\/td>\n<td><span style=\"font-weight: 400;\">Products with options<\/span><\/td>\n<td><span style=\"font-weight: 400;\">Per variant<\/span><\/td>\n<\/tr>\n<tr>\n<td><span style=\"font-weight: 400;\">none<\/span><\/td>\n<td><span style=\"font-weight: 400;\">Digital\/services<\/span><\/td>\n<td><span style=\"font-weight: 400;\">No<\/span><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<p><span style=\"font-weight: 400;\">With updates covered, let&#8217;s explore product deletion and archival strategies.<\/span><\/p>\n<h2><span style=\"font-weight: 400;\">Managing Product Lifecycle<\/span><\/h2>\n<p><span style=\"font-weight: 400;\">Beyond creation and updates, effective product management includes deletion, archival, and bulk operations for efficient catalog maintenance.<\/span><\/p>\n<h3><span style=\"font-weight: 400;\">Soft Deletion vs. Hard Deletion<\/span><\/h3>\n<p><span style=\"font-weight: 400;\">The BigCommerce product API treats deletion as permanent removal. Unlike some platforms, there&#8217;s no built-in trash or recovery mechanism. Before deleting products, consider setting is_visible to false as a soft-delete alternative.<\/span><\/p>\n<p><span style=\"font-weight: 400;\">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.<\/span><\/p>\n<h3><span style=\"font-weight: 400;\">Bulk Deletion Operations<\/span><\/h3>\n<p><span style=\"font-weight: 400;\">To delete multiple products efficiently, send DELETE requests to <\/span><span style=\"font-weight: 400;\">\/v3\/catalog\/products<\/span><span style=\"font-weight: 400;\"> with a query parameter array:<\/span><\/p>\n<p><span style=\"font-weight: 400;\">DELETE \/v3\/catalog\/products?id:in=234,235,236<\/span><\/p>\n<p><span style=\"font-weight: 400;\">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.<\/span><\/p>\n<h3><span style=\"font-weight: 400;\">Product Variant Deletion<\/span><\/h3>\n<p><span style=\"font-weight: 400;\">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.<\/span><\/p>\n<p><span style=\"font-weight: 400;\">To remove individual variants without affecting the parent product, use the variant-specific endpoint:<\/span><\/p>\n<p><span style=\"font-weight: 400;\">DELETE \/v3\/catalog\/products\/{product_id}\/variants\/{variant_id}<\/span><\/p>\n<p><span style=\"font-weight: 400;\">Now that we&#8217;ve covered basic product operations, let&#8217;s explore how custom fields extend product data.<\/span><\/p>\n<h2><span style=\"font-weight: 400;\">Define Custom Product Fields BigCommerce API<\/span><\/h2>\n<p><span style=\"font-weight: 400;\">Custom fields allow you to store additional product information beyond BigCommerce&#8217;s standard attributes. These fields power everything from specification tables to integration metadata.<\/span><\/p>\n<h3><span style=\"font-weight: 400;\">What Are BigCommerce Custom Fields?<\/span><\/h3>\n<p><span style=\"font-weight: 400;\">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.<\/span><\/p>\n<p><span style=\"font-weight: 400;\">Common use cases include:<\/span><\/p>\n<ul>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Product specifications (dimensions, materials, certifications)<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Integration identifiers (ERP SKUs, warehouse codes)<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Display flags (badges, special handling indicators)<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">External references (manufacturer part numbers, UPC codes)<\/span><\/li>\n<\/ul>\n<h3><span style=\"font-weight: 400;\">Creating Custom Fields<\/span><\/h3>\n<p><span style=\"font-weight: 400;\">To define <a href=\"https:\/\/ecommerce.folio3.com\/blog\/b2b-ecommerce-for-eco-friendly-products-using-bigcommerce-custom-development\/\">custom product fields BigCommerce<\/a> API operations use the endpoint <\/span><span style=\"font-weight: 400;\">\/v3\/catalog\/products\/{product_id}\/custom-fields<\/span><span style=\"font-weight: 400;\"> with a POST request:<\/span><\/p>\n<p><span style=\"font-weight: 400;\">json<\/span><\/p>\n<p><span style=\"font-weight: 400;\">{<\/span><\/p>\n<p><span style=\"font-weight: 400;\">\u00a0\u00a0<\/span><span style=\"font-weight: 400;\">&#8220;name&#8221;<\/span><span style=\"font-weight: 400;\">:<\/span> <span style=\"font-weight: 400;\">&#8220;Warranty Period&#8221;<\/span><span style=\"font-weight: 400;\">,<\/span><\/p>\n<p><span style=\"font-weight: 400;\">\u00a0\u00a0<\/span><span style=\"font-weight: 400;\">&#8220;value&#8221;<\/span><span style=\"font-weight: 400;\">:<\/span> <span style=\"font-weight: 400;\">&#8220;2 Years Limited&#8221;<\/span><\/p>\n<p><span style=\"font-weight: 400;\">}<\/span><\/p>\n<p><span style=\"font-weight: 400;\">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.<\/span><\/p>\n<h3><span style=\"font-weight: 400;\">Retrieving Custom Field Data<\/span><\/h3>\n<p><span style=\"font-weight: 400;\">Fetch all custom fields for a product using GET requests:<\/span><\/p>\n<p><span style=\"font-weight: 400;\">GET \/v3\/catalog\/products\/{product_id}\/custom-fields<\/span><\/p>\n<p><span style=\"font-weight: 400;\">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.<\/span><\/p>\n<p><span style=\"font-weight: 400;\">Response pagination applies when products have many custom fields. The default page size returns 50 fields; adjust using the <\/span><span style=\"font-weight: 400;\">limit<\/span><span style=\"font-weight: 400;\"> parameter up to 250.<\/span><\/p>\n<h3><span style=\"font-weight: 400;\">Updating Custom Fields<\/span><\/h3>\n<p><span style=\"font-weight: 400;\">Modify existing custom fields with PUT requests to the field-specific endpoint:<\/span><\/p>\n<p><span style=\"font-weight: 400;\">PUT \/v3\/catalog\/products\/{product_id}\/custom-fields\/{custom_field_id}<\/span><\/p>\n<p><span style=\"font-weight: 400;\">You can update either the name, value, or both fields in a single request:<\/span><\/p>\n<p><span style=\"font-weight: 400;\">json<\/span><\/p>\n<p><span style=\"font-weight: 400;\">{<\/span><\/p>\n<p><span style=\"font-weight: 400;\">\u00a0\u00a0<\/span><span style=\"font-weight: 400;\">&#8220;name&#8221;<\/span><span style=\"font-weight: 400;\">:<\/span> <span style=\"font-weight: 400;\">&#8220;Warranty Period&#8221;<\/span><span style=\"font-weight: 400;\">,<\/span><\/p>\n<p><span style=\"font-weight: 400;\">\u00a0\u00a0<\/span><span style=\"font-weight: 400;\">&#8220;value&#8221;<\/span><span style=\"font-weight: 400;\">:<\/span> <span style=\"font-weight: 400;\">&#8220;3 Years Extended&#8221;<\/span><\/p>\n<p><span style=\"font-weight: 400;\">}<\/span><\/p>\n<p><span style=\"font-weight: 400;\">Remember that name-value pairs must remain unique after updates. Changing a name to match an existing field causes validation failures.<\/span><\/p>\n<h3><span style=\"font-weight: 400;\">Custom Fields vs. Metafields<\/span><\/h3>\n<p><span style=\"font-weight: 400;\">While custom fields excel at simple data storage, BigCommerce also offers metafields for more complex scenarios. The key differences:<\/span><\/p>\n<table>\n<tbody>\n<tr>\n<td><b>Feature<\/b><\/td>\n<td><b>Custom Fields<\/b><\/td>\n<td><b>Metafields<\/b><\/td>\n<\/tr>\n<tr>\n<td><span style=\"font-weight: 400;\">Character Limit<\/span><\/td>\n<td><span style=\"font-weight: 400;\">250<\/span><\/td>\n<td><span style=\"font-weight: 400;\">65,535<\/span><\/td>\n<\/tr>\n<tr>\n<td><span style=\"font-weight: 400;\">Admin UI Access<\/span><\/td>\n<td><span style=\"font-weight: 400;\">Yes<\/span><\/td>\n<td><span style=\"font-weight: 400;\">No (API only)<\/span><\/td>\n<\/tr>\n<tr>\n<td><span style=\"font-weight: 400;\">Namespace Support<\/span><\/td>\n<td><span style=\"font-weight: 400;\">No<\/span><\/td>\n<td><span style=\"font-weight: 400;\">Yes<\/span><\/td>\n<\/tr>\n<tr>\n<td><span style=\"font-weight: 400;\">Rich Content<\/span><\/td>\n<td><span style=\"font-weight: 400;\">Limited<\/span><\/td>\n<td><span style=\"font-weight: 400;\">Full HTML<\/span><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<p><span style=\"font-weight: 400;\">Choose custom fields when:<\/span><\/p>\n<ul>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Data length stays under 250 characters<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Non-technical staff need admin panel access<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Simple key-value storage suffices<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Enterprise plan filtering features are required<\/span><\/li>\n<\/ul>\n<p><span style=\"font-weight: 400;\">Select metafields when:<\/span><\/p>\n<ul>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Storing extensive descriptions or specifications<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Managing multi-language content variants<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Implementing complex data structures<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">SEO content blocks are needed<\/span><\/li>\n<\/ul>\n<p><span style=\"font-weight: 400;\">Now let&#8217;s examine practical implementation patterns.<\/span><\/p>\n<h2><span style=\"font-weight: 400;\">Working With Product Variants and Options<\/span><\/h2>\n<p><span style=\"font-weight: 400;\">Products with multiple configurations require variant and option management through the BigCommerce product API. Understanding these relationships is critical for complex catalog structures.<\/span><\/p>\n<h3><span style=\"font-weight: 400;\">Option Sets and Product Options<\/span><\/h3>\n<p><span style=\"font-weight: 400;\">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&#8217;ll typically reference existing option sets rather than creating them per product.<\/span><\/p>\n<p><span style=\"font-weight: 400;\">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 &#8220;Size&#8221; option might include Small, Medium, Large values).<\/span><\/p>\n<h3><span style=\"font-weight: 400;\">Creating Product Variants<\/span><\/h3>\n<p><span style=\"font-weight: 400;\">Variants represent specific combinations of option values. A t-shirt with three sizes and four colors generates 12 variants (3 \u00d7 4). The API automatically creates these combinations when you define options, or you can create them individually for precise control.<\/span><\/p>\n<p><span style=\"font-weight: 400;\">Each variant maintains its own:<\/span><\/p>\n<ul>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">SKU identifier<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Price adjustments (positive or negative)<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Inventory levels<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Weight specifications<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Image associations<\/span><\/li>\n<\/ul>\n<h3><span style=\"font-weight: 400;\">Variant-Level Inventory Management<\/span><\/h3>\n<p><span style=\"font-weight: 400;\">When products use variant-level inventory tracking, set inventory_tracking to &#8220;variant&#8221; on the parent product. Each variant then maintains independent stock counts, allowing precise inventory control for specific configurations.<\/span><\/p>\n<p><span style=\"font-weight: 400;\">This approach is essential for products where certain combinations (e.g., Red\/Large) might stock out while others remain available.<\/span><\/p>\n<p><span style=\"font-weight: 400;\">Let&#8217;s now explore error handling and troubleshooting strategies.<\/span><\/p>\n<h2><span style=\"font-weight: 400;\">Error Handling and Troubleshooting<\/span><\/h2>\n<p><span style=\"font-weight: 400;\">Robust error handling separates production-ready integrations from fragile implementations. The BigCommerce product API uses standard HTTP status codes with detailed error messages.<\/span><\/p>\n<h3><span style=\"font-weight: 400;\">Common API Errors<\/span><\/h3>\n<p><b>422 Unprocessable Entity<\/b><span style=\"font-weight: 400;\"> occurs when request data fails validation rules. The response includes specific field errors:<\/span><\/p>\n<p><span style=\"font-weight: 400;\">json<\/span><\/p>\n<p><span style=\"font-weight: 400;\">{<\/span><\/p>\n<p><span style=\"font-weight: 400;\">\u00a0\u00a0<\/span><span style=\"font-weight: 400;\">&#8220;status&#8221;<\/span><span style=\"font-weight: 400;\">:<\/span> <span style=\"font-weight: 400;\">422<\/span><span style=\"font-weight: 400;\">,<\/span><\/p>\n<p><span style=\"font-weight: 400;\">\u00a0\u00a0<\/span><span style=\"font-weight: 400;\">&#8220;title&#8221;<\/span><span style=\"font-weight: 400;\">:<\/span> <span style=\"font-weight: 400;\">&#8220;The product was not valid&#8221;<\/span><span style=\"font-weight: 400;\">,<\/span><\/p>\n<p><span style=\"font-weight: 400;\">\u00a0\u00a0<\/span><span style=\"font-weight: 400;\">&#8220;errors&#8221;<\/span><span style=\"font-weight: 400;\">:<\/span><span style=\"font-weight: 400;\"> {<\/span><\/p>\n<p><span style=\"font-weight: 400;\">\u00a0\u00a0\u00a0\u00a0<\/span><span style=\"font-weight: 400;\">&#8220;price&#8221;<\/span><span style=\"font-weight: 400;\">:<\/span> <span style=\"font-weight: 400;\">&#8220;Price must be greater than 0&#8221;<\/span><\/p>\n<p><span style=\"font-weight: 400;\">\u00a0\u00a0}<\/span><\/p>\n<p><span style=\"font-weight: 400;\">}<\/span><\/p>\n<p><span style=\"font-weight: 400;\">Address each error in the errors object before retrying the request.<\/span><\/p>\n<p><b>404 Not Found<\/b><span style=\"font-weight: 400;\"> indicates the requested product ID doesn&#8217;t exist. Verify IDs before operations and implement existence checks for critical workflows.<\/span><\/p>\n<p><b>409 Conflict<\/b><span style=\"font-weight: 400;\"> signals constraint violations, typically unique field duplicates like SKUs. Ensure SKU uniqueness across your catalog or leave the field empty for auto-generation.<\/span><\/p>\n<h3><span style=\"font-weight: 400;\">Validation Best Practices<\/span><\/h3>\n<p><span style=\"font-weight: 400;\">Implement client-side validation before sending API requests:<\/span><\/p>\n<ol>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Verify required fields are present and non-empty<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Check string lengths against maximum values<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Validate numeric ranges for price and weight<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Ensure array fields contain valid IDs<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Confirm boolean fields use proper true\/false values<\/span><\/li>\n<\/ol>\n<p><span style=\"font-weight: 400;\">This proactive approach reduces unnecessary API calls and improves response times.<\/span><\/p>\n<h3><span style=\"font-weight: 400;\">Request Timeout Handling<\/span><\/h3>\n<p><span style=\"font-weight: 400;\">Network issues or high server load can cause request timeouts. Implement retry logic with exponential backoff:<\/span><\/p>\n<p><span style=\"font-weight: 400;\">Attempt 1: Immediate<\/span><\/p>\n<p><span style=\"font-weight: 400;\">Attempt 2: Wait 2 seconds<\/span><\/p>\n<p><span style=\"font-weight: 400;\">Attempt 3: Wait 4 seconds<\/span><\/p>\n<p><span style=\"font-weight: 400;\">Attempt 4: Wait 8 seconds<\/span><\/p>\n<p><span style=\"font-weight: 400;\">Set a maximum retry count (typically 3-5) to prevent infinite loops. Log failures that exceed retry limits for manual investigation.<\/span><\/p>\n<h3><span style=\"font-weight: 400;\">Logging and Monitoring<\/span><\/h3>\n<p><span style=\"font-weight: 400;\">Comprehensive logging helps diagnose integration issues. Capture:<\/span><\/p>\n<ul>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Request timestamps and endpoints<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Complete request payloads (excluding sensitive data)<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Response status codes and bodies<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Error messages and stack traces<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Correlation IDs for tracking request chains<\/span><\/li>\n<\/ul>\n<p><span style=\"font-weight: 400;\">Use structured logging formats (JSON) for easier analysis and alerting. Monitor error rates to detect degraded API performance or systematic integration problems.<\/span><\/p>\n<p><span style=\"font-weight: 400;\">With error handling covered, let&#8217;s examine performance optimization techniques.<\/span><\/p>\n<h2><span style=\"font-weight: 400;\">Optimizing API Performance<\/span><\/h2>\n<p><span style=\"font-weight: 400;\">Efficient API usage improves integration speed, reduces costs, and provides better user experiences. Several <a href=\"https:\/\/ecommerce.folio3.com\/blog\/sales-strategies-for-maximizing-bigcommerce-store-revenue\/\">strategies help maximize BigCommerce<\/a> product API performance.<\/span><\/p>\n<h3><span style=\"font-weight: 400;\">Request Batching<\/span><\/h3>\n<p><span style=\"font-weight: 400;\">Instead of individual product operations, batch related requests together. The <a href=\"https:\/\/ecommerce.folio3.com\/blog\/using-bigcommerce-storefront-apis-to-create-custom-product-display-page-experiences\/\">BigCommerce API product<\/a> v3 supports batch endpoints for creating and updating multiple products:<\/span><\/p>\n<p><span style=\"font-weight: 400;\">POST \/v3\/catalog\/products<\/span><\/p>\n<p><span style=\"font-weight: 400;\">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%.<\/span><\/p>\n<h3><span style=\"font-weight: 400;\">Field Filtering<\/span><\/h3>\n<p><span style=\"font-weight: 400;\">The BigCommerce product API allows you to request only needed fields using the <\/span><span style=\"font-weight: 400;\">include_fields<\/span><span style=\"font-weight: 400;\"> parameter:<\/span><\/p>\n<p><span style=\"font-weight: 400;\">GET \/v3\/catalog\/products\/234?include_fields=id,name,price,inventory_level<\/span><\/p>\n<p><span style=\"font-weight: 400;\">This reduces response payload sizes, accelerating data transfer and JSON parsing. Particularly valuable when fetching product lists where you only need specific attributes.<\/span><\/p>\n<h3><span style=\"font-weight: 400;\">Pagination Strategies<\/span><\/h3>\n<p><span style=\"font-weight: 400;\">When retrieving product catalogs, implement cursor-based pagination instead of offset-based approaches. Cursor pagination handles large datasets more efficiently and avoids the &#8220;page shift&#8221; problem when products are added during multi-page retrievals.<\/span><\/p>\n<table>\n<tbody>\n<tr>\n<td><b>Pagination Type<\/b><\/td>\n<td><b>Performance<\/b><\/td>\n<td><b>Consistency<\/b><\/td>\n<td><b>Best For<\/b><\/td>\n<\/tr>\n<tr>\n<td><span style=\"font-weight: 400;\">Offset<\/span><\/td>\n<td><span style=\"font-weight: 400;\">Degrades with size<\/span><\/td>\n<td><span style=\"font-weight: 400;\">Poor (page shift)<\/span><\/td>\n<td><span style=\"font-weight: 400;\">Small catalogs<\/span><\/td>\n<\/tr>\n<tr>\n<td><span style=\"font-weight: 400;\">Cursor<\/span><\/td>\n<td><span style=\"font-weight: 400;\">Constant<\/span><\/td>\n<td><span style=\"font-weight: 400;\">Excellent<\/span><\/td>\n<td><span style=\"font-weight: 400;\">Large catalogs<\/span><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h3><span style=\"font-weight: 400;\">Caching Strategies<\/span><\/h3>\n<p><span style=\"font-weight: 400;\">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:<\/span><\/p>\n<ul>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Static products: 24-hour cache<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Regular updates: 1-hour cache<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Real-time inventory: 5-minute cache<\/span><\/li>\n<\/ul>\n<p><span style=\"font-weight: 400;\">Include cache-control headers in your requests and respect ETags returned by the API for conditional requests.<\/span><\/p>\n<h3><span style=\"font-weight: 400;\">Webhook Integration<\/span><\/h3>\n<p><span style=\"font-weight: 400;\">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.<\/span><\/p>\n<p><span style=\"font-weight: 400;\">Configure webhooks through the <a href=\"https:\/\/ecommerce.folio3.com\/blog\/bigcommerce-api-documentation\/\">BigCommerce API integration<\/a> setup<\/span><span style=\"font-weight: 400;\"> to receive product change notifications directly in your application.<\/span><\/p>\n<p><span style=\"font-weight: 400;\">Now let&#8217;s explore practical implementation examples.<\/span><\/p>\n<h2><span style=\"font-weight: 400;\">Practical Implementation Examples<\/span><\/h2>\n<p><span style=\"font-weight: 400;\">Real-world scenarios demonstrate how to combine BigCommerce product API capabilities into functional integrations.<\/span><\/p>\n<h3><span style=\"font-weight: 400;\">Example 1: Product Import From CSV<\/span><\/h3>\n<p><span style=\"font-weight: 400;\">Many businesses need to import products from spreadsheets or legacy systems. Here&#8217;s a pattern for CSV-to-API conversion:<\/span><\/p>\n<ol>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Parse CSV file and validate required fields<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Map CSV columns to BigCommerce product attributes<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Batch products into groups of 10<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Submit each batch with error handling<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Log successful imports and failures<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Generate summary report with product IDs<\/span><\/li>\n<\/ol>\n<p><span style=\"font-weight: 400;\">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.<\/span><\/p>\n<h3><span style=\"font-weight: 400;\">Example 2: Price Synchronization<\/span><\/h3>\n<p><span style=\"font-weight: 400;\">E-commerce operations often require automated pricing updates from ERP or pricing management systems. Effective synchronization:<\/span><\/p>\n<ol>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Query external system for price changes<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Fetch affected BigCommerce products by SKU<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Compare current prices with new prices<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Batch update only products with price differences<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Log price history for audit purposes<\/span><\/li>\n<\/ol>\n<p><span style=\"font-weight: 400;\">This selective update approach minimizes API calls compared to full catalog updates. Schedule price synchronization during low-traffic periods to optimize store performance.<\/span><\/p>\n<h3><span style=\"font-weight: 400;\">Example 3: Inventory Management<\/span><\/h3>\n<p><span style=\"font-weight: 400;\">Real-time inventory synchronization prevents overselling and maintains accurate stock levels:<\/span><\/p>\n<ol>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Listen for webhooks from inventory management system<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Map inventory SKU to BigCommerce product<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Update inventory_level through API<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Set inventory_warning_level based on reorder points<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Trigger notifications when stock falls below threshold<\/span><\/li>\n<\/ol>\n<p><span style=\"font-weight: 400;\">Implement queue-based processing to handle high-volume inventory updates without overwhelming the API. This architecture provides resilience during traffic spikes.<\/span><\/p>\n<p><span style=\"font-weight: 400;\">These patterns apply to<\/span> <span style=\"font-weight: 400;\">various e-commerce integrations across different platforms<\/span><span style=\"font-weight: 400;\">.<\/span><\/p>\n<h2><span style=\"font-weight: 400;\">Advanced Topics and Best Practices<\/span><\/h2>\n<p><span style=\"font-weight: 400;\">Taking your BigCommerce product API integration to the next level requires understanding advanced capabilities and following industry best practices.<\/span><\/p>\n<h3><span style=\"font-weight: 400;\">Multi-Channel Product Management<\/span><\/h3>\n<p><span style=\"font-weight: 400;\">When selling across multiple channels, maintain a single source of truth in BigCommerce. Use channel-specific fields for marketplace variations:<\/span><\/p>\n<ul>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Amazon listings require UPC codes (store in custom fields)<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">eBay needs specific condition values<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Google Shopping demands GTIN compliance<\/span><\/li>\n<\/ul>\n<p><span style=\"font-weight: 400;\">Structure custom fields with channel prefixes to organize marketplace-specific data:<\/span><\/p>\n<p><span style=\"font-weight: 400;\">json<\/span><\/p>\n<p><span style=\"font-weight: 400;\">{<\/span><\/p>\n<p><span style=\"font-weight: 400;\">\u00a0\u00a0<\/span><span style=\"font-weight: 400;\">&#8220;name&#8221;<\/span><span style=\"font-weight: 400;\">:<\/span> <span style=\"font-weight: 400;\">&#8220;amazon_condition&#8221;<\/span><span style=\"font-weight: 400;\">,<\/span><\/p>\n<p><span style=\"font-weight: 400;\">\u00a0\u00a0<\/span><span style=\"font-weight: 400;\">&#8220;value&#8221;<\/span><span style=\"font-weight: 400;\">:<\/span> <span style=\"font-weight: 400;\">&#8220;New&#8221;<\/span><\/p>\n<p><span style=\"font-weight: 400;\">},<\/span><\/p>\n<p><span style=\"font-weight: 400;\">{<\/span><\/p>\n<p><span style=\"font-weight: 400;\">\u00a0\u00a0<\/span><span style=\"font-weight: 400;\">&#8220;name&#8221;<\/span><span style=\"font-weight: 400;\">:<\/span> <span style=\"font-weight: 400;\">&#8220;ebay_category_id&#8221;<\/span><span style=\"font-weight: 400;\">,<\/span><\/p>\n<p><span style=\"font-weight: 400;\">\u00a0\u00a0<\/span><span style=\"font-weight: 400;\">&#8220;value&#8221;<\/span><span style=\"font-weight: 400;\">:<\/span> <span style=\"font-weight: 400;\">&#8220;11450&#8221;<\/span><\/p>\n<p><span style=\"font-weight: 400;\">}<\/span><\/p>\n<h3><span style=\"font-weight: 400;\">API Version Migration<\/span><\/h3>\n<p><span style=\"font-weight: 400;\">If you&#8217;re currently using API v2, plan your migration to v3 carefully:<\/span><\/p>\n<ol>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Audit current v2 endpoint usage<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Identify v3 equivalents for each endpoint<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Test v3 functionality in sandbox environment<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Implement parallel requests during transition<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Monitor error rates and performance metrics<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Gradually shift traffic to v3 endpoints<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Deprecate v2 code once v3 proves stable<\/span><\/li>\n<\/ol>\n<p><span style=\"font-weight: 400;\">Run both versions simultaneously during migration to enable quick rollback if issues arise. This dual-track approach minimizes business risk.<\/span><\/p>\n<h3><span style=\"font-weight: 400;\">Security Considerations<\/span><\/h3>\n<p><span style=\"font-weight: 400;\">Protect your API credentials and implement security best practices:<\/span><\/p>\n<ul>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Store credentials in environment variables or secret managers<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Use HTTPS exclusively for all API communications<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Implement IP whitelisting when possible<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Rotate access tokens periodically<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Monitor API access logs for unusual patterns<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Never log full request\/response bodies containing sensitive data<\/span><\/li>\n<\/ul>\n<p><span style=\"font-weight: 400;\">For applications handling customer data, ensure compliance with PCI DSS, GDPR, and other relevant regulations.<\/span><\/p>\n<h3><span style=\"font-weight: 400;\">Testing Strategies<\/span><\/h3>\n<p><span style=\"font-weight: 400;\">Comprehensive testing prevents production issues:<\/span><\/p>\n<p><b>Unit Tests<\/b><span style=\"font-weight: 400;\">: Mock API responses to test business logic without live API calls<\/span><\/p>\n<p><b>Integration Tests<\/b><span style=\"font-weight: 400;\">: Use BigCommerce sandbox stores for end-to-end testing with real API endpoints<\/span><\/p>\n<p><b>Load Tests<\/b><span style=\"font-weight: 400;\">: Simulate high-volume operations to verify rate limit handling and performance under stress<\/span><\/p>\n<p><b>Error Scenario Tests<\/b><span style=\"font-weight: 400;\">: Intentionally trigger error conditions to validate error handling code paths<\/span><\/p>\n<p><span style=\"font-weight: 400;\">Maintain a dedicated test store that mirrors your production catalog structure. This environment enables safe experimentation with API features.<\/span><\/p>\n<p><span style=\"font-weight: 400;\">Similar testing approaches apply to<\/span> <span style=\"font-weight: 400;\"><a href=\"https:\/\/ecommerce.folio3.com\/bigcommerce-migration\/\">BigCommerce migrations<\/a> and <a href=\"https:\/\/ecommerce.folio3.com\/bigcommerce-integration-services\/\">integrations<\/a><\/span><span style=\"font-weight: 400;\">.<\/span><\/p>\n<h2><span style=\"font-weight: 400;\">Key Takeaways<\/span><\/h2>\n<ul>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><b>Start with API v3<\/b><span style=\"font-weight: 400;\"> for all new integrations to leverage modern features, better security, and active development support<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><b>Implement robust error handling<\/b><span style=\"font-weight: 400;\"> with retry logic, validation, and comprehensive logging to build resilient integrations<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><b>Use custom fields strategically<\/b><span style=\"font-weight: 400;\"> for storing additional product metadata while understanding their 250-character limitation<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><b>Optimize performance<\/b><span style=\"font-weight: 400;\"> through request batching, field filtering, and webhook integration to minimize API calls<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><b>Plan for scale<\/b><span style=\"font-weight: 400;\"> with proper caching, pagination, and rate limit management as your catalog grows<\/span><\/li>\n<\/ul>\n<h2><span style=\"font-weight: 400;\">Frequently Asked Questions<\/span><\/h2>\n<h3><span style=\"font-weight: 400;\">What Is the Difference Between BigCommerce API v2 and v3 for Products?<\/span><\/h3>\n<p><span style=\"font-weight: 400;\">The BigCommerce product API v3 uses OAuth 2.0 authentication instead of basic auth, provides <a href=\"https:\/\/restfulapi.net\/\" target=\"_blank\" rel=\"noopener\">REST<\/a> and <a href=\"https:\/\/graphql.org\/\" target=\"_blank\" rel=\"noopener\">GraphQL<\/a> query options, and offers better rate limits at 450 requests per 30 seconds. V3 is actively maintained while v2 receives only critical security updates.<\/span><\/p>\n<h3><span style=\"font-weight: 400;\">How Do I Define Custom Product Fields BigCommerce API?<\/span><\/h3>\n<p><span style=\"font-weight: 400;\">Use POST requests to <\/span><span style=\"font-weight: 400;\">\/v3\/catalog\/products\/{product_id}\/custom-fields<\/span><span style=\"font-weight: 400;\"> with JSON payloads containing name and value fields. Each custom field can store up to 250 characters and must be unique within the product.<\/span><\/p>\n<h3><span style=\"font-weight: 400;\">Can I Use Both BigCommerce Product API Versions Simultaneously?<\/span><\/h3>\n<p><span style=\"font-weight: 400;\">Yes, you can make requests to both <a href=\"https:\/\/ecommerce.folio3.com\/bigcommerce-v2-to-v3-migration\/\">v2 and v3<\/a> 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.<\/span><\/p>\n<h3><span style=\"font-weight: 400;\">What Rate Limits Apply to the BigCommerce API Product Endpoints?<\/span><\/h3>\n<p><span style=\"font-weight: 400;\">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.<\/span><\/p>\n<h3><span style=\"font-weight: 400;\">How Do I Handle Inventory Tracking for Product Variants?<\/span><\/h3>\n<p><span style=\"font-weight: 400;\">Set the parent product&#8217;s inventory_tracking field to &#8220;variant&#8221; and manage stock levels individually for each variant through <\/span><span style=\"font-weight: 400;\">\/v3\/catalog\/products\/{product_id}\/variants\/{variant_id}<\/span><span style=\"font-weight: 400;\"> endpoints. This enables precise inventory control for specific size\/color combinations.<\/span><\/p>\n<h3><span style=\"font-weight: 400;\">What&#8217;s the Maximum Character Limit for Custom Field Values?<\/span><\/h3>\n<p><span style=\"font-weight: 400;\">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.<\/span><\/p>\n<h3><span style=\"font-weight: 400;\">How Do I Bulk Update Product Prices?<\/span><\/h3>\n<p><span style=\"font-weight: 400;\">Send PUT requests to <\/span><span style=\"font-weight: 400;\">\/v3\/catalog\/products<\/span><span style=\"font-weight: 400;\"> 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.<\/span><\/p>\n<h3><span style=\"font-weight: 400;\">Can I Retrieve Products by SKU Instead of ID?<\/span><\/h3>\n<p><span style=\"font-weight: 400;\">Yes, use the query parameter <\/span><span style=\"font-weight: 400;\">sku=YOUR_SKU<\/span><span style=\"font-weight: 400;\"> in GET requests to <\/span><span style=\"font-weight: 400;\">\/v3\/catalog\/products<\/span><span style=\"font-weight: 400;\">. This returns products matching the specified SKU, allowing lookups without knowing internal product IDs.<\/span><\/p>\n<h2><span style=\"font-weight: 400;\">Conclusion<\/span><\/h2>\n<p><span style=\"font-weight: 400;\">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.<\/span><\/p>\n<p><span style=\"font-weight: 400;\">Ready to build your BigCommerce integration?<\/span><a href=\"https:\/\/ecommerce.folio3.com\/contact-us\/\"> <span style=\"font-weight: 400;\">Contact our team of e-commerce development experts<\/span><\/a><span style=\"font-weight: 400;\"> to discuss your specific requirements and explore how we can help optimize your online store&#8217;s API implementation.<\/span><\/p>\n","protected":false},"excerpt":{"rendered":"<p>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&#8217;re syncing inventory from an ERP system or building custom integrations, understanding how the API handles product data will save you countless hours while<\/p>\n","protected":false},"author":49,"featured_media":17291,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[28],"tags":[62],"class_list":{"0":"post-16788","1":"post","2":"type-post","3":"status-publish","4":"format-standard","5":"has-post-thumbnail","7":"category-bigcommerce","8":"tag-bigcommerce-development"},"acf":[],"featured_image_data":{"src":"https:\/\/ecommerce.folio3.com\/blog\/wp-content\/uploads\/2023\/03\/bigcommerce-api-v2-vs-v3-2.png","alt":"bigcommerce api v2 vs v3 (2)","caption":""},"_links":{"self":[{"href":"https:\/\/ecommerce.folio3.com\/blog\/wp-json\/wp\/v2\/posts\/16788"}],"collection":[{"href":"https:\/\/ecommerce.folio3.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/ecommerce.folio3.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/ecommerce.folio3.com\/blog\/wp-json\/wp\/v2\/users\/49"}],"replies":[{"embeddable":true,"href":"https:\/\/ecommerce.folio3.com\/blog\/wp-json\/wp\/v2\/comments?post=16788"}],"version-history":[{"count":0,"href":"https:\/\/ecommerce.folio3.com\/blog\/wp-json\/wp\/v2\/posts\/16788\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/ecommerce.folio3.com\/blog\/wp-json\/wp\/v2\/media\/17291"}],"wp:attachment":[{"href":"https:\/\/ecommerce.folio3.com\/blog\/wp-json\/wp\/v2\/media?parent=16788"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/ecommerce.folio3.com\/blog\/wp-json\/wp\/v2\/categories?post=16788"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/ecommerce.folio3.com\/blog\/wp-json\/wp\/v2\/tags?post=16788"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}