BigCommerce Category Page Integration with Similar AI
Use the BigCommerce REST API and Python SDK to create category pages, assign products, and connect your store to Similar AI.
How It Works
We use the official BigCommerce Python package to manage your category pages. The approach is straightforward:
- -We create an invisible parent category page. All remaining pages are nested underneath it.
- -Instead of publishing an app to the BigCommerce app store, we ask you to create an API token and share the credentials with us directly.
For the full onboarding flow, see the New Page onboarding checklist.
Create an API Token
- Go to Settings → Store-level API accounts.
- Click Create API account.
- For Token type, select
V2/V3 API token. - Fill in the account name.
- In the OAuth scopes section, change the Products scope from
Nonetomodify. This is required because creating category pages needs modify permissions. - Click Save.
- Share the following three values with Similar AI: API Path, Client ID, and Access Token.
List All Products
Verify your API token works by fetching the product catalog. Replace dd02dnjzrx with your store ID and include your token in the X-Auth-Token header.
GET https://api.bigcommerce.com/stores/{store_id}/v3/catalog/products
Headers:
X-Auth-Token: your-access-token
Content-Type: application/jsonIf you receive a 200 response with your product list, the token is working correctly.
Create the Parent Category Page
Create an invisible parent category that will hold all Similar AI pages. Send a POST request to the categories endpoint:
POST https://api.bigcommerce.com/stores/{store_id}/v3/catalog/trees/categories
Body:
[
{
"name": "SimilarPage",
"url": {
"path": "/s-test-page/",
"is_customized": false
},
"parent_id": 0,
"tree_id": 1,
"description": "<p>Category description</p>",
"sort_order": 3,
"page_title": "Similar Test Page",
"meta_keywords": ["keyword1", "keyword2"],
"meta_description": "string",
"layout_file": "category.html",
"is_visible": true,
"default_product_sort": "use_store_settings"
}
]- -parent_id: 0 - places this category at the top level of your catalog tree.
- -tree_id: 1 - targets your default catalog tree. Check your store if you use multiple trees.
- -is_visible: true - set to
falseif you want to hide the parent page from navigation.
Save the category ID from the response. You will need it in the next step.
Create Child Category Pages
Use the same endpoint to create child pages. Replace parent_id with the category ID returned in the previous step.
POST https://api.bigcommerce.com/stores/{store_id}/v3/catalog/trees/categories
Body:
[
{
"name": "Child Page Name",
"url": {
"path": "/s-test-page/child-page/",
"is_customized": false
},
"parent_id": 123,
"tree_id": 1,
"description": "<p>Child category description</p>",
"page_title": "Child Page Title",
"meta_keywords": ["keyword1", "keyword2"],
"meta_description": "Child page meta description",
"layout_file": "category.html",
"is_visible": true,
"default_product_sort": "use_store_settings"
}
]Repeat this call for each child page you need. All child pages nest under the parent category created in step 3.
Assign Products to Category Pages
Once your category pages exist, assign products to them using a PUT request to the category-assignments endpoint:
PUT https://api.bigcommerce.com/stores/{store_id}/v3/catalog/products/category-assignments
Body:
[
{
"product_id": 456,
"category_id": 123
},
{
"product_id": 789,
"category_id": 123
}
]- -product_id - the ID of the product you want to assign. Use the product list from step 2 to find IDs.
- -category_id - the ID of the parent or child category page where the product should appear.
You can assign multiple products in a single request by adding more objects to the array.
Frequently asked questions
What do I need before setting up the Similar AI integration on BigCommerce?
You'll need a BigCommerce store with API access enabled and a V2/V3 REST API token with read and write permissions for catalog resources. Similar AI uses these credentials to let its agents create and manage category pages and assign products automatically.
How does Similar AI create new category pages on my BigCommerce store?
The New Pages Agent uses its sub-agent, the Topic Sieve, to filter candidate topics through checks such as search demand, product sufficiency, existing traffic, page competition, and product match, surfacing genuine opportunities with real demand. It then programmatically creates optimized category pages with schema markup, internal links, and auto-matched products. Products are assigned to each new category based on relevance, so pages are shoppable from the moment they go live.
Can Similar AI manage product assignments across existing BigCommerce categories?
Yes, the Enrichment Agent (currently in Beta) enriches your product feeds with structured data and searchable attributes such as brands, materials, and styles, making products more discoverable in both traditional and AI-powered search. This enriched product data then enables more effective category page creation without requiring manual merchandising work.
Does the integration support bulk category updates for large catalogs?
Similar AI is built for retailers with 3,000-100,000 products, so its agents handle bulk operations through batched REST API calls to stay within BigCommerce rate limits. The Cleanup Agents also removes or consolidates underperforming pages to keep the catalog structure healthy.
Where can I find code examples for the BigCommerce API token setup?
This guide includes step-by-step instructions for generating a BigCommerce API token with the correct scopes, along with code examples showing how Similar AI authenticates requests and structures category and product assignment calls. Follow the token creation section first to ensure the Linking Agent and New Pages Agent have the permissions they need.
Ready to Connect BigCommerce with Similar AI?
We handle the API integration for you. Share your credentials and your new pages can begin ranking within days, replacing weeks of manual work.