Managing Customers

Overview

Customer records in Kintsugi store customer information and enable exemption management. While not required for all integrations, customer records are essential when dealing with tax-exempt customers (nonprofits, resellers, etc.) or when you need to track customer-specific tax information.

When to Create Customer Records

Tax-exempt customers: Nonprofits, resellers, or other exempt entities
Customer exemptions: When customers have jurisdiction-specific exemptions
Customer tracking: When you need to maintain customer tax history

For regular taxable customers, you can pass customer information directly in transaction requests without creating separate customer records.

Workflow

Create a Customer - Create a customer record with address information
Retrieve Customers - Search and retrieve customer records

Step 1: Create a Customer

Create a customer record using the interactive playground below with POST /v1/customers.

Required Fields

external_id: Your internal customer identifier (must be unique)
name: Customer name
Address information (at minimum: country, state, city, postal_code)

Example Request

{
  "external_id": "CUST-001",
  "name": "Acme Corporation",
  "email": "[email protected]",
  "street_1": "123 Business St",
  "city": "San Francisco",
  "state": "CA",
  "postal_code": "94105",
  "country": "US"
}

Step 2: Retrieve Customers

After creating customers, retrieve them using GET /v1/customers. You can:

Search by external_id using the search_query parameter
Filter by country and state
Paginate through all customers

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 customer. 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 customer configurations.

Common Use Cases

Basic Customer Creation

Create a customer with minimal required fields:

{
  "external_id": "CUST-12345",
  "name": "John Doe",
  "street_1": "123 Main St",
  "city": "Seattle",
  "state": "WA",
  "postal_code": "98101",
  "country": "US"
}

Customer with Full Details

Include complete customer information:

{
  "external_id": "CUST-ABC-123",
  "name": "Acme Corporation",
  "email": "[email protected]",
  "phone": "555-123-4567",
  "street_1": "123 Business St",
  "street_2": "Suite 100",
  "city": "San Francisco",
  "county": "San Francisco",
  "state": "CA",
  "postal_code": "94105",
  "country": "US",
  "source": "API"
}

Exempt Customer

Create a customer that may be tax-exempt:

{
  "external_id": "CUST-NONPROFIT-001",
  "name": "Nonprofit Organization",
  "email": "[email protected]",
  "street_1": "456 Charity Ave",
  "city": "Austin",
  "state": "TX",
  "postal_code": "78701",
  "country": "US",
  "status": "ACTIVE"
}

Response Fields

The API returns detailed customer information:

id: Kintsugi’s unique customer identifier
external_id: Your customer identifier
name: Customer name
email: Customer email
address_status: Address verification status
status: Customer status (ACTIVE, ARCHIVED)

Next Steps

Get Customers - List and search customers
Get Customer By ID - Retrieve specific customer
Update Customer - Modify customer details
Product & Customer Records Guide - Learn more about customer management

Authorizations

X-API-KEY

string

header

required

x-organization-id

string

header

required

Body

application/json

phone

string

Customer's phone number

street_1

string

Primary street address.

street_2

string

Additional street address details, such as an apartment or suite number.

city

string

City where the customer resides.

county

string

County or district of the customer.

state

string

State or province of the customer.

postal_code

string

ZIP or Postal code of the customer.

country

enum<string>

Country code in ISO 3166-1 alpha-2 format

Available options:

AF,

AX,

AL,

DZ,

AS,

AD,

AO,

AI,

AQ,

AG,

AR,

AM,

AW,

AU,

AT,

AZ,

BS,

BH,

BD,

BB,

BY,

BE,

BZ,

BJ,

BM,

BT,

BO,

BQ,

BA,

BW,

BV,

BR,

IO,

BN,

BG,

BF,

BI,

CV,

KH,

CM,

CA,

KY,

CF,

TD,

CL,

CN,

CX,

CC,

CO,

KM,

CG,

CD,

CK,

CR,

HR,

CU,

CW,

CY,

CZ,

DK,

DJ,

DM,

DO,

EC,

EG,

SV,

GQ,

ER,

EE,

SZ,

ET,

FK,

FO,

FJ,

FI,

FR,

GF,

PF,

TF,

GA,

GM,

GE,

DE,

GH,

GI,

GR,

GL,

GD,

GP,

GU,

GT,

GG,

GN,

GW,

GY,

HT,

HM,

VA,

HN,

HK,

HU,

IS,

IN,

ID,

IR,

IQ,

IE,

IM,

IL,

IT,

CI,

JM,

JP,

JE,

JO,

KZ,

KE,

KI,

KP,

KR,

KW,

KG,

LA,

LV,

LB,

LS,

LR,

LY,

LI,

LT,

LU,

MO,

MG,

MW,

MY,

MV,

ML,

MT,

MH,

MQ,

MR,

MU,

YT,

MX,

FM,

MD,

MC,

MN,

ME,

MS,

MA,

MZ,

MM,

NA,

NR,

NP,

NL,

NC,

NZ,

NI,

NE,

NG,

NU,

NF,

MK,

MP,

NO,

OM,

PK,

PW,

PS,

PA,

PG,

PY,

PE,

PH,

PN,

PL,

PT,

PR,

QA,

RE,

RO,

RU,

RW,

BL,

SH,

KN,

LC,

MF,

PM,

VC,

WS,

SM,

ST,

SA,

SN,

RS,

SC,

SL,

SG,

SX,

SK,

SI,

SB,

SO,

ZA,

GS,

SS,

ES,

LK,

SD,

SR,

SJ,

SE,

CH,

SY,

TW,

TJ,

TZ,

TH,

TL,

TG,

TK,

TO,

TT,

TN,

TR,

TM,

TC,

TV,

UG,

UA,

AE,

GB,

US,

UM,

UY,

UZ,

VU,

VE,

VN,

VG,

VI,

WF,

EH,

YE,

ZM,

ZW,

XK,

ZZ_EU

full_address

string

Complete address string of the customer, which can be used as an alternative to individual fields.

name

string

Name of the customer.

external_id

string

External identifier associated with the customer.

status

enum<string>

default:ACTIVE

Status of the customer.

Available options:

ACTIVE,

ARCHIVED

string

Customer's email address

source

enum<string>

Source of the customer's record.

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

Identifier for the connection source, if applicable.

address_status

enum<string>

default:UNVERIFIED

Status of address verification

Available options:

UNVERIFIED,

INVALID,

PARTIALLY_VERIFIED,

VERIFIED,

UNVERIFIABLE,

BLANK

registration_number

string

Registration number of the customer.

external_friendly_id

string

External friendly identifier associated with the customer. We need it for netsuite.

customer_tax_registrations

CustomerTaxRegistrationRead · object[]

Customer tax registrations associated with the customer.

Show child attributes

customer_tax_registrations.id

string

required

customer_tax_registrations.customer_id

string

required

customer_tax_registrations.country_code

enum<string>

required

Available options:

AF,

AX,

AL,

DZ,

AS,

AD,

AO,

AI,

AQ,

AG,

AR,

AM,

AW,

AU,

AT,

AZ,

BS,

BH,

BD,

BB,

BY,

BE,

BZ,

BJ,

BM,

BT,

BO,

BQ,

BA,

BW,

BV,

BR,

IO,

BN,

BG,

BF,

BI,

CV,

KH,

CM,

CA,

KY,

CF,

TD,

CL,

CN,

CX,

CC,

CO,

KM,

CG,

CD,

CK,

CR,

HR,

CU,

CW,

CY,

CZ,

DK,

DJ,

DM,

DO,

EC,

EG,

SV,

GQ,

ER,

EE,

SZ,

ET,

FK,

FO,

FJ,

FI,

FR,

GF,

PF,

TF,

GA,

GM,

GE,

DE,

GH,

GI,

GR,

GL,

GD,

GP,

GU,

GT,

GG,

GN,

GW,

GY,

HT,

HM,

VA,

HN,

HK,

HU,

IS,

IN,

ID,

IR,

IQ,

IE,

IM,

IL,

IT,

CI,

JM,

JP,

JE,

JO,

KZ,

KE,

KI,

KP,

KR,

KW,

KG,

LA,

LV,

LB,

LS,

LR,

LY,

LI,

LT,

LU,

MO,

MG,

MW,

MY,

MV,

ML,

MT,

MH,

MQ,

MR,

MU,

YT,

MX,

FM,

MD,

MC,

MN,

ME,

MS,

MA,

MZ,

MM,

NA,

NR,

NP,

NL,

NC,

NZ,

NI,

NE,

NG,

NU,

NF,

MK,

MP,

NO,

OM,

PK,

PW,

PS,

PA,

PG,

PY,

PE,

PH,

PN,

PL,

PT,

PR,

QA,

RE,

RO,

RU,

RW,

BL,

SH,

KN,

LC,

MF,

PM,

VC,

WS,

SM,

ST,

SA,

SN,

RS,

SC,

SL,

SG,

SX,

SK,

SI,

SB,

SO,

ZA,

GS,

SS,

ES,

LK,

SD,

SR,

SJ,

SE,

CH,

SY,

TW,

TJ,

TZ,

TH,

TL,

TG,

TK,

TO,

TT,

TN,

TR,

TM,

TC,

TV,

UG,

UA,

AE,

GB,

US,

UM,

UY,

UZ,

VU,

VE,

VN,

VG,

VI,

WF,

EH,

YE,

ZM,

ZW,

XK,

ZZ_EU

customer_tax_registrations.tax_type

enum<string>

required

Enum for customer tax registration types.

Available options:

gst,

hst,

gst_hst,

qst,

pst,

rst,

vat,

unknown

customer_tax_registrations.tax_id

string

required

customer_tax_registrations.is_valid

boolean

required

Response

Successfully created customer

string

required

Unique identifier for the customer required.

organization_id

string

required

Unique identifier for the organization associated with the customer. Required.

phone

string

Customer's phone number

street_1

string

Primary street address.

street_2

string

Additional street address details, such as an apartment or suite number.

city

string

City where the customer resides.

county

string

County or district of the customer.

state

string

State or province of the customer.

postal_code

string

ZIP or Postal code of the customer.

country

enum<string>

Country code in ISO 3166-1 alpha-2 format

Available options:

AF,

AX,

AL,

DZ,

AS,

AD,

AO,

AI,

AQ,

AG,

AR,

AM,

AW,

AU,

AT,

AZ,

BS,

BH,

BD,

BB,

BY,

BE,

BZ,

BJ,

BM,

BT,

BO,

BQ,

BA,

BW,

BV,

BR,

IO,

BN,

BG,

BF,

BI,

CV,

KH,

CM,

CA,

KY,

CF,

TD,

CL,

CN,

CX,

CC,

CO,

KM,

CG,

CD,

CK,

CR,

HR,

CU,

CW,

CY,

CZ,

DK,

DJ,

DM,

DO,

EC,

EG,

SV,

GQ,

ER,

EE,

SZ,

ET,

FK,

FO,

FJ,

FI,

FR,

GF,

PF,

TF,

GA,

GM,

GE,

DE,

GH,

GI,

GR,

GL,

GD,

GP,

GU,

GT,

GG,

GN,

GW,

GY,

HT,

HM,

VA,

HN,

HK,

HU,

IS,

IN,

ID,

IR,

IQ,

IE,

IM,

IL,

IT,

CI,

JM,

JP,

JE,

JO,

KZ,

KE,

KI,

KP,

KR,

KW,

KG,

LA,

LV,

LB,

LS,

LR,

LY,

LI,

LT,

LU,

MO,

MG,

MW,

MY,

MV,

ML,

MT,

MH,

MQ,

MR,

MU,

YT,

MX,

FM,

MD,

MC,

MN,

ME,

MS,

MA,

MZ,

MM,

NA,

NR,

NP,

NL,

NC,

NZ,

NI,

NE,

NG,

NU,

NF,

MK,

MP,

NO,

OM,

PK,

PW,

PS,

PA,

PG,

PY,

PE,

PH,

PN,

PL,

PT,

PR,

QA,

RE,

RO,

RU,

RW,

BL,

SH,

KN,

LC,

MF,

PM,

VC,

WS,

SM,

ST,

SA,

SN,

RS,

SC,

SL,

SG,

SX,

SK,

SI,

SB,

SO,

ZA,

GS,

SS,

ES,

LK,

SD,

SR,

SJ,

SE,

CH,

SY,

TW,

TJ,

TZ,

TH,

TL,

TG,

TK,

TO,

TT,

TN,

TR,

TM,

TC,

TV,

UG,

UA,

AE,

GB,

US,

UM,

UY,

UZ,

VU,

VE,

VN,

VG,

VI,

WF,

EH,

YE,

ZM,

ZW,

XK,

ZZ_EU

full_address

string

Complete address string of the customer, which can be used as an alternative to individual fields.

name

string

Name of the customer.

external_id

string

External identifier associated with the customer.

status

enum<string>

default:ACTIVE

Status of the customer.

Available options:

ACTIVE,

ARCHIVED

string

Customer's email address

source

enum<string>

Source of the customer's record.

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

Identifier for the connection source, if applicable.

address_status

enum<string>

default:UNVERIFIED

Status of address verification

Available options:

UNVERIFIED,

INVALID,

PARTIALLY_VERIFIED,

VERIFIED,

UNVERIFIABLE,

BLANK

registration_number

string

Registration number of the customer.

external_friendly_id

string

External friendly identifier associated with the customer. We need it for netsuite.

customer_tax_registrations

CustomerTaxRegistrationRead · object[]

Customer tax registrations associated with the customer.

Show child attributes

customer_tax_registrations.id

string

required

customer_tax_registrations.customer_id

string

required

customer_tax_registrations.country_code

enum<string>

required

Available options:

AF,

AX,

AL,

DZ,

AS,

AD,

AO,

AI,

AQ,

AG,

AR,

AM,

AW,

AU,

AT,

AZ,

BS,

BH,

BD,

BB,

BY,

BE,

BZ,

BJ,

BM,

BT,

BO,

BQ,

BA,

BW,

BV,

BR,

IO,

BN,

BG,

BF,

BI,

CV,

KH,

CM,

CA,

KY,

CF,

TD,

CL,

CN,

CX,

CC,

CO,

KM,

CG,

CD,

CK,

CR,

HR,

CU,

CW,

CY,

CZ,

DK,

DJ,

DM,

DO,

EC,

EG,

SV,

GQ,

ER,

EE,

SZ,

ET,

FK,

FO,

FJ,

FI,

FR,

GF,

PF,

TF,

GA,

GM,

GE,

DE,

GH,

GI,

GR,

GL,

GD,

GP,

GU,

GT,

GG,

GN,

GW,

GY,

HT,

HM,

VA,

HN,

HK,

HU,

IS,

IN,

ID,

IR,

IQ,

IE,

IM,

IL,

IT,

CI,

JM,

JP,

JE,

JO,

KZ,

KE,

KI,

KP,

KR,

KW,

KG,

LA,

LV,

LB,

LS,

LR,

LY,

LI,

LT,

LU,

MO,

MG,

MW,

MY,

MV,

ML,

MT,

MH,

MQ,

MR,

MU,

YT,

MX,

FM,

MD,

MC,

MN,

ME,

MS,

MA,

MZ,

MM,

NA,

NR,

NP,

NL,

NC,

NZ,

NI,

NE,

NG,

NU,

NF,

MK,

MP,

NO,

OM,

PK,

PW,

PS,

PA,

PG,

PY,

PE,

PH,

PN,

PL,

PT,

PR,

QA,

RE,

RO,

RU,

RW,

BL,

SH,

KN,

LC,

MF,

PM,

VC,

WS,

SM,

ST,

SA,

SN,

RS,

SC,

SL,

SG,

SX,

SK,

SI,

SB,

SO,

ZA,

GS,

SS,

ES,

LK,

SD,

SR,

SJ,

SE,

CH,

SY,

TW,

TJ,

TZ,

TH,

TL,

TG,

TK,

TO,

TT,

TN,

TR,

TM,

TC,

TV,

UG,

UA,

AE,

GB,

US,

UM,

UY,

UZ,

VU,

VE,

VN,

VG,

VI,

WF,

EH,

YE,

ZM,

ZW,

XK,

ZZ_EU

customer_tax_registrations.tax_type

enum<string>

required

Enum for customer tax registration types.

Available options:

gst,

hst,

gst_hst,

qst,

pst,

rst,

vat,

unknown

customer_tax_registrations.tax_id

string

required

customer_tax_registrations.is_valid

boolean

required

​Managing Customers

​Overview

​When to Create Customer Records

​Workflow

​Step 1: Create a Customer

​Required Fields

​Example Request

​Step 2: Retrieve Customers

​Authentication

​Try It Out

​Common Use Cases

​Basic Customer Creation

​Customer with Full Details

​Exempt Customer

​Response Fields

​Next Steps

​Related Resources

Authorizations

Body

Response

Managing Customers

Overview

When to Create Customer Records

Workflow

Step 1: Create a Customer

Required Fields

Example Request

Step 2: Retrieve Customers

Authentication

Try It Out

Common Use Cases

Basic Customer Creation

Customer with Full Details

Exempt Customer

Response Fields

Next Steps

Related Resources