Customers API The Customers API allows you to create and manage customer information. Storing customer data makes it easier to process payments and track customer activity.
The Customer Object { "id" : "cus_123456789" , "name" : "John Doe" , "email" : "[email protected] " , "phone" : "+237600000000" , "metadata" : {}, "created_at" : "2023-01-01T12:00:00Z" , "updated_at" : "2023-01-01T12:00:00Z" }
Customer Object Properties Unique identifier for the customer
Additional data attached to the customer
Timestamp when the customer was created
Timestamp when the customer was last updated
API Endpoints
List All Customers Retrieve a list of customers with pagination. Query Parameters Number of items per page (default: 30, max: 100)
Search by name, email, or phone
{ "code" : 200 , "status" : "OK" , "message" : "Customers retrieved" , "totals" : 50 , "last_page" : 2 , "current_page" : 1 , "selected" : 30 , "items" : [ { "id" : "cus_123456789" , "name" : "John Doe" , "email" : "[email protected] " , "phone" : "+237600000000" , "created_at" : "2023-01-01T12:00:00Z" }, // More customers... ] }
Create a Customer Create a new customer. Request Parameters Customer’s email address (required if phone is not provided)
Customer’s phone number (required if email is not provided)
Additional data to attach to the customer
Example Request { "name" : "John Doe" , "email" : "[email protected] " , "phone" : "+237600000000" , "metadata" : { "user_id" : "12345" , "company" : "Acme Inc." } }
{ "status" : "Created" , "message" : "Customer created" , "code" : 201 , "customer" : { "id" : "cus_123456789" , "name" : "John Doe" , "email" : "[email protected] " , "phone" : "+237600000000" , "metadata" : { "user_id" : "12345" , "company" : "Acme Inc." }, "created_at" : "2023-01-01T12:00:00Z" , "updated_at" : "2023-01-01T12:00:00Z" } }
Retrieve a Customer Retrieve details of a specific customer. Path Parameters ID of the customer to retrieve
{ "status" : "OK" , "message" : "Customer retrieved" , "code" : 200 , "customer" : { "id" : "cus_123456789" , "name" : "John Doe" , "email" : "[email protected] " , "phone" : "+237600000000" , "metadata" : { "user_id" : "12345" , "company" : "Acme Inc." }, "created_at" : "2023-01-01T12:00:00Z" , "updated_at" : "2023-01-01T12:00:00Z" } }
Update a Customer Update an existing customer. Path Parameters ID of the customer to update
Request Parameters Additional data to attach to the customer
Example Request { "name" : "John Smith" , "phone" : "+237600000001" , "metadata" : { "user_id" : "12345" , "company" : "Acme Corporation" } }
{ "status" : "OK" , "message" : "Customer updated" , "code" : 200 , "customer" : { "id" : "cus_123456789" , "name" : "John Smith" , "email" : "[email protected] " , "phone" : "+237600000001" , "metadata" : { "user_id" : "12345" , "company" : "Acme Corporation" }, "created_at" : "2023-01-01T12:00:00Z" , "updated_at" : "2023-01-02T10:00:00Z" } }
Delete a Customer Delete a customer. Path Parameters ID of the customer to delete
{ "status" : "OK" , "message" : "Customer deleted" , "code" : 200 }
Deleting a customer will not delete any associated payments or other records. It only removes the customer record itself.
List Customer Payments GET /customers/{id}/payments
Retrieve a list of payments made by a specific customer. Path Parameters Query Parameters Number of items per page (default: 30, max: 100)
{ "code" : 200 , "status" : "OK" , "message" : "Payments retrieved" , "totals" : 10 , "last_page" : 1 , "current_page" : 1 , "selected" : 10 , "items" : [ { "id" : "pay_123456789" , "reference" : "order_123" , "amount" : 5000 , "currency" : "XAF" , "status" : "complete" , "created_at" : "2023-01-01T12:00:00Z" }, // More payments... ] }
Best Practices
Collect Complete Information Collect as much customer information as possible to improve payment success rates and reduce fraud. Include both email and phone when available.
Use Metadata Effectively Use the metadata field to store additional information about your customers that’s relevant to your business. This can include user IDs from your system, subscription information, or other custom data.
Validate Customer Data Validate email addresses and phone numbers before sending them to the API to ensure they’re in the correct format. This helps prevent errors and improves the quality of your customer data.
Implement Customer Search Use the search parameter when listing customers to quickly find existing customers instead of creating duplicates. Search by email, phone, or name to find matching customers.
