KashuDocs
Menu

Customers

The customers endpoints of the Kashu API, with their parameters, objects, errors and examples. The guide explains how they fit together.

EndpointWhat it does
POST /v1/customersCreate a customer.
GET /v1/customersList customers, newest first.
GET /v1/customers/{id}Retrieve a customer.
POST /v1/customers/{id}Update a customer. A field sent as null is cleared; an address replaces the one held.

The customer object

FieldTypeAbout
idstringAn id that starts cu_.
objectstringAlways "customer".
emailstring or null
namestring or null
phonestring or null
addressobject or null
address.line1string or null
address.line2string or null
address.citystring or null
address.statestring or null
address.postal_codestring or null
address.countrystring or null
metadatamap of strings
livemodeboolean
createdintegerUnix seconds.
{
  "id": "cu_1a2B3c4D5e6F7g8H9i0J1k2L",
  "object": "customer",
  "email": "jenny@example.com",
  "name": "Jenny Rosen",
  "phone": "+15555550123",
  "address": {
    "line1": "1 Market Street",
    "line2": "line2",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94105",
    "country": "US"
  },
  "metadata": {
    "order": "1001"
  },
  "livemode": false,
  "created": 1762473600
}

POST /v1/customers

Create a customer.

Scope
customers:write
Keys
Secret, or restricted with the scope below.
Idempotency-Key
Optional. Without one, Kashu makes one and returns it. See Idempotency.
Answers
201 with the Customer.

Parameters

NameInTypeRequiredAbout
Idempotency-KeyheaderstringOptionalOptional. When absent, Kashu mints one and returns it. Up to 255 characters.
Kashu-VersionheaderstringOptionalThe API version to answer in. Defaults to the key's pinned version.

Request body

FieldTypeRequiredAbout
emailstringOptionalAn email address. Up to 254 characters.
namestringOptionalUp to 200 characters.
phonestringOptionalUp to 40 characters.
addressobjectOptional
address.line1stringOptionalUp to 200 characters.
address.line2stringOptionalUp to 200 characters.
address.citystringOptionalUp to 100 characters.
address.statestringOptionalUp to 100 characters.
address.postal_codestringOptionalUp to 20 characters.
address.countrystringOptionalTwo capital letters, such as US.
metadatamap of stringsOptionalKeys up to 40 characters, values up to 500.

Errors

StatusCodes
400invalid_json, parameter_missing, parameter_invalid, parameter_unknown, api_version_invalid, idempotency_key_invalid, idempotency_key_reused
401api_key_missing, api_key_invalid, api_key_expired
403livemode_unavailable, insufficient_scope, publishable_key_not_allowed
409idempotency_key_in_use
429rate_limited
500api_error

Examples

curl https://api.kashupay.com/v1/customers \
  -H "Authorization: Bearer $KASHU_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"jenny@example.com","name":"Jenny Rosen"}'
const customer = await kashu("POST", "/v1/customers", {
  "email": "jenny@example.com",
  "name": "Jenny Rosen"
});
console.log(customer.id);

GET /v1/customers

List customers, newest first.

Scope
customers:read
Keys
Secret, or restricted with the scope below.
Idempotency-Key
Not used. A read changes nothing.
Answers
200 with a list of Customer, newest first.

Parameters

NameInTypeRequiredAbout
emailquerystringOptionalUp to 254 characters.
limitqueryintegerOptionalAt least 1. Up to 100. Defaults to 10.
cursorquerystringOptional
Kashu-VersionheaderstringOptionalThe API version to answer in. Defaults to the key's pinned version.

Errors

StatusCodes
400parameter_missing, parameter_invalid, parameter_unknown, cursor_invalid, cursor_expired, api_version_invalid
401api_key_missing, api_key_invalid, api_key_expired
403livemode_unavailable, insufficient_scope, publishable_key_not_allowed
500api_error

Examples

curl "https://api.kashupay.com/v1/customers?limit=3" \
  -H "Authorization: Bearer $KASHU_SECRET_KEY"
const list = await kashu("GET", "/v1/customers?limit=3");
console.log(list.has_more);

GET /v1/customers/{id}

Retrieve a customer.

Scope
customers:read
Keys
Secret, or restricted with the scope below.
Idempotency-Key
Not used. A read changes nothing.
Answers
200 with the Customer.

Parameters

NameInTypeRequiredAbout
idpathstringRequiredAn id that starts cu_.
Kashu-VersionheaderstringOptionalThe API version to answer in. Defaults to the key's pinned version.

Errors

StatusCodes
400parameter_unknown, api_version_invalid
401api_key_missing, api_key_invalid, api_key_expired
403livemode_unavailable, insufficient_scope, publishable_key_not_allowed
404resource_missing
500api_error

Examples

curl https://api.kashupay.com/v1/customers/cu_1a2B3c4D5e6F7g8H9i0J1k2L \
  -H "Authorization: Bearer $KASHU_SECRET_KEY"
const customer = await kashu("GET", "/v1/customers/cu_1a2B3c4D5e6F7g8H9i0J1k2L");
console.log(customer.id);

POST /v1/customers/{id}

Update a customer. A field sent as null is cleared; an address replaces the one held.

Scope
customers:write
Keys
Secret, or restricted with the scope below.
Idempotency-Key
Optional. Without one, Kashu makes one and returns it. See Idempotency.
Answers
200 with the Customer.

Parameters

NameInTypeRequiredAbout
idpathstringRequiredAn id that starts cu_.
Idempotency-KeyheaderstringOptionalOptional. When absent, Kashu mints one and returns it. Up to 255 characters.
Kashu-VersionheaderstringOptionalThe API version to answer in. Defaults to the key's pinned version.

Request body

FieldTypeRequiredAbout
emailstring or nullOptionalAn email address. Up to 254 characters.
namestring or nullOptionalUp to 200 characters.
phonestring or nullOptionalUp to 40 characters.
addressobject or nullOptional
address.line1stringOptionalUp to 200 characters.
address.line2stringOptionalUp to 200 characters.
address.citystringOptionalUp to 100 characters.
address.statestringOptionalUp to 100 characters.
address.postal_codestringOptionalUp to 20 characters.
address.countrystringOptionalTwo capital letters, such as US.
metadatamap of stringsOptionalKeys up to 40 characters, values up to 500.

Errors

StatusCodes
400invalid_json, parameter_missing, parameter_invalid, parameter_unknown, api_version_invalid, idempotency_key_invalid, idempotency_key_reused
401api_key_missing, api_key_invalid, api_key_expired
403livemode_unavailable, insufficient_scope, publishable_key_not_allowed
404resource_missing
409idempotency_key_in_use
429rate_limited
500api_error

Examples

curl https://api.kashupay.com/v1/customers/cu_1a2B3c4D5e6F7g8H9i0J1k2L \
  -H "Authorization: Bearer $KASHU_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Jenny Rosen"}'
const customer = await kashu("POST", "/v1/customers/cu_1a2B3c4D5e6F7g8H9i0J1k2L", {
  "name": "Jenny Rosen"
});
console.log(customer.id);