POST

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": "T-shirts",
  "product_category": "Physical",
  "product_subcategory": "General Clothing",
  "tax_exempt": false
}
'

{
  "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

Get Product Categories - View all available categories and subcategories
Get Products - List and search your products
Get Product by ID - Retrieve a specific product
Update Product - Modify product details
Product & Customer Records Guide - Learn more about product management

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,

MICROSOFT_DYNAMICS_365,

KICKSTARTER,

INTERNAL_ERP

Response

Successfully created product

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

Main category of the product. For example, Physical, Digital, etc. You can retrieve supported categories from GET /products/categories endpoint

product_subcategory

string

required

Subcategory of the product. For example, General Clothing, UNKNOWN, etc. You can retrieve supported subcategories from GET /products/categories endpoint

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,

MICROSOFT_DYNAMICS_365,

KICKSTARTER,

INTERNAL_ERP

connection_id

string

required

classification_failed

boolean

required

Managing CustomersInteractive playground for creating customers and retrieving customer records

⌘I

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": "T-shirts",
  "product_category": "Physical",
  "product_subcategory": "General Clothing",
  "tax_exempt": false
}
'

{
  "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

​When to Use

​Authentication

​Try It Out

​Required Fields

​Common Use Cases

​Basic Product Creation

​Product with Full Details

​Response Fields

​Product Categories

​Next Steps

​Related Resources

Authorizations

Body

Response

Create a Product

Overview

When to Use

Authentication

Try It Out

Required Fields

Common Use Cases

Basic Product Creation

Product with Full Details

Response Fields

Product Categories

Next Steps

Related Resources