Create a product
Create a product in the resolved organization. Idempotent on externalId and source: sending the same values again returns the existing product unchanged and responds 200 instead of creating a duplicate. If the match is a product you previously deleted, it is restored (not duplicated) so its tax history stays attached to it; a restored product re-enters classification and its status returns to PENDING, so it is not used in tax calculation until it is approved again. The product is not otherwise updated by this call; use PATCH /products/{productId} to update. source accepts only the curated public values. status does not accept ARCHIVED; archive an existing product with DELETE /products/{productId}.
Authorization
Headers
Release date, as YYYY-MM-DD. Defaults to 2026-07-21.
Target organization id (Organization-Id selector).
Target connection id; resolves to its organization.
Platform entity id; resolves to a connection's organization.
Optional source to disambiguate an Entity-Id.
Body
Your stable identifier for the product. Creating another product with the same externalId and source returns the existing product (200) instead of a duplicate; use PATCH to update it. The same externalId can still appear on products synced from your connections.
Human-readable product name.
Optional product description.
Approval status of the product's tax classification. ARCHIVED is not accepted here: archive an existing product with DELETE /products/{id}.
APPROVEDPARTIALLY_APPROVEDPENDINGTop-level tax category for the product.
DigitalMiscPhysicalServicesTax subcategory display label within the category (e.g. 'General Clothing', 'B2B SaaS'). Together with productCategory it resolves to a product tax code; an unrecognized pair returns 400.
Whether the product is treated as tax-exempt by tax calculation. This is the effective exemption flag applied to transactions.
Origin system of the product (e.g. API, SHOPIFY). Defaults to OTHER. Must be a supported public source; unsupported values are rejected.
ACUMATICAAIRWALLEXAMAZONAPIAPPLE_APP_STOREBESTBUYBIGCOMMERCEBILL_COMBUNNYCAMPFIRECHARGEBEECHECKOUTCHAMPDEELDUALENTRYEBAYECWIDETSYFACEBOOKFAIREFRESHBOOKSGOOGLE_APP_STOREGOOGLE_EXPRESSGROUPONGUSTOHYPERLINEINSTAGRAMINTUIT_ENTERPRISE_SUITEKICKSTARTERKILL_BILLMACYSMAGENTOMAXIOMERCADO_LIBREMICROSOFT_DYNAMICS_365MODALYSTNETSUITENEWEGGNOCNOCNORDSTROMODOOOPENMETERORBORDWAYOTHERPAYPALPINTERESTPLENTYONEQUICKBOOKSRECURLYRILLETRIPPLINGSAGE-INTACCTSALESFORCESHOPIFYSHOPLINESHOPWARESQUARESPACESTRIPETARGETTIKTOKVERTEX_O_SERIESWALMARTWAYFAIRWISHWIXWOOCOMMERCEXEROZENSKARZOHOZUORARaw tax-exempt signal as reported by the source system, stored for auditing. Distinct from taxExempt (the derived, effective flag). Optional on create; always returned on read.
Response
Kintsugi's unique identifier for the product.
Organization the product belongs to. Send it as Organization-Id to scope a request to this product.
Display name of the organization the product belongs to. null when the organization has no name set.
Your stable identifier for the product, as supplied on create.
SKUs associated with the product. An empty list when it has none.
Derived product tax code display name.
Human-readable product name.
Product description; an empty string when the product has none.
Approval status of the product's tax classification.
APPROVEDPARTIALLY_APPROVEDPENDINGARCHIVEDDerived display category for the product's tax code.
Derived display subcategory for the product's tax code.
Effective tax-exemption flag applied by tax calculation.
Raw tax-exempt signal reported by the source system (audit). null when the source system did not report a signal, which is distinct from an explicit false.
Origin system of the product (e.g. API, SHOPIFY). Any origin outside the published values is reported as OTHER.
ACUMATICAAIRWALLEXAMAZONAPIAPPLE_APP_STOREBESTBUYBIGCOMMERCEBILL_COMBUNNYCAMPFIRECHARGEBEECHECKOUTCHAMPDEELDUALENTRYEBAYECWIDETSYFACEBOOKFAIREFRESHBOOKSGOOGLE_APP_STOREGOOGLE_EXPRESSGROUPONGUSTOHYPERLINEINSTAGRAMINTUIT_ENTERPRISE_SUITEKICKSTARTERKILL_BILLMACYSMAGENTOMAXIOMERCADO_LIBREMICROSOFT_DYNAMICS_365MODALYSTNETSUITENEWEGGNOCNOCNORDSTROMODOOOPENMETERORBORDWAYOTHERPAYPALPINTERESTPLENTYONEQUICKBOOKSRECURLYRILLETRIPPLINGSAGE-INTACCTSALESFORCESHOPIFYSHOPLINESHOPWARESQUARESPACESTRIPETARGETTIKTOKVERTEX_O_SERIESWALMARTWAYFAIRWISHWIXWOOCOMMERCEXEROZENSKARZOHOZUORAIdentifier of the connection that produced the product. null when the product was not produced by a connection (e.g. created manually).
Display name of the connection (store) that produced the product. null when the product has no connection, or the connection has no store name set.
Whether automated tax classification failed for the product. null when classification has not been attempted.
An existing product matched on externalId and source; no new product was created. A live match is returned unchanged. A previously deleted match is revived and re-enters classification (its status returns to PENDING), so it may differ from its pre-deletion state.
Successful Response
The request was invalid.
Authentication failed or was missing.
The credential is not permitted for this request.
The requested resource was not found.
The request conflicts with existing state.
The request failed validation.