KintsugiKintsugi
API Lab

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

  1. Create a Customer - Create a customer record with address information
  2. 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 LabSimulated
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.
1Create a customer
POST/customers

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

2Get a customer by id
GET/customers/{customer_id}

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

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

Related Resources