5. Product Catalog Management

​

Product Catalog Flow

​

Understanding Product Records

• Product identifiers: External ID, name, description
• Tax classification: Category, taxability rules
• Physical or digital designation: Affects taxability in some jurisdictions
• Custom tax codes: If applicable

​

Create Products

• During initial onboarding (after organization setup)
• When adding new products to the catalog
• Bulk product creation for catalog setup
• Automatically triggered after economic nexus registrations in this application

{
  "external_id": "PROD-001",
  "name": "Widget Pro",
  "description": "Professional widget for business use",
  "status": "APPROVED",
  "product_category": "PHYSICAL",
  "product_subcategory": "ELECTRONICS",
  "source": "OTHER",
  "tax_exempt": false
}

• x-api-key: Organization’s API key
• x-organization-id: Organization ID
• Content-Type: application/json

• external_id: Your internal product identifier (must be unique)
• name: Product name
• product_category: Product category that determines taxability rules
• status: Typically set to "APPROVED" for active products
• product_subcategory: More specific classification
• source: Origin indicator (e.g., "OTHER", "SHOPIFY", "WOOCOMMERCE")
• tax_exempt: Flag indicating if product is exempt from sales tax

• external_id should be your internal product identifier
• status typically set to "APPROVED" for active products
• product_category and product_subcategory determine tax rules
• source indicates origin (e.g., "OTHER", "SHOPIFY", "WOOCOMMERCE")
• tax_exempt flag indicates if product is exempt from sales tax
• Products are referenced in transactions for accurate tax calculation
• In this application, products are created automatically after economic nexus registrations

async function createProduct(productData, organizationId, apiKey) {
  const response = await fetch('https://api.trykintsugi.com/v1/products', {
    method: 'POST',
    headers: {
      'x-api-key': apiKey,
      'x-organization-id': organizationId,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      external_id: productData.sku,
      name: productData.name,
      description: productData.description,
      status: "APPROVED",
      product_category: productData.category,
      product_subcategory: productData.subcategory,
      source: "OTHER",
      tax_exempt: productData.isTaxExempt || false
    })
  });
  
  return await response.json();
}

​

Bulk Product Creation

async function createProductsInBatches(products, organizationId, apiKey, batchSize = 50) {
  const results = [];
  
  for (let i = 0; i < products.length; i += batchSize) {
    const batch = products.slice(i, i + batchSize);
    
    // Create products in parallel within batch
    const batchPromises = batch.map(product => 
      createProduct(product, organizationId, apiKey)
    );
    
    const batchResults = await Promise.allSettled(batchPromises);
    results.push(...batchResults);
    
    // Rate limiting: wait between batches
    if (i + batchSize < products.length) {
      await new Promise(resolve => setTimeout(resolve, 1000));
    }
  }
  
  return results;
}

​

Product Data Flow

​

Automatic Product Creation

• After creating an economic nexus registration
• Products are created with default classifications
• You can update product details later if needed

// After creating registration
const registration = await kintsugi.registrations.create({
  country_code: "US",
  state_code: "CA",
  filing_frequency: "MONTHLY",
  start_date: "2024-01-01"
}, { 'x-organization-id': organizationId });

// Products are automatically created
// You can then update product details if needed
await updateProductDetails(organizationId, apiKey);

​

Best Practices

1. Create Before Use: Create products before using them in tax estimates or transactions
2. Use Unique External IDs: Use your SKU or product ID as external_id to prevent duplicates
3. Set Appropriate Categories: Choose categories that accurately reflect product taxability
4. Batch Creation: For large catalogs, create products in batches to avoid rate limiting
5. Update When Needed: Update product records if tax classifications change
6. Verify Existence: Check if product exists before creating to avoid duplicates
7. Handle Errors: Implement retry logic for transient failures

​

Error Handling

• 409 Conflict: Product with same external_id already exists
• 400 Bad Request: Invalid category or missing required fields
• 401 Unauthorized: Invalid API key

async function createProductSafely(productData, organizationId, apiKey) {
  try {
    // Check if product already exists
    const existing = await getProductByExternalId(
      productData.external_id, 
      organizationId, 
      apiKey
    );
    
    if (existing) {
      console.log('Product already exists, updating...');
      return await updateProduct(existing.id, productData, organizationId, apiKey);
    }
    
    return await createProduct(productData, organizationId, apiKey);
  } catch (error) {
    if (error.status === 409) {
      // Product exists, fetch and return it
      return await getProductByExternalId(
        productData.external_id, 
        organizationId, 
        apiKey
      );
    }
    throw error;
  }
}

​

Product Categories Reference

• PHYSICAL: Tangible goods subject to sales tax
• DIGITAL: Digital products (may be exempt in some jurisdictions)
• SERVICE: Services (taxability varies by jurisdiction)
• SOFTWARE: Software products (may have special tax rules)
• FOOD: Food items (often exempt or reduced rate)
• CLOTHING: Clothing items (may be exempt in some states)