# Managing Customers

> Interactive walkthrough for creating customers and retrieving customer records

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

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

Example Request

{
"external_id": "CUST-001",
"name": "Acme Corporation",
"email": "contact@acme.com",
"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

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 customer

POST /v1/customers

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

{

"phone": "987-654-3210",

"street_1": "456 Elm St",

"street_2": "Suite 202",

"city": "Metropolis",

"county": "Wayne",

"state": "NY",

"postal_code": "10001",

"country": "US",

"name": "Jane Smith",

"external_id": "cust_002",

"status": "ARCHIVED",

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

"source": "SHOPIFY",

"address_status": "PARTIALLY_VERIFIED"

}

{
"phone": "987-654-3210",
"street_1": "456 Elm St",
"street_2": "Suite 202",
"city": "Metropolis",
"county": "Wayne",
"state": "NY",
"postal_code": "10001",
"country": "US",
"name": "Jane Smith",
"external_id": "cust_002",
"status": "ARCHIVED",
"email": "jane.smith@example.com",
"source": "SHOPIFY",
"address_status": "PARTIALLY_VERIFIED"
}

Run

2 Get customer by id

GET /v1/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

external_id: Your internal customer identifier (must be unique within your organization)

name: Customer name

email: Customer email address

## 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": "contact@acme.com",
"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": "info@nonprofit.org",
"street_1": "456 Charity Ave",
"city": "Austin",
"state": "TX",
"postal_code": "78701",
"country": "US",
"status": "ACTIVE"
}

## Response Fields

id: Kintsugi's unique customer identifier

external_id: Your customer identifier

name: Customer name

email: Customer email

status: Customer status (ACTIVE, ARCHIVED)

address_status: Address verification status

## 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

## Related Resources

Customers API Reference

Getting Started

Support

---

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