Customer CRUD API — v1.0.4 Release

Calmony Pay v1.0.4 introduces a full set of Stripe-compatible REST endpoints for managing customers. All endpoints live under /v1/customers and are automatically scoped to your project via your API key.

Customer ID Format

Every customer created through the API is assigned a unique identifier prefixed with cus_ (e.g. cus_abc123). This follows the same ID convention used by Stripe, making it straightforward to migrate or integrate existing tooling.

Endpoints

Create a Customer

POST /v1/customers

Creates a new customer record scoped to your project.

Request body (example)

{
  "email": "jane@example.com",
  "name": "Jane Smith"
}

Response (201 Created)

{
  "id": "cus_abc123",
  "email": "jane@example.com",
  "name": "Jane Smith",
  "created": 1710000000
}

Retrieve a Customer

GET /v1/customers/:id

Fetches a single customer by their cus_-prefixed ID.

Response (200 OK)

{
  "id": "cus_abc123",
  "email": "jane@example.com",
  "name": "Jane Smith",
  "created": 1710000000
}

Update a Customer

PATCH /v1/customers/:id

Updates one or more fields on an existing customer. Only the fields you include in the request body will be modified.

Request body (example)

{
  "email": "jane.new@example.com"
}

Response (200 OK)

{
  "id": "cus_abc123",
  "email": "jane.new@example.com",
  "name": "Jane Smith",
  "created": 1710000000
}

Delete a Customer

DELETE /v1/customers/:id

Permanently deletes a customer record. This is a hard delete designed to satisfy GDPR right-to-erasure requirements — the record cannot be recovered after deletion.

Response (200 OK)

{
  "id": "cus_abc123",
  "deleted": true
}

⚠️ Irreversible. Deleting a customer permanently removes their record. Ensure any associated payment methods, subscriptions, or invoices are handled before calling this endpoint.

List Customers

GET /v1/customers

Returns a paginated list of all customers belonging to your project.

Query parameters

Parameter	Type	Description
`limit`	integer	Number of results per page.
`starting_after`	string	Cursor for forward pagination — the `id` of the last customer from the previous page.

Response (200 OK)

{
  "object": "list",
  "data": [
    {
      "id": "cus_abc123",
      "email": "jane@example.com",
      "name": "Jane Smith",
      "created": 1710000000
    }
  ],
  "has_more": false
}

Project Scoping

All /v1/customers endpoints are scoped to your project automatically. Your API key identifies which project the request belongs to — you will never see or be able to modify customers from another project, even if you know their ID.

GDPR Compliance

The DELETE /v1/customers/:id endpoint performs a hard delete, permanently erasing the customer record from the database. Use this endpoint to fulfil subject erasure requests under GDPR Article 17.