KintsugiKintsugi
API Lab

Create a Product

Overview

Products in Kintsugi represent the items you sell. Each product needs a tax classification, a category and subcategory, so tax is calculated accurately. This endpoint creates a new product record that is used for tax calculations in transactions.

Creating a product is idempotent on externalId and source: sending the same values again returns the existing product unchanged with 200 instead of creating a duplicate. To change a product, use Update a product.

When to Use

  • Product catalog setup: Create products when setting up your integration
  • New product launches: Add new products as you expand your catalog
  • Tax classification: Ensure products have proper tax categories for accurate calculations
  • Manual product management: Create products outside of automated syncs

Authentication

This endpoint takes one credential header:

  • Api-Key: Your API key

Api-Version: 2026-07-21 is optional. A request without it runs against 2026-07-21. When your key can reach more than one organization, add an Organization-Id, Connection-Id or Entity-Id header to choose which one the product is created in.

Try It Out

API LabSimulated
Runs in a simulated sandbox. Responses are generated from the API schema so you can explore each call safely; they never reach the live API, so the values are illustrative.
1Create a product
POST/products
2List the product category catalog
GET/products/categories

Browse the categories you can assign to a product.

3Get a product by id
GET/products/{product_id}
Run the previous step to fill the path.

Required Fields

  • externalId: Your stable identifier for the product
  • name: Human-readable product name
  • productCategory: Top-level tax category: Digital, Misc, Physical or Services (see List the product category catalog)
  • productSubcategory: Tax subcategory label within the category (see List the product category catalog). An unrecognized category and subcategory pair returns 400
  • taxExempt: Whether tax calculation treats the product as tax-exempt

Common Use Cases

Basic Product Creation

Create a product with only the required fields:

{
  "externalId": "sku-1001",
  "name": "Blue T-Shirt",
  "productCategory": "Physical",
  "productSubcategory": "General Clothing",
  "taxExempt": false
}

Product with Full Details

Include the classification status and the source system:

{
  "externalId": "sku-1001",
  "name": "Blue T-Shirt",
  "status": "APPROVED",
  "productCategory": "Physical",
  "productSubcategory": "General Clothing",
  "taxExempt": false,
  "source": "API"
}

status accepts APPROVED, PARTIALLY_APPROVED or PENDING. It does not accept ARCHIVED; archive an existing product with Archive a product. source defaults to OTHER and must be a supported public value.

Response Fields

  • id: Kintsugi's unique identifier for the product
  • externalId: Your stable identifier for the product, as supplied on create
  • name: Human-readable product name
  • productCategory: Derived display category for the product's tax code
  • productSubcategory: Derived display subcategory for the product's tax code
  • status: Approval status of the product's tax classification (APPROVED, PARTIALLY_APPROVED, PENDING, ARCHIVED)
  • taxExempt: Effective tax-exemption flag applied by tax calculation
  • source: Origin system of the product, such as API or SHOPIFY

Product Categories

Before creating products, fetch the available categories and subcategories with List the product category catalog. Each entry's category and each subcategory's label are the exact values productCategory and productSubcategory accept.

Together, productCategory and productSubcategory resolve to a product tax code. Choose the most specific category and subcategory that matches your product to ensure accurate tax calculations.

Next Steps

Related Resources