Customers

Customers represent the people paying you. Create a customer before you save a card, run a charge, or start a subscription. Best practice: create the customer once, store its cus_* id on your own user record, and reuse that id for every action on the person's behalf - checkout sessions, setup sessions, subscriptions, charges, and billing-portal sessions. The cus_* id is the durable handle that ties saved cards, subscriptions (the user's current plan), charge history, and tax documents together, so reusing it keeps the user's plan and self-service billing pages intact. Creating a fresh customer each time fragments one person into duplicate, disconnected records.

Use cases: Keep a single record for every payer across charges and subscriptions, attach metadata to link to your own users table, and let customers manage cards from the hosted Billing Portal. One person in your system should map to exactly one CHING customer for life.

POST/v1/customers

Create a customer scoped to your project. Customers are isolated per project and per mode (test vs live).

Body Parameters

Name	Type		Description
`name`	string	required	Display name. Used across the dashboard and receipts.
`email`	string		Email address. Used for receipts, setup-session emails, and the Billing Portal.
`phone`	string		Phone number in E.164 format (e.g. +972501234567).
`locale`	string		Preferred locale for customer-facing surfaces. Defaults to "he".
`taxId`	string		Tax ID (if the customer is a business).
`metadata`	object		Set of key-value pairs you can attach to the object for your own use. Returned as-is on retrieval.

Request

curl -X POST "https://api.ching.co.il/ching/v1/customers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "example_name",
  "email": "example_email",
  "phone": "example_phone",
  "locale": "example_locale",
  "taxId": "example_taxId",
  "metadata": {}
}'

Response

{
  "success": true,
  "data": {
    "id": "cus_V8ltq1pK_MWH",
    "object": "customer",
    "name": "Tal Levi",
    "email": "tal@example.com",
    "phone": "+972501234567",
    "locale": "he",
    "taxId": null,
    "metadata": {},
    "default_payment_method": "pm_WMc9X22NT1af",
    "livemode": false,
    "created": "2026-04-19T09:12:43.000Z"
  }
}

GET/v1/customers

List the 100 most recent customers in the current mode, newest first.

List endpoints currently return up to 100 results, newest first. For larger result sets use the dashboard export or filter by metadata in your application layer.

Request

curl -X GET "https://api.ching.co.il/ching/v1/customers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response

{
  "success": true,
  "data": [
    {
      "id": "cus_V8ltq1pK_MWH",
      "object": "customer",
      "name": "Tal Levi",
      "email": "tal@example.com",
      "phone": "+972501234567",
      "locale": "he",
      "taxId": null,
      "metadata": {},
      "default_payment_method": "pm_WMc9X22NT1af",
      "livemode": false,
      "created": "2026-04-19T09:12:43.000Z"
    }
  ]
}

GET/v1/customers/:id

Retrieve a customer by its id.

Path Parameters

Name	Type		Description
`id`	string	required	The customer id (e.g. cus_V8ltq1pK_MWH).

Request

curl -X GET "https://api.ching.co.il/ching/v1/customers/:id" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response

{
  "success": true,
  "data": {
    "id": "cus_V8ltq1pK_MWH",
    "object": "customer",
    "name": "Tal Levi",
    "email": "tal@example.com",
    "phone": "+972501234567",
    "locale": "he",
    "taxId": null,
    "metadata": {},
    "default_payment_method": "pm_WMc9X22NT1af",
    "livemode": false,
    "created": "2026-04-19T09:12:43.000Z"
  }
}

POST/v1/customers/:id

Update an existing customer. Only the fields you send are changed; omitted fields keep their current value.

Emits a customer.updated webhook event. Returns 404 if no customer with that id exists in the current mode.

Path Parameters

Name	Type		Description
`id`	string	required	The customer id (e.g. cus_V8ltq1pK_MWH).

Body Parameters

Name	Type	Description
`name`	string	Display name.
`email`	string	Email address. Send an empty string to clear it.
`phone`	string	Phone number. Local Israeli formats are accepted and stored as E.164 (e.g. "054-987-6543" becomes "+972549876543").
`locale`	string	Preferred locale for customer-facing surfaces.
`taxId`	string	Tax ID (if the customer is a business).
`metadata`	object	Set of key-value pairs you can attach to the object for your own use. Returned as-is on retrieval.

Request

curl -X POST "https://api.ching.co.il/ching/v1/customers/:id" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "example_name",
  "email": "example_email",
  "phone": "example_phone",
  "locale": "example_locale",
  "taxId": "example_taxId",
  "metadata": {}
}'

Response

{
  "success": true,
  "data": {
    "id": "cus_V8ltq1pK_MWH",
    "object": "customer",
    "name": "Tal Levi",
    "email": "tal@example.com",
    "phone": "+972501234567",
    "locale": "he",
    "taxId": null,
    "metadata": {},
    "default_payment_method": "pm_WMc9X22NT1af",
    "livemode": false,
    "created": "2026-04-19T09:12:43.000Z"
  }
}

POST/v1/customers/upsert

Create a customer, or update the existing one that matches on a field you choose. Use this to sync customers from your own system without first checking whether they already exist.

The response includes an "action" field: "created" or "updated". A created customer emits customer.created; an updated one emits customer.updated. If several customers match the identifier, the most recently created one is updated.

Body Parameters

Name	Type		Description
`identifyBy`	string	required	Which field locates an existing customer: "email", "taxId", or "phone". The named field must be present in the body. If a match is found it is updated (patch semantics); otherwise a new customer is created.
`name`	string		Display name. Required when a new customer is created (no match found); optional when updating.
`email`	string		Email address.
`phone`	string		Phone number. Local Israeli formats are normalized to E.164 before matching and storage.
`locale`	string		Preferred locale for customer-facing surfaces. Defaults to "he" on create.
`taxId`	string		Tax ID (if the customer is a business).
`metadata`	object		Set of key-value pairs you can attach to the object for your own use. Returned as-is on retrieval.

Request

curl -X POST "https://api.ching.co.il/ching/v1/customers/upsert" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "identifyBy": "example_identifyBy",
  "name": "example_name",
  "email": "example_email",
  "phone": "example_phone",
  "locale": "example_locale",
  "taxId": "example_taxId",
  "metadata": {}
}'

Response

{
  "success": true,
  "action": "updated",
  "data": {
    "id": "cus_V8ltq1pK_MWH",
    "object": "customer",
    "name": "Tal Levi",
    "email": "tal@example.com",
    "phone": "+972501234567",
    "locale": "he",
    "taxId": null,
    "metadata": {},
    "default_payment_method": "pm_WMc9X22NT1af",
    "livemode": false,
    "created": "2026-04-19T09:12:43.000Z"
  }
}

DELETE/v1/customers/:id

Soft-delete a customer. The record is tombstoned (not erased): all charges, documents, and subscriptions keep referencing it, so your financial history stays intact. Saved cards are detached so no future charge can land on the customer.

Returns 409 (CUSTOMER_HAS_ACTIVE_SUBSCRIPTION) if the customer has a subscription in active, trialing, or past_due - cancel it first. Emits customer.deleted. After deletion the customer is excluded from list, is skipped by upsert matching, and can no longer be updated; GET returns the minimal { id, object, deleted: true } stub. The call is idempotent.

Path Parameters

Name	Type		Description
`id`	string	required	The customer id (e.g. cus_V8ltq1pK_MWH).

Request

curl -X DELETE "https://api.ching.co.il/ching/v1/customers/:id" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response

{
  "success": true,
  "data": {
    "id": "cus_V8ltq1pK_MWH",
    "object": "customer",
    "deleted": true
  }
}