Skip to main content
Use these endpoints to create and manage subscription customers on your account. A customer record stores the billing contact information needed for card-based recurring payments. You must create a customer before you can create a subscription for them. Base URL: https://app.kulmipay.com/api/v1/subscriptions/customers/ The POST endpoint performs an upsert: if a customer with the given email already exists on your account, the request updates their record instead of creating a new one. This makes it safe to call on every checkout without checking for duplicates first.

​
Create or update a customer

POST /api/v1/subscriptions/customers/

​
Request parameters

​
email
string
required
The customer’s email address. This is the unique key — if a customer with this email already exists on your account, the request will update their record.
​
first_name
string
required
Customer’s first name. Alphanumeric characters only.
​
last_name
string
required
Customer’s last name. Alphanumeric characters only.
​
phone_number
string
Customer’s phone number in international format, for example 254712345678.
​
reference
string
Your internal reference ID for this customer, up to 45 characters. Useful for linking the Kulmi Pay customer record to your own database.
​
address
string
Street address for billing, up to 50 characters. Required for card payments in some regions.
​
city
string
City for the billing address.
​
state
string
State or region for the billing address.
​
zipcode
string
Postal or ZIP code. Required for card billing when country is US, CA, or GB.
​
country
string
Two-letter ISO 3166-1 alpha-2 country code, for example KE or US.
cURL
curl --request POST \
  --url https://app.kulmipay.com/api/v1/subscriptions/customers/ \
  --header "Authorization: Bearer YOUR_SECRET_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "email": "jane@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "phone_number": "254712345678",
    "country": "KE"
  }'

​
List customers

GET /api/v1/subscriptions/customers/ Returns all customers associated with your account, ordered by creation date (newest first).

​
Retrieve a customer

GET /api/v1/subscriptions/customers/{customer_id}/ Returns a single customer record by their customer_id (alias ID).

​
Customer object

​
customer_id
string
The customer alias ID. Use this value as customer_id when creating a subscription.
​
email
string
The customer’s email address.
​
first_name
string
Customer’s first name.
​
last_name
string
Customer’s last name.
​
phone_number
string
Customer’s phone number.
​
reference
string
Your internal reference ID for this customer.
​
address
string
Street address on file.
​
city
string
City on file.
​
state
string
State or region on file.
​
zipcode
string
Postal code on file.
​
country
string
Two-letter country code on file.
​
created_at
string
ISO 8601 timestamp of when the customer was created.
​
updated_at
string
ISO 8601 timestamp of the last update to this customer record.

​
Example response

{
  "customer_id": "cus_xyz789",
  "email": "jane@example.com",
  "first_name": "Jane",
  "last_name": "Doe",
  "phone_number": "254712345678",
  "reference": "user_8821",
  "address": "123 Main Street",
  "city": "Nairobi",
  "state": "Nairobi",
  "zipcode": null,
  "country": "KE",
  "created_at": "2024-03-15T10:00:00Z",
  "updated_at": "2024-04-10T14:22:00Z"
}