# Managing Customers (2026-07-21)

> Interactive walkthrough for creating customers and retrieving customer records

Source: https://docs.trykintsugi.com/docs/2026-07-21/recipes/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

A transaction does not need a separate customer record. You can pass the buyer's details in the customer object of a transaction request, or omit it for a sale with no customer identity.

## 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 API Lab below with POST /customers.

Example Request

{
"externalId": "cust-1001",
"name": "Acme Corp",
"email": "jane.doe@example.com",
"street1": "123 Main St",
"city": "San Francisco",
"state": "CA",
"postalCode": "94105",
"country": "US"
}

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

## Step 2: Retrieve Customers

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

Search with the search parameter, which matches a customer's id, externalId and externalFriendlyId exactly, and its name and email as a case-insensitive substring

Filter by country and state

Page through all customers with limit and the cursor from a prior response's nextCursor or previousCursor

## Authentication

These endpoints take 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 request targets.

## Try It Out

API Lab Simulated

Run all Reset Share Copy cURL Postman

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.

1 Create a customer

POST /customers

Send a customer record. The response returns the new customer, including its id.

{

"externalId": "cust-1001",

"name": "Acme Corp",

"email": "jane.doe@example.com",

"street1": "123 Main St",

"city": "San Francisco",

"state": "CA",

"postalCode": "94105",

"country": "US"

}

{
"externalId": "cust-1001",
"name": "Acme Corp",
"email": "jane.doe@example.com",
"street1": "123 Main St",
"city": "San Francisco",
"state": "CA",
"postalCode": "94105",
"country": "US"
}

Run

2 Get a customer by id

GET /customers/{customer_id}

Fetch the customer you just created. The id from step 1 fills the path automatically.

Run Run the previous step to fill the path.

## Required Fields

The request schema marks no field as required. Send an externalId: it is your stable identifier for the customer and the key that makes creation idempotent.

## Common Use Cases

Basic Customer Creation

Create a customer with an identifier, a name and an address:

{
"externalId": "cust-1001",
"name": "Acme Corp",
"street1": "123 Main St",
"city": "San Francisco",
"state": "CA",
"postalCode": "94105",
"country": "US"
}

Customer with Full Details

Include complete customer information, including a tax registration:

{
"externalId": "cust-1001",
"name": "Acme Corp",
"companyName": "Acme Corp",
"email": "jane.doe@example.com",
"phone": "+1 415 555 0100",
"source": "API",
"taxRegistrations": [
{
"countryCode": "CA",
"taxType": "gst",
"taxId": "123456789RT0001"
}
],
"street1": "123 Main St",
"street2": "Suite 400",
"city": "San Francisco",
"county": "San Francisco County",
"state": "CA",
"postalCode": "94105",
"country": "US"
}

Each tax registration needs a countryCode, taxType and taxId, and a customer holds one registration per countryCode and taxType pair.

Exempt Customer

Creating a customer does not record an exemption. Create the customer as in Step 1, then record the exemption with Create an exemption, passing the customer's id as customerId.

## Response Fields

id: Kintsugi's unique identifier for the customer

externalId: Your stable identifier for the customer

name: Customer name

email: Contact email address

status: Whether the customer record is in use or retired (ACTIVE, ARCHIVED)

addressStatus: Whether the customer's address has been validated

## Next Steps

List customers - List and search customers

Get a customer by id - Retrieve a specific customer

Update a customer - Modify customer details

Product & Customer Records Guide - Learn more about customer management

## Related Resources

Customers API Reference

Getting Started

Support

---

Index of every page: https://docs.trykintsugi.com/llms.txt