Customer Management API
The Customer Management API allows you to create, retrieve, update, and delete customer records.
Methods
getCustomers
Retrieve a list of all customers with optional pagination and filtering.
const { getCustomers } = useEasy();
// Get all customers
const allCustomers = await getCustomers({
limit: 50,
offset: 0,
});
// Get specific customers by ID
const result = await getCustomers({
ids: ["cust_123", "cust_456"],
});
Parameters
params(optional)ids(string[], optional): Filter by specific customer IDslimit(number): Maximum number of customers to return (default: 10, max: 100)offset(number): Number of customers to skip for pagination
Returns
ApiResponse<CustomerData[]>;
Example
import { useEasy } from "@easylabs/react";
import { useState, useEffect } from "react";
function CustomerList() {
const { getCustomers } = useEasy();
const [customers, setCustomers] = useState([]);
const [loading, setLoading] = useState(true);
useEffect(() => {
const fetchCustomers = async () => {
try {
const result = await getCustomers({ limit: 50 });
setCustomers(result.data);
} catch (error) {
console.error("Failed to fetch customers:", error);
} finally {
setLoading(false);
}
};
fetchCustomers();
}, [getCustomers]);
if (loading) return <div>Loading...</div>;
return (
<ul>
{customers.map((customer) => (
<li key={customer.id}>
{customer.first_name} {customer.last_name} - {customer.email}
</li>
))}
</ul>
);
}
getCustomer
Retrieve a specific customer by their ID.
const { getCustomer } = useEasy();
const result = await getCustomer("cust_123");
Parameters
customerId(string, required): The ID of the customer to retrieve
Returns
ApiResponse<CustomerData>;
Example
import { useEasy } from "@easylabs/react";
import { useState, useEffect } from "react";
function CustomerProfile({ customerId }) {
const { getCustomer } = useEasy();
const [customer, setCustomer] = useState(null);
useEffect(() => {
const fetchCustomer = async () => {
const result = await getCustomer(customerId);
setCustomer(result.data);
};
fetchCustomer();
}, [customerId, getCustomer]);
if (!customer) return <div>Loading...</div>;
return (
<div>
<h2>
{customer.first_name} {customer.last_name}
</h2>
<p>Email: {customer.email}</p>
<p>Phone: {customer.phone}</p>
</div>
);
}
createCustomer
Create a new customer record.
const { createCustomer } = useEasy();
const result = await createCustomer({
email: "[email protected]",
first_name: "John",
last_name: "Doe",
phone: "+1234567890",
metadata: {
source: "web_signup",
},
});
Parameters
data(object, required)email(string, required): Customer email addressfirst_name(string, required): Customer first namelast_name(string, required): Customer last namephone(string, optional): Customer phone numbermetadata(object, optional): Additional custom data
Returns
ApiResponse<CustomerData>;
Example
import { useEasy } from "@easylabs/react";
import { useState } from "react";
function CustomerSignup() {
const { createCustomer } = useEasy();
const [formData, setFormData] = useState({
email: "",
first_name: "",
last_name: "",
phone: "",
});
const handleSubmit = async (e) => {
e.preventDefault();
try {
const result = await createCustomer(formData);
console.log("Customer created:", result.data);
} catch (error) {
console.error("Failed to create customer:", error);
}
};
return (
<form onSubmit={handleSubmit}>
<input
type="email"
placeholder="Email"
value={formData.email}
onChange={(e) => setFormData({ ...formData, email: e.target.value })}
required
/>
<input
type="text"
placeholder="First Name"
value={formData.first_name}
onChange={(e) =>
setFormData({ ...formData, first_name: e.target.value })
}
required
/>
<input
type="text"
placeholder="Last Name"
value={formData.last_name}
onChange={(e) =>
setFormData({ ...formData, last_name: e.target.value })
}
required
/>
<input
type="tel"
placeholder="Phone"
value={formData.phone}
onChange={(e) => setFormData({ ...formData, phone: e.target.value })}
/>
<button type="submit">Create Customer</button>
</form>
);
}
updateCustomer
Update an existing customer's information.
const { updateCustomer } = useEasy();
const result = await updateCustomer("cust_123", {
email: "[email protected]",
phone: "+0987654321",
});
Parameters
customerId(string, required): The ID of the customer to updatedata(object, required): Fields to updateemail(string, optional): New email addressfirst_name(string, optional): New first namelast_name(string, optional): New last namephone(string, optional): New phone numbermetadata(object, optional): Updated metadata
Returns
ApiResponse<CustomerData>;
Example
import { useEasy } from "@easylabs/react";
import { useState } from "react";
function CustomerEdit({ customerId, initialData }) {
const { updateCustomer } = useEasy();
const [formData, setFormData] = useState(initialData);
const handleSubmit = async (e) => {
e.preventDefault();
try {
const result = await updateCustomer(customerId, formData);
console.log("Customer updated:", result.data);
} catch (error) {
console.error("Failed to update customer:", error);
}
};
return (
<form onSubmit={handleSubmit}>
<input
type="email"
value={formData.email}
onChange={(e) => setFormData({ ...formData, email: e.target.value })}
/>
<input
type="text"
value={formData.first_name}
onChange={(e) =>
setFormData({ ...formData, first_name: e.target.value })
}
/>
<input
type="text"
value={formData.last_name}
onChange={(e) =>
setFormData({ ...formData, last_name: e.target.value })
}
/>
<button type="submit">Update Customer</button>
</form>
);
}
deleteCustomer
Delete a customer record.
const { deleteCustomer } = useEasy();
await deleteCustomer("cust_123");
Parameters
customerId(string, required): The ID of the customer to delete
Returns
ApiResponse<void>;
Example
import { useEasy } from "@easylabs/react";
function CustomerDeleteButton({ customerId }) {
const { deleteCustomer } = useEasy();
const handleDelete = async () => {
if (confirm("Are you sure you want to delete this customer?")) {
try {
await deleteCustomer(customerId);
console.log("Customer deleted successfully");
} catch (error) {
console.error("Failed to delete customer:", error);
}
}
};
return (
<button onClick={handleDelete} className="btn-danger">
Delete Customer
</button>
);
}
Type Definitions
CustomerData
interface CustomerData {
id: string;
email: string;
first_name: string;
last_name: string;
phone?: string;
created_at: string;
updated_at: string;
metadata?: Record<string, any>;
}
ApiResponse<T>
interface ApiResponse<T> {
data: T;
status: number;
message?: string;
}
import { useEasy } from "@easylabs/react";
import { useState, useEffect } from "react";
function CustomerList() {
const { getCustomers } = useEasy();
const [customers, setCustomers] = useState([]);
const [loading, setLoading] = useState(true);
useEffect(() => {
const fetchCustomers = async () => {
try {
const result = await getCustomers({ limit: 50 });
setCustomers(result.data);
} catch (error) {
console.error("Failed to fetch customers:", error);
} finally {
setLoading(false);
}
};
fetchCustomers();
}, [getCustomers]);
if (loading) return <div>Loading...</div>;
return (
<ul>
{customers.map((customer) => (
<li key={customer.id}>
{customer.first_name} {customer.last_name} - {customer.email}
</li>
))}
</ul>
);
}
getCustomer
Retrieve a specific customer by ID.
const { getCustomer } = useEasy();
const customer = await getCustomer("cust_123");
Parameters
customerId(string, required): The ID of the customer to retrieve
Returns
Customer;
Example
import { useEasy } from "@easylabs/react";
import { useState, useEffect } from "react";
function CustomerDetails({ customerId }) {
const { getCustomer } = useEasy();
const [customer, setCustomer] = useState(null);
useEffect(() => {
const fetchCustomer = async () => {
try {
const data = await getCustomer(customerId);
setCustomer(data);
} catch (error) {
console.error("Customer not found:", error);
}
};
fetchCustomer();
}, [customerId, getCustomer]);
if (!customer) return <div>Loading...</div>;
return (
<div>
<h2>
{customer.first_name} {customer.last_name}
</h2>
<p>Email: {customer.email}</p>
{customer.phone && <p>Phone: {customer.phone}</p>}
<p>Member since: {new Date(customer.created_at).toLocaleDateString()}</p>
</div>
);
}
createCustomer
Create a new customer.
const { createCustomer } = useEasy();
const customer = await createCustomer({
first_name: "John",
last_name: "Doe",
email: "[email protected]",
phone: "+1234567890",
metadata: {
source: "web",
},
});
Parameters
params(required)first_name(string, required): Customer's first namelast_name(string, required): Customer's last nameemail(string, required): Customer's email addressphone(string, optional): Customer's phone numbermetadata(object, optional): Additional custom data
Returns
Customer;
Example
import { useEasy } from "@easylabs/react";
import { useState } from "react";
function CreateCustomerForm() {
const { createCustomer } = useEasy();
const [formData, setFormData] = useState({
first_name: "",
last_name: "",
email: "",
phone: "",
});
const handleSubmit = async (e) => {
e.preventDefault();
try {
const customer = await createCustomer(formData);
console.log("Created customer:", customer.id);
// Reset form or navigate
} catch (error) {
console.error("Failed to create customer:", error);
}
};
return (
<form onSubmit={handleSubmit}>
<input
type="text"
placeholder="First Name"
value={formData.first_name}
onChange={(e) =>
setFormData({ ...formData, first_name: e.target.value })
}
required
/>
<input
type="text"
placeholder="Last Name"
value={formData.last_name}
onChange={(e) =>
setFormData({ ...formData, last_name: e.target.value })
}
required
/>
<input
type="email"
placeholder="Email"
value={formData.email}
onChange={(e) => setFormData({ ...formData, email: e.target.value })}
required
/>
<input
type="tel"
placeholder="Phone (optional)"
value={formData.phone}
onChange={(e) => setFormData({ ...formData, phone: e.target.value })}
/>
<button type="submit">Create Customer</button>
</form>
);
}
updateCustomer
Update an existing customer.
const { updateCustomer } = useEasy();
const customer = await updateCustomer("cust_123", {
email: "[email protected]",
metadata: {
updated: true,
},
});
Parameters
customerId(string, required): The ID of the customer to updateparams(required)first_name(string, optional): New first namelast_name(string, optional): New last nameemail(string, optional): New email addressphone(string, optional): New phone numbermetadata(object, optional): Updated metadata (replaces existing)
Returns
Customer;
Example
import { useEasy } from "@easylabs/react";
import { useState } from "react";
function EditCustomerForm({ customerId, initialData }) {
const { updateCustomer } = useEasy();
const [formData, setFormData] = useState(initialData);
const [saving, setSaving] = useState(false);
const handleSubmit = async (e) => {
e.preventDefault();
setSaving(true);
try {
const updated = await updateCustomer(customerId, formData);
console.log("Customer updated:", updated.id);
} catch (error) {
console.error("Failed to update:", error);
} finally {
setSaving(false);
}
};
return (
<form onSubmit={handleSubmit}>
<input
type="email"
value={formData.email}
onChange={(e) => setFormData({ ...formData, email: e.target.value })}
/>
<button type="submit" disabled={saving}>
{saving ? "Saving..." : "Save Changes"}
</button>
</form>
);
}
deleteCustomer
Delete a customer.
const { deleteCustomer } = useEasy();
await deleteCustomer("cust_123");
Parameters
customerId(string, required): The ID of the customer to delete
Returns
void
warning
Deleting a customer is permanent and cannot be undone. All associated payment instruments will also be removed.
Example
import { useEasy } from "@easylabs/react";
import { useState } from "react";
function DeleteCustomerButton({ customerId, onDeleted }) {
const { deleteCustomer } = useEasy();
const [confirming, setConfirming] = useState(false);
const handleDelete = async () => {
if (!confirming) {
setConfirming(true);
return;
}
try {
await deleteCustomer(customerId);
console.log("Customer deleted");
onDeleted();
} catch (error) {
console.error("Failed to delete:", error);
}
};
return (
<button onClick={handleDelete} style={{ color: "red" }}>
{confirming ? "Click again to confirm" : "Delete Customer"}
</button>
);
}
Type Definitions
Customer
interface Customer {
id: string;
first_name: string;
last_name: string;
email: string;
phone?: string;
metadata?: Record<string, unknown>;
created_at: string;
updated_at: string;
}
CreateCustomerParams
interface CreateCustomerParams {
first_name: string;
last_name: string;
email: string;
phone?: string;
metadata?: Record<string, unknown>;
}
UpdateCustomerParams
interface UpdateCustomerParams {
first_name?: string;
last_name?: string;
email?: string;
phone?: string;
metadata?: Record<string, unknown>;
}
ListParams
interface ListParams {
limit?: number;
offset?: number;
}
Error Handling
All methods can throw errors. Always wrap in try-catch:
try {
const customer = await createCustomer({ ... });
} catch (error) {
if (error.message.includes('email')) {
console.error('Invalid email address');
} else if (error.message.includes('duplicate')) {
console.error('Customer already exists');
} else {
console.error('Unknown error:', error);
}
}
Best Practices
- Validate email addresses before creating customers
- Use metadata for custom fields instead of extending the schema
- Handle pagination for large customer lists
- Cache customer data to reduce API calls
- Confirm deletions to prevent accidental data loss
Next Steps
This documentation is being migrated from the DEVELOPER_DOCS.md file.
For complete documentation, please see:
Coming soon to this documentation site!