agents-store Catalog Import
This skill covers the catalog import tool — importing a full catalog of categories and products from structured JSON data in a single operation.
Available Tools
| Tool | Description |
|---|---|
import_catalog |
Import full catalog (categories + products) from JSON |
Import Catalog
Tool: import_catalog
Input: {
"options": {
"mode": "merge",
"stockControl": true
},
"categories": [
{
"externalId": "cat-electronics",
"title": "Electronics",
"parentExternalId": null,
"imageUrl": "https://example.com/electronics.jpg"
},
{
"externalId": "cat-phones",
"title": "Smartphones",
"parentExternalId": "cat-electronics",
"imageUrl": "https://example.com/phones.jpg"
}
],
"products": [
{
"sku": "IPHONE-15-PRO",
"title": "iPhone 15 Pro",
"price": 999.99,
"description": "Latest iPhone with titanium design",
"discountPrice": 899.99,
"quantity": 50,
"categoryExternalId": "cat-phones",
"imageUrls": [
"https://example.com/iphone1.jpg",
"https://example.com/iphone2.jpg"
],
"attributes": [
{ "name": "Storage", "value": "256GB", "type": "string" },
{ "name": "Color", "value": "Space Black,#1d1d1f", "type": "color" }
],
"brand": "Apple",
"isActive": true,
"stockControl": true
}
]
}
Max request size: 10 MB
Import Options
| Field | Type | Required | Values | Description |
|---|---|---|---|---|
| mode | string | YES | merge, replace | How to handle existing data |
| stockControl | boolean | no | true/false | Enable stock control for imported products |
Import modes:
merge— Add new items, update existing (matched by SKU for products, externalId for categories). Existing items not in the import are preserved.replace— Remove all existing data and replace with imported data. Use with caution!
Category Import Format
| Field | Type | Required | Description |
|---|---|---|---|
| externalId | string | YES | Your unique ID for the category (used for linking) |
| title | string | YES | Category display name |
| parentExternalId | string | no | Parent category's externalId (for hierarchy) |
| imageUrl | string | no | URL to category image (will be downloaded) |
Categories are linked via externalId / parentExternalId — build hierarchy within a single import.
Product Import Format
| Field | Type | Required | Description |
|---|---|---|---|
| sku | string | YES | Unique product SKU |
| title | string | YES | Product title |
| price | number | YES | Product price |
| description | string | no | Product description |
| discountPrice | number | no | Discounted price |
| quantity | number | no | Available quantity |
| categoryExternalId | string | no | Category externalId to assign |
| imageUrls | array[string] | no | URLs to product images (downloaded automatically) |
| attributes | array | no | Product attributes |
| brand | string | no | Brand name |
| variantGroupId | string | no | Group ID for variant products |
| isActive | boolean | no | Whether product is active |
| stockControl | boolean | no | Per-product stock control override |
Attribute Format in Import
{ "name": "Size", "value": "XL", "type": "string" }
{ "name": "Color", "value": "Red,#FF0000", "type": "color" }
Attribute types:
string— plain text valuecolor— format:"ColorName,#HexCode"(comma-separated name and hex)
Variant Grouping
Products with the same variantGroupId are linked as variants:
[
{ "sku": "TSHIRT-S", "title": "T-Shirt S", "price": 29, "variantGroupId": "tshirt-group" },
{ "sku": "TSHIRT-M", "title": "T-Shirt M", "price": 29, "variantGroupId": "tshirt-group" },
{ "sku": "TSHIRT-L", "title": "T-Shirt L", "price": 29, "variantGroupId": "tshirt-group" }
]
Common Workflows
Initial Store Setup from Spreadsheet Data
1. Prepare JSON with categories and products from spreadsheet
2. import_catalog(mode="merge", categories=[...], products=[...]) -> Import all
3. list_categories() -> Verify categories created
4. list_products() -> Verify products created
Sync with External System
1. Get updated data from external system
2. import_catalog(mode="merge", products=[updated products]) -> Merge changes
(SKU matching: existing products updated, new products added)
Full Catalog Replace
1. import_catalog(mode="replace", categories=[...], products=[...])
WARNING: This deletes ALL existing products and categories first!
Best Practices
- Use "merge" mode for most imports — safer and preserves existing data
- Use "replace" mode only for full catalog resets
- Always set externalId on categories for proper hierarchy linking
- Use SKU as the unique identifier — merge mode matches by SKU
- Keep import under 10 MB — split large catalogs into multiple imports
- Use imageUrls — the platform downloads and stores images automatically
- Test with a small batch first before importing the full catalog
- Use variantGroupId to link product variants within the import