Catalog Management API Documentation

Talking Shops WhatsApp Catalog Management API

The Catalog Management API allows you to programmatically manage your WhatsApp Business catalog. You can create, update, delete products, and sync inventory levels directly from your systems.

Base URL

https://api.talkingshops.com/v1/catalog

Authentication

All API requests require authentication using an API key in the header:

http

x-tenant-api-key: your_api_key_here

Endpoints Overview

Endpoint	Method	Description
`/`	GET	Get catalog information
`/products`	GET	List products in catalog
`/products`	POST	Create or update a single product
`/products/batch`	POST	Batch create/update products (max 50)
`/products/{productId}`	DELETE	Delete a single product
`/products/batch`	DELETE	Batch delete products (max 50)
`/inventory/sync`	POST	Sync inventory levels (max 100)

Product Data Structure

Basic Product Fields

Field	Type	Required	Description
`id`	string	Yes	Unique product retailer identifier (used by Meta API as primary key)
`name`	string	Yes	Product name (max 200 chars)
`price`	number	Yes	Product price
`currency`	string	No	Currency code (default: INR)
`description`	string	No	Product description (max 1000 chars)
`availability`	string	No	"in stock" or "out of stock" (default: "in stock")
`condition`	string	No	"new", "refurbished", or "used" (default: "new")
`image_url`	string	No	Main product image URL
`url`	string	No	Product page URL
`brand`	string	No	Product brand
`category`	string	No	Product category
`inventory`	number	No	Inventory quantity

Product Variants

Products can have variants (size, color, etc.) which are processed as separate products in WhatsApp:

json

{
  "variants": [
    {
      "id": "variant_123",
      "title": "Size M",
      "price": 29.99,
      "inventory_quantity": 10
    },
    {
      "title": "Size L", 
      "inventory_quantity": 5
    }
  ]
}

Variant Processing:

Each variant becomes a separate product in WhatsApp with its own unique ID
If no variant id is provided, it's auto-generated as {product_id}_{title_lowercase_with_underscores}
Variant titles are appended to the main product name

API Reference

1. Get Catalog Information

Retrieve information about your WhatsApp catalog.

http

GET /v1/catalog

Response:

json

{
  "success": true,
  "catalog": {
    "id": "catalog_123",
    "name": "My Business Catalog",
    "product_count": 150,
    "catalog_id": "catalog_123",
    "phone_number_id": "123456789",
    "waba_id": "waba_123"
  }
}

2. List Products

Get products from your catalog with optional filtering.

http

GET /v1/catalog/products?limit=30&offset=0&search=shirt&category=clothing

Query Parameters:

limit (number, optional): Number of products to return (1-100, default: 30)
search (string, optional): Search term for product name or description
category (string, optional): Filter by product category
after (string, optional): Cursor for pagination

Response:

json

{
  "success": true,
  "products": [
    {
      "id": "prod_123",
      "name": "Samsung Galaxy S24",
      "description": "Latest Samsung smartphone with advanced features",
      "price": "999.00 USD",
      "availability": "in stock",
      "condition": "new",
      "image_url": "https://example.com/galaxy-s24.jpg",
      "brand": "Samsung",
      "category": "electronics",
      "inventory": 25,
      "visibility": "published"
    }
  ],
  "total": 156,
  "limit": 10,
  "offset": 0,
  "has_more": true,
  "next_cursor": "eyJpZCI6InByb2RfMTMzIn0",  // 🆕 Use for next page
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 156,
    "has_more": true,
    "next_cursor": "eyJpZCI6InByb2RfMTMzIn0"
  }
}

Note: The id field in the response corresponds to your product's retailer identifier - the same ID you use when creating, updating, or deleting products.

3. Create or Update Single Product

Create a new product or update an existing one.

http

POST /v1/catalog/products

Request Body:

json

{
  "product": {
    "id": "prod_123",
    "name": "Cotton T-Shirt",
    "description": "Comfortable cotton t-shirt available in multiple sizes",
    "price": 25.00,
    "currency": "INR",
    "availability": "in stock",
    "condition": "new",
    "image_url": "https://example.com/tshirt.jpg",
    "url": "https://mystore.com/products/cotton-tshirt",
    "brand": "MyBrand",
    "category": "clothing",
    "inventory": 50,
    "variants": [
      {
        "title": "Size S",
        "inventory_quantity": 10
      },
      {
        "title": "Size M", 
        "inventory_quantity": 20
      },
      {
        "title": "Size L",
        "inventory_quantity": 20
      }
    ],
    "additional_image_urls": [
      "https://example.com/tshirt-back.jpg",
      "https://example.com/tshirt-detail.jpg"
    ]
  }
}

Response:

json

{
  "success": true,
  "product": {
    "id": "prod_123",
    "variants_processed": 3,
    "handles": ["handle_abc123"]
  },
  "message": "Product created/updated successfully"
}

4. Batch Create/Update Products

Create or update multiple products in a single request (max 50 products).

http

POST /v1/catalog/products/batch

Request Body:

json

{
  "products": [
    {
      "id": "prod_123",
      "name": "Cotton T-Shirt",
      "price": 25.00,
      "inventory": 50
    },
    {
      "id": "prod_124",
      "name": "Denim Jeans",
      "price": 45.00,
      "inventory": 30,
      "variants": [
        {
          "title": "Size 32",
          "inventory_quantity": 10
        },
        {
          "title": "Size 34",
          "inventory_quantity": 20
        }
      ]
    }
  ],
  "allow_upsert": true
}

Response:

json

{
  "success": true,
  "total": 2,
  "successful": 2,
  "failed": 0,
  "succeeded": [
    {
      "id": "prod_123",
      "title": "Cotton T-Shirt"
    },
    {
      "id": "prod_124", 
      "title": "Denim Jeans"
    }
  ],
  "failed_items": [],
  "handles": ["handle_abc123", "handle_def456"],
  "message": "Batch operation completed"
}

5. Delete Single Product

Delete a product from your catalog.

http

DELETE /v1/catalog/products/prod_123

Note: The product ID in the URL path is sufficient for deletion. No request body is required.

Response:

json

{
  "success": true,
  "message": "Product deleted successfully",
  "result": {
    "id": "prod_123",
    "handles": ["handle_xyz789"]
  }
}

6. Batch Delete Products

Delete multiple products (max 50 per request).

http

DELETE /v1/catalog/products/batch

Request Body:

json

{
  "product_ids": ["prod_123", "prod_124", "prod_125"]
}

Response:

json

{
  "success": true,
  "total": 3,
  "successful": 3,
  "failed": 0,
  "succeeded": [
    {
      "id": "prod_123",
      "title": "Product prod_123"
    },
    {
      "id": "prod_124",
      "title": "Product prod_124"
    },
    {
      "id": "prod_125",
      "title": "Product prod_125"
    }
  ],
  "failed_items": [],
  "handles": ["handle_abc123"],
  "message": "Batch delete operation completed"
}

7. Sync Inventory

Update inventory levels for multiple products (max 100 per request).

http

POST /v1/catalog/inventory/sync

Request Body:

json

{
  "inventory_updates": [
    {
      "id": "prod_123",
      "inventory": 25,
      "availability": "in stock"
    },
    {
      "id": "prod_124",
      "inventory": 0,
      "availability": "out of stock"
    },
    {
      "id": "prod_125",
      "inventory": 15
    }
  ]
}

Response:

json

{
  "success": true,
  "total": 3,
  "successful": 3,
  "failed": 0,
  "succeeded": [
    {
      "id": "prod_123",
      "title": "Product prod_123"
    },
    {
      "id": "prod_124",
      "title": "Product prod_124"
    },
    {
      "id": "prod_125",
      "title": "Product prod_125"
    }
  ],
  "failed_items": [],
  "handles": ["handle_inv123"],
  "message": "Inventory sync completed"
}

Error Handling

All endpoints return standard HTTP status codes:

200 - Success
400 - Bad Request (validation errors)
401 - Unauthorized (invalid API key)
404 - Not Found (tenant or catalog not found)
429 - Too Many Requests (rate limit exceeded)
500 - Internal Server Error

Error Response Format:

json

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Product id, name, and price are required",
    "details": {
      "field": "product.name",
      "value": ""
    }
  }
}

Rate Limits

General API calls: 100 requests per minute
Batch operations: 10 requests per minute
Inventory sync: 20 requests per minute

Integration Examples

Node.js Example

javascript

const axios = require('axios');

const apiKey = 'your_api_key_here';
const baseURL = 'https://api.talkingshops.com/v1/catalog';

const catalogAPI = axios.create({
  baseURL,
  headers: {
    'x-tenant-api-key': apiKey,
    'Content-Type': 'application/json'
  }
});

// Create a product
async function createProduct() {
  try {
    const response = await catalogAPI.post('/products', {
      product: {
        id: 'shirt_001',
        name: 'Premium Cotton Shirt',
        price: 49.99,
        currency: 'USD',
        description: 'High-quality cotton shirt',
        image_url: 'https://example.com/shirt.jpg',
        inventory: 100
      }
    });
    
    console.log('Product created:', response.data);
  } catch (error) {
    console.error('Error:', error.response.data);
  }
}

// Sync inventory
async function syncInventory(updates) {
  try {
    const response = await catalogAPI.post('/inventory/sync', {
      inventory_updates: updates
    });
    
    console.log('Inventory synced:', response.data);
  } catch (error) {
    console.error('Error:', error.response.data);
  }
}

// Usage examples
await createProduct();

await syncInventory([
  {
    id: 'shirt_001',
    inventory: 25,
    availability: 'in stock'
  },
  {
    id: 'shirt_002', 
    inventory: 0,
    availability: 'out of stock'
  }
]);

Python Example

python

import requests

API_KEY = 'your_api_key_here'
BASE_URL = 'https://api.talkingshops.com/v1/catalog'

headers = {
    'x-tenant-api-key': API_KEY,
    'Content-Type': 'application/json'
}

def create_product(product_data):
    response = requests.post(
        f'{BASE_URL}/products',
        json={'product': product_data},
        headers=headers
    )
    return response.json()

def batch_update_inventory(inventory_updates):
    response = requests.post(
        f'{BASE_URL}/inventory/sync',
        json={'inventory_updates': inventory_updates},
        headers=headers
    )
    return response.json()

# Usage examples
product = {
    'id': 'jeans_001',
    'name': 'Classic Denim Jeans',
    'price': 79.99,
    'inventory': 50
}

result = create_product(product)
print(result)

# Sync inventory
inventory_updates = [
    {
        'id': 'jeans_001',
        'inventory': 25,
        'availability': 'in stock'
    },
    {
        'id': 'shirt_001',
        'inventory': 0,
        'availability': 'out of stock'
    }
]

sync_result = batch_update_inventory(inventory_updates)
print(sync_result)

Best Practices

Product IDs: Use consistent, meaningful product IDs that align with your inventory system. These IDs will be used across all catalog operations.
Batch Operations: Use batch endpoints when updating multiple products to reduce API calls and improve performance.
Error Handling: Always handle errors gracefully and check the failed_items array in batch operations.
Rate Limiting: Implement exponential backoff when you hit rate limits.
Inventory Sync: Use the inventory sync endpoint for frequent stock updates rather than updating entire products.
Image URLs: Ensure image URLs are publicly accessible and use HTTPS.
Product Variants: Consider whether to use variants or separate products based on your business needs. Variants are processed as separate products in WhatsApp.
Data Validation: Validate your data before sending to avoid API errors.
ID Management: The id field is your product's unique identifier in the WhatsApp catalog. Keep it consistent across all operations.

Support

For API support, contact our team at info@talkingshops.com or check our developer portal for more resources.

Catalog Management API Documentation ​

Talking Shops WhatsApp Catalog Management API ​

Base URL ​

Authentication ​

Endpoints Overview ​

Product Data Structure ​

Basic Product Fields ​

Product Variants ​

API Reference ​

1. Get Catalog Information ​

2. List Products ​

3. Create or Update Single Product ​

4. Batch Create/Update Products ​

5. Delete Single Product ​

6. Batch Delete Products ​

7. Sync Inventory ​

Error Handling ​

Rate Limits ​

Integration Examples ​

Node.js Example ​

Python Example ​

Best Practices ​

Support ​

Catalog Management API Documentation

Talking Shops WhatsApp Catalog Management API

Base URL

Authentication

Endpoints Overview

Product Data Structure

Basic Product Fields

Product Variants

API Reference

1. Get Catalog Information

2. List Products

3. Create or Update Single Product

4. Batch Create/Update Products

5. Delete Single Product

6. Batch Delete Products

7. Sync Inventory

Error Handling

Rate Limits

Integration Examples

Node.js Example

Python Example

Best Practices

Support