BigCommerce Integration Guide

This guide will walk you through integrating Claudery with your BigCommerce store. BigCommerce uses store-level API credentials that are created directly in your store’s control panel. You’ll need to create a store-level API account to connect your store to Claudery.

Prerequisites

• Active BigCommerce store with admin/owner access
• Claudery SaaS account and access to the Claudery dashboard

Step 1: Access Store-Level API Accounts

1.1 Log in to BigCommerce

1. Log in to your BigCommerce control panel
2. Navigate to Advanced Settings → API Accounts
3. You’ll see a list of existing API accounts (if any)

Important: BigCommerce uses store-level API accounts. These are created directly in your store’s control panel, not in a separate developer portal. The API credentials you create are specific to your store.

Step 2: Create Store-Level API Account

2.1 Create New API Account

1. Click the Create API Account button (or Create V2/V3 API Token)
2. Enter an account name (e.g., “Claudery AI Integration”)
3. Select the API scopes/permissions you need:
   • Products – Read and modify products
   • Orders – Read order information
   • Customers – Read customer information
   • Catalog – Read catalog information

2.2 Save and Get Credentials

1. Click Save to create the API account
2. BigCommerce will display your API credentials
3. You’ll see the following information:
   • API Path – Contains your store hash (e.g., https://api.bigcommerce.com/stores/abc123/v3/)
   • Client ID
   • Access Token – This is your API access token
4. Copy all credentials immediately – the Access Token is only shown once

Important: Copy the Access Token immediately and store it securely. The token will only be displayed once. If you lose it, you’ll need to create a new API account.

Step 3: Extract Store Hash from API Path

3.1 Get Store Hash

1. From the API Path provided by BigCommerce, extract your store hash
2. The API Path format is: https://api.bigcommerce.com/stores/{store-hash}/v3/
3. The store hash is the value between /stores/ and /v3/
4. Example: If API Path is https://api.bigcommerce.com/stores/abc123/v3/, your store hash is abc123
5. Alternatively, if your store URL is https://store-abc123.mybigcommerce.com, your store hash is abc123

Step 4: Get Account UUID (If Required)

4.1 Find Account UUID

1. Account UUID is typically only needed for multi-store accounts or account-level API access
2. For store-level API accounts (which is what we’re using), Account UUID may not be required
3. If Account UUID is needed, you can find it in:
   • BigCommerce Developer Portal (developer.bigcommerce.com) if you have account-level access
   • Your BigCommerce account settings
   • Or contact BigCommerce support
4. Note: For most store-level integrations, Account UUID can be left blank

Step 5: Configure Claudery Platform Settings

5.1 Access Claudery Dashboard

1. Log in to your Claudery SaaS dashboard
2. Navigate to your merchant site settings
3. Go to the Quick Start section or Platform Settings

5.2 Select BigCommerce Platform

1. Select BigCommerce as your e-commerce platform
2. This will display the BigCommerce-specific credential fields

5.3 Enter Store Hash (Required)

1. Paste your Store Hash into the Store Hash field
2. This is the store hash you extracted from the API Path in Step 3
3. Do not include the “store-” prefix – just the hash itself (e.g., abc123)
4. Alternatively, you can enter your store URL and the system will auto-extract the hash

5.4 Enter Client ID

1. Paste your Client ID into the Client ID field
2. This is the Client ID from your store-level API account
3. Ensure there are no extra spaces

5.5 Enter Access Token (Required)

1. Paste your Access Token into the Access Token field
2. This is the Access Token from your store-level API account
3. Ensure there are no extra spaces

5.6 Enter Account UUID (Optional – for Multi-Store Accounts)

1. If you have multiple stores or need account-level access, enter your Account UUID
2. For single-store integrations, this field can typically be left blank
3. If provided, use the full UUID format (e.g., 34b5266e-xxxx-xxxx-xxxx-xxxxxxxxxxxx)

5.7 Enter Client Secret (If Required)

1. If Client Secret is required for your account type, paste it into the Client Secret field
2. For store-level API accounts created in the control panel, Client Secret may not be required
3. Check the API account details in BigCommerce to see if Client Secret was provided

5.8 Test Connection

1. Click the Test Connection or Save & Test button
2. Wait for the connection test to complete
3. If successful, you’ll see a confirmation message
4. If there’s an error, verify all credentials are correct

Step 6: Sync Products

6.1 Initial Product Sync

1. After successful connection, navigate to the Product Sync section
2. Click Sync Products or Initial Sync
3. Wait for the sync process to complete
4. Monitor the progress – larger catalogs may take several minutes

6.2 Verify Sync

1. Check the sync status in the dashboard
2. Review the product count to ensure all products were synced
3. If any products failed to sync, check the error logs for details

Step 7: Configure Widget Settings

7.1 Get Widget Embed Code

1. Navigate to Widget Settings in your Claudery dashboard
2. Copy the provided JavaScript embed code

7.2 Add Widget to BigCommerce Theme

1. In BigCommerce control panel, go to Storefront → Theme Editor
2. Navigate to Footer or Global Footer template
3. Add the Claudery widget script before the closing </body> tag
4. Save and publish your theme

Troubleshooting

Connection Errors

• Verify your Store Hash is correct (extracted from API Path or store URL)
• Ensure your Client ID and Access Token are copied correctly (no extra spaces)
• Check that the API account has the required scopes/permissions
• Verify the API account is active in BigCommerce
• Ensure you’re using store-level API credentials (created in Advanced Settings → API Accounts)
• If Account UUID is required, verify it’s in the correct UUID format
• For store-level API accounts, Client Secret may not be required – check BigCommerce API account details

Sync Issues

• Check that products exist in your BigCommerce store
• Review error logs in the Claudery dashboard for specific error messages
• Verify your API scopes include product read permissions
• Check BigCommerce API rate limits if sync is intermittent
• Ensure the store hash is correct if you have multiple stores

Credential Issues

• If Access Token is lost, you’ll need to create a new store-level API account (tokens are only shown once)
• Store-level API accounts use simple token authentication (not full OAuth flow)
• Ensure you’re using store-level API credentials, not account-level credentials
• Verify the store hash matches your store (check your store URL format)
• If you have multiple stores, create separate API accounts for each store

Security Notes

• Keep all API credentials secure – treat them like passwords
• If credentials are compromised, revoke the API account in BigCommerce and create a new one
• Use the minimum required API scopes for security
• Regularly review API accounts and their permissions in BigCommerce
• Monitor API usage and set up alerts for unusual activity
• Consider using environment variables to store credentials securely

API Information

Claudery uses BigCommerce Store-Level API V3 for all operations. The integration uses store-level API credentials, which means:

• API accounts are created directly in your store’s control panel (Settings → API Accounts)
• Credentials are specific to your store (store hash is required)
• Store hash is extracted from the API Path provided by BigCommerce
• The integration uses the store-level API endpoint: https://api.bigcommerce.com/stores/{hash}/v3/
• Supports cursor-based pagination for efficient data retrieval from large catalogs

Next Steps: Once integration is complete, you can customize your AI assistant settings, configure product search preferences, and start using Claudery’s AI-powered shopping features on your BigCommerce store.