Customers API

Customers allow you to save payment information for repeat purchases, track payment history, and manage subscriptions.

The Customer Object

{
  "id": "cus_abc123def456",
  "object": "customer",
  "email": "customer@example.com",
  "name": "John Doe",
  "phone": "0241234567",
  "metadata": {
    "user_id": "123"
  },
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-01-15T10:00:00Z"
}

Attributes

Attribute	Type	Description
`id`	string	Unique identifier for the customer
`object`	string	Always `"customer"`
`email`	string	Customer's email address
`name`	string	Customer's full name
`phone`	string	Customer's phone number
`metadata`	object	Custom key-value pairs
`created_at`	string	ISO 8601 timestamp
`updated_at`	string	ISO 8601 timestamp

Create a Customer

Creates a new customer.

POST /v1/customers

Request Body

Parameter	Type	Required	Description
`email`	string	No	Customer's email address
`name`	string	No	Customer's full name
`phone`	string	No	Customer's phone number
`metadata`	object	No	Custom metadata

curl -X POST https://api.44.200.142.19.nip.io/v1/customers \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "customer@example.com",
    "name": "John Doe",
    "phone": "0241234567",
    "metadata": {
      "user_id": "123"
    }
  }'

const customer = await paygate.customers.create({
  email: 'customer@example.com',
  name: 'John Doe',
  phone: '0241234567',
  metadata: {
    user_id: '123'
  }
})

customer = client.customers.create(
    email='customer@example.com',
    name='John Doe',
    phone='0241234567',
    metadata={'user_id': '123'}
)

$customer = $paygate->customers->create([
    'email' => 'customer@example.com',
    'name' => 'John Doe',
    'phone' => '0241234567',
    'metadata' => ['user_id' => '123']
]);

Response

{
  "id": "cus_abc123def456",
  "object": "customer",
  "email": "customer@example.com",
  "name": "John Doe",
  "phone": "0241234567",
  "metadata": {
    "user_id": "123"
  },
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-01-15T10:00:00Z"
}

Retrieve a Customer

Retrieves a customer by ID.

GET /v1/customers/:id

curl https://api.44.200.142.19.nip.io/v1/customers/cus_abc123def456 \
  -H "Authorization: Bearer sk_test_..."

const customer = await paygate.customers.retrieve('cus_abc123def456')

customer = client.customers.retrieve('cus_abc123def456')

Update a Customer

Updates a customer's information.

PATCH /v1/customers/:id

Request Body

Parameter	Type	Description
`email`	string	Customer's email address
`name`	string	Customer's full name
`phone`	string	Customer's phone number
`metadata`	object	Custom metadata

curl -X PATCH https://api.44.200.142.19.nip.io/v1/customers/cus_abc123def456 \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Doe",
    "metadata": {
      "vip": "true"
    }
  }'

const customer = await paygate.customers.update('cus_abc123def456', {
  name: 'Jane Doe',
  metadata: { vip: 'true' }
})

customer = client.customers.update('cus_abc123def456',
    name='Jane Doe',
    metadata={'vip': 'true'}
)

Delete a Customer

Deletes a customer.

DELETE /v1/customers/:id

Deleting a customer will cancel all active subscriptions and remove payment history association.

curl -X DELETE https://api.44.200.142.19.nip.io/v1/customers/cus_abc123def456 \
  -H "Authorization: Bearer sk_test_..."

const deleted = await paygate.customers.delete('cus_abc123def456')

deleted = client.customers.delete('cus_abc123def456')

Response

{
  "id": "cus_abc123def456",
  "object": "customer",
  "deleted": true
}

List Customers

Returns a list of customers.

GET /v1/customers

Query Parameters

Parameter	Type	Description
`limit`	integer	Number of results (1-100, default 10)
`starting_after`	string	Cursor for pagination
`ending_before`	string	Cursor for pagination
`email`	string	Filter by email
`created[gte]`	string	Filter by creation date
`created[lte]`	string	Filter by creation date

curl "https://api.44.200.142.19.nip.io/v1/customers?limit=10" \
  -H "Authorization: Bearer sk_test_..."

const customers = await paygate.customers.list({
  limit: 10
})

// Iterate through all customers
for await (const customer of paygate.customers.list()) {
  console.log(customer.id)
}

customers = client.customers.list(limit=10)

# Iterate through all customers
for customer in client.customers.list():
    print(customer.id)

Response

{
  "object": "list",
  "data": [
    {
      "id": "cus_abc123def456",
      "object": "customer",
      "email": "customer@example.com",
      "name": "John Doe",
      ...
    }
  ],
  "has_more": true,
  "url": "/v1/customers"
}

List Customer Payments

Returns all payments for a customer.

GET /v1/customers/:id/payments

curl "https://api.44.200.142.19.nip.io/v1/customers/cus_abc123def456/payments" \
  -H "Authorization: Bearer sk_test_..."

const payments = await paygate.payments.list({
  customer: 'cus_abc123def456'
})

payments = client.payments.list(customer='cus_abc123def456')

List Customer Subscriptions

Returns all subscriptions for a customer.

GET /v1/customers/:id/subscriptions

curl "https://api.44.200.142.19.nip.io/v1/customers/cus_abc123def456/subscriptions" \
  -H "Authorization: Bearer sk_test_..."

const subscriptions = await paygate.subscriptions.list({
  customer: 'cus_abc123def456'
})

subscriptions = client.subscriptions.list(customer='cus_abc123def456')

Customers

On this page