Skip to main content
POST
/
v1
/
products
Create Product
curl --request POST \
  --url https://api.trykintsugi.com/v1/products/ \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --header 'x-organization-id: <api-key>' \
  --data '
{
  "external_id": "prod_001",
  "name": "Sample Product",
  "description": "A description of the product",
  "status": "APPROVED",
  "product_category": "PHYSICAL",
  "product_subcategory": "GENERAL_CLOTHING",
  "tax_exempt": false,
  "source": "BIGCOMMERCE"
}
'
{
  "id": "prod_xR9t8P1wMK6aQ",
  "external_id": "prod_123",
  "code": "CODE_1234",
  "name": "Test Product",
  "description": "This is a test product description.",
  "status": "APPROVED",
  "product_category": "PHYSICAL",
  "product_subcategory": "GENERAL_CLOTHING",
  "tax_exempt": false,
  "source": "SHOPIFY",
  "classification_failed": false
}

​
Create a Product

​
Overview

Products in Kintsugi represent the items you sell. Each product needs proper tax classification (category and subcategory) to ensure accurate tax calculations. This endpoint creates a new product record that will be used for tax calculations in transactions.

​
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 requires two headers:
  • x-api-key: Your API key
  • x-organization-id: Your organization ID
Both headers are required for authentication. You can find your API key and organization ID in your Kintsugi dashboard.

​
Try It Out

Use the interactive playground below to create a product. The playground will automatically include the required authentication headers.
The playground prefills example values from the API schema. Modify the request body to test different product configurations. You’ll need valid product categories and subcategories - see the Get Product Categories endpoint for available options.

​
Required Fields

  • external_id: Your internal product identifier (must be unique within your organization)
  • product_name: Name of the product
  • product_category: Product category (see Get Product Categories)
  • product_subcategory: Product subcategory (see Get Product Categories)

​
Common Use Cases

​
Basic Product Creation

Create a product with minimal required fields: 
{
  "external_id": "SKU-12345",
  "product_name": "Example Product",
  "product_category": "Physical",
  "product_subcategory": "General Physical"
}

​
Product with Full Details

Include additional product information: 
{
  "external_id": "PROD-ABC-123",
  "product_name": "Premium Wireless Headphones",
  "product_category": "Physical",
  "product_subcategory": "General Physical",
  "product_description": "High-quality wireless headphones with noise cancellation",
  "source": "API"
}

​
Response Fields

The API returns detailed product information:
  • id: Kintsugi’s unique product identifier
  • external_id: Your product identifier
  • product_name: Product name
  • product_category: Product category
  • product_subcategory: Product subcategory
  • status: Product status (ACTIVE, ARCHIVED)
  • source: Source of the product record
  • created_at: Timestamp when the product was created

​
Product Categories

Before creating products, you may want to fetch available categories and subcategories using the Get Product Categories endpoint. Categories determine how products are taxed across different jurisdictions.
Product categories align with tax regulations across jurisdictions. Choose the most specific category and subcategory that matches your product to ensure accurate tax calculations.

​
Next Steps

Authorizations

​
X-API-KEY
string
header
required
​
x-organization-id
string
header
required

Body

application/json
​
external_id
string
required

A unique external identifier for the product.

​
name
string
required

The name of the product.

​
product_category
enum<string>
required

The high-level category of the product.

Available options:
PHYSICAL,
DIGITAL,
SERVICE,
UNKNOWN,
MISCELLANEOUS
​
product_subcategory
enum<string>
required

The subcategory of the product.

Available options:
UNKNOWN,
SAAS,
DIGITAL_GENERAL,
B2B_SAAS,
SOFTWARE_ON_PERSONAL_PROPERTY,
SOFTWARE_DOWNLOADED,
CUSTOM_SOFTWARE_ON_PERSONAL_PROPERTY,
CUSTOM_SOFTWARE_DOWNLOADED,
CUSTOMIZATION_OF_SOFTWARE,
B2C_SAAS,
IAAS,
SERVICE_GENERAL,
PROFESSIONAL_SERVICE,
TANGIBLE_PROPERTY_SERVICE,
REAL_PROPERTY_SERVICE,
BUSINESS_SERVICE,
PERSONAL_SERVICE,
AMUSEMENT_SERVICE,
MEDICAL_SERVICES,
SECURITY_SERVICES_ELECTRONIC_MONITORING,
FACILITY_MAINTENANCE_REAL_PROPERTY_LABOR_ONLY,
COMMERCIAL_RENOVATION_CAPITAL_IMPROVEMENT_LABOR,
COMMERCIAL_CONSTRUCTION_EXISTING_BUILDINGS_LABOR,
PHYSICAL_GENERAL,
GENERAL_CLOTHING,
CATERING,
GROCERY_FOOD,
LEASES_AND_RENTALS_MOTOR_VEHICLES,
LEASES_AND_RENTALS_TANGIBLE_MEDIA_PROPERTY,
MACHINERY,
RAW_MATERIALS,
UTILITIES_FUEL,
MEDICAL_DEVICES,
MEDICINES,
NEWSPAPERS,
PERIODICALS,
GENERAL_OCCASIONAL_SALES,
MOTOR_VEHICLES_OCCASIONAL_SALES,
GENERAL_OPTIONAL_MAINTENANCE_CONTRACTS,
PARTS_PURCHASED_OPTIONAL_MAINTENANCE_CONTRACTS,
GENERAL_POLLUTION_CONTROL_EQUIPMENT,
GENERAL_TRADE_INS,
FOOD_VENDING_MACHINE,
MERCHANDISE_VENDING_MACHINE,
SUPPLEMENTS,
FEMININE_HYGIENE,
ORAL_HYGIENE,
BEVERAGE_NUTRITION_LABEL_ENERGY_SHOTS_AND_DRINKS,
DIETARY_SUPPLEMENTS_SUPPLEMENT_FACTS_LABEL_RETAIL,
ADVERTISING_MEDIA_INSERT_DISTRIBUTED_BY_NEWSPAPER,
ADVERTISING_MEDIA_INSERT_DISTRIBUTED_BY_MAIL_PACKAGE,
MAINTENANCE_SERVICES_MATERIALS,
NUTRITION_BARS,
SHIPPING,
GIFT_CARD,
CREDIT_CARD_SURCHARGES,
CREDIT_CARD_FEES,
MISCELLANEOUS_EXEMPT,
DISCOUNT,
GIFT_WRAPPING,
HANDLING,
TAX,
DANCE_LESSONS
​
tax_exempt
boolean
required

Specifies whether the product is tax-exempt.

​
description
string

A description of the product.

​
status
enum<string>
default:APPROVED

The approval status of the product.

Available options:
APPROVED,
PARTIALLY_APPROVED,
PENDING
​
source
enum<string>
default:OTHER

Indicates the source of the product.

Available options:
BIGCOMMERCE,
BESTBUY,
BUNNY,
CHARGEBEE,
SHOPIFY,
STRIPE,
AMAZON,
TIKTOK,
CUSTOM,
UNKNOWN,
IMPORT,
ZUORA,
APIDECK,
QUICKBOOKS,
API,
APPLE_APP_STORE,
GOOGLE_APP_STORE,
WALMART,
PAYPAL,
NETSUITE,
XERO,
MAXIO,
RECURLY,
SALESFORCE,
ETSY,
EBAY,
WIX,
SQUARESPACE,
WOOCOMMERCE,
MAGENTO,
BILLING_PLATFORM,
DEEL,
RIPPLING,
GUSTO,
FACEBOOK,
OTHER,
ORDWAY,
INSTAGRAM,
PINTEREST,
WAYFAIR,
WISH,
POS,
TARGET,
NEWEGG,
GROUPON,
GOOGLE_EXPRESS,
NOCNOC,
MERCADO_LIBRE,
MODALYST,
NORDSTROM,
FAIRE,
SHOPWARE,
ZOHO,
SAGE-INTACCT,
AIRWALLEX,
ORB,
ZENSKAR

Response

Successfully created product

​
id
string
required
​
external_id
string
required
​
sku
string[]
required
​
code
string
required
​
name
string
required
​
description
string
required
​
status
enum<string>
required
Available options:
APPROVED,
PARTIALLY_APPROVED,
PENDING
​
product_category
string
required
​
product_subcategory
string
required
​
tax_exempt
boolean
required
​
source
enum<string>
required
Available options:
BIGCOMMERCE,
BESTBUY,
BUNNY,
CHARGEBEE,
SHOPIFY,
STRIPE,
AMAZON,
TIKTOK,
CUSTOM,
UNKNOWN,
IMPORT,
ZUORA,
APIDECK,
QUICKBOOKS,
API,
APPLE_APP_STORE,
GOOGLE_APP_STORE,
WALMART,
PAYPAL,
NETSUITE,
XERO,
MAXIO,
RECURLY,
SALESFORCE,
ETSY,
EBAY,
WIX,
SQUARESPACE,
WOOCOMMERCE,
MAGENTO,
BILLING_PLATFORM,
DEEL,
RIPPLING,
GUSTO,
FACEBOOK,
OTHER,
ORDWAY,
INSTAGRAM,
PINTEREST,
WAYFAIR,
WISH,
POS,
TARGET,
NEWEGG,
GROUPON,
GOOGLE_EXPRESS,
NOCNOC,
MERCADO_LIBRE,
MODALYST,
NORDSTROM,
FAIRE,
SHOPWARE,
ZOHO,
SAGE-INTACCT,
AIRWALLEX,
ORB,
ZENSKAR
​
connection_id
string
required
​
classification_failed
boolean
required