Customers

Create, update and retrieve the customers used to calculate tax and generate invoices.

Customers represent the individuals or organizations on your taxable transactions. A customer record stores billing and shipping addresses, tax identification numbers and exemption status, and is referenced as customer_id on a transaction.

Create or update a customer

post

/customers

Creates a customer, or merges into the existing one with the same external_id. Only the fields you send change; an address you send replaces the stored one in full.

Authorizations

X-API-KEYstringRequired

Body

Body for POST /v1/customers. external_id is the natural idempotency key — re-posting updates the existing customer (merge; an address replaces whole).

external_idstring · min: 1 · max: 255Required

namestring · max: 1024 · nullableOptionalDefault: null

emailstring · max: 255 · nullableOptionalDefault: null

tax_exemptboolean · nullableOptionalDefault: null

Responses

200Success

application/json

A customer.

external_idstringRequired

namestring · nullableOptionalDefault: null

emailstring · nullableOptionalDefault: null

tax_exemptbooleanRequired

created_atstring · date-timeRequired

400

Validation error, keyed by the failing field.

403

Missing, invalid, or inactive API key, or a key not provisioned for the Transaction API.

429

Rate limit exceeded. Carries Retry-After and RateLimit-* headers.

post/customers

POST /v1/customers HTTP/1.1
Host: api.getsphere.com
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 385

{
  "external_id": "text",
  "name": "text",
  "email": "text",
  "billing_address": {
    "address1": "text",
    "address2": "text",
    "city": "text",
    "state": "text",
    "postal_code": "text",
    "country": "text"
  },
  "shipping_address": {
    "address1": "text",
    "address2": "text",
    "city": "text",
    "state": "text",
    "postal_code": "text",
    "country": "text"
  },
  "tax_ids": [
    {
      "tax_id": "text",
      "country": "text",
      "secondary_id": "text"
    }
  ],
  "tax_exempt": true
}

{
  "external_id": "text",
  "name": "text",
  "email": "text",
  "billing_address": {
    "address1": "text",
    "address2": "text",
    "city": "text",
    "state": "text",
    "postal_code": "text",
    "country": "text"
  },
  "shipping_address": {
    "address1": "text",
    "address2": "text",
    "city": "text",
    "state": "text",
    "postal_code": "text",
    "country": "text"
  },
  "tax_ids": [
    {
      "tax_id": "text",
      "country": "text",
      "secondary_id": "text"
    }
  ],
  "tax_exempt": true,
  "created_at": "2026-01-01T00:00:00.000Z"
}

Retrieve a customer

get

/customers/{external_id}

Base for every public v1 endpoint (products, and customers/transactions later) — named for the surface, not any one resource.

Authorizations

X-API-KEYstringRequired

Path parameters

external_idstringRequired

The external_id you assigned to the record.

Responses

200Success

application/json

A customer.

external_idstringRequired

namestring · nullableOptionalDefault: null

emailstring · nullableOptionalDefault: null

tax_exemptbooleanRequired

created_atstring · date-timeRequired

403

Missing, invalid, or inactive API key, or a key not provisioned for the Transaction API.

404

No record with that external_id.

429

Rate limit exceeded. Carries Retry-After and RateLimit-* headers.

get/customers/{external_id}

GET /v1/customers/{external_id} HTTP/1.1
Host: api.getsphere.com
X-API-KEY: YOUR_API_KEY
Accept: */*

{
  "external_id": "text",
  "name": "text",
  "email": "text",
  "billing_address": {
    "address1": "text",
    "address2": "text",
    "city": "text",
    "state": "text",
    "postal_code": "text",
    "country": "text"
  },
  "shipping_address": {
    "address1": "text",
    "address2": "text",
    "city": "text",
    "state": "text",
    "postal_code": "text",
    "country": "text"
  },
  "tax_ids": [
    {
      "tax_id": "text",
      "country": "text",
      "secondary_id": "text"
    }
  ],
  "tax_exempt": true,
  "created_at": "2026-01-01T00:00:00.000Z"
}