Customers

Create and manage customer records for your business. Customers are linked to invoices — you need at least one customer before creating an invoice.

Endpoints

Method	Endpoint	Description
POST	`/v1/customers`	Create a new customer
GET	`/v1/customers`	List customers (paginated, searchable)
GET	`/v1/customers/{id}`	Get customer details
PATCH	`/v1/customers/{id}`	Update a customer
DELETE	`/v1/customers/{id}`	Delete a customer (soft delete)

🔑
All endpoints on this page require authentication. See Authentication for details.

Create a Customer

Add a new customer to your business. Customer names must be unique within a business.

curl -X POST https://e-invoicing.earnipay.com/v1/customers \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "businessId": "biz_xyz789",
    "name": "Zenith Enterprises",
    "email": "[email protected]",
    "phone": "+2348055551234",
    "TIN": "98765432-0001",
    "address": "8 Broad Street",
    "city": "Lagos",
    "state": "Lagos",
    "country": "Nigeria"
  }'

Parameter	Type	Required	Description
`businessId`	string	Yes	ID of the business this customer belongs to
`name`	string	Yes	Customer name (must be unique per business)
`email`	string	No	Customer email address
`phone`	string	No	Phone number (include country code)
`TIN`	string	No	Customer's Tax Identification Number
`address`	string	No	Street address
`city`	string	No	City
`state`	string	No	State
`country`	string	No	Country

{
  "statusCode": 201,
  "message": "Customer created successfully.",
  "data": {
    "id": "cus_def456",
    "businessId": "biz_xyz789",
    "name": "Zenith Enterprises",
    "email": "[email protected]",
    "phone": "+2348055551234",
    "TIN": "98765432-0001",
    "address": "8 Broad Street",
    "city": "Lagos",
    "state": "Lagos",
    "country": "Nigeria",
    "createdAt": "2026-03-13T11:00:00.000Z",
    "updatedAt": "2026-03-13T11:00:00.000Z"
  }
}

List Customers

Retrieve a paginated list of customers for your business. Supports search, sorting, and date filtering.

curl "https://e-invoicing.earnipay.com/v1/customers?businessId=biz_xyz789&page=1&limit=10&search=zenith" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Parameter	Type	Required	Description
`businessId`	string	Yes	Filter by business ID
`page`	integer	No	Page number (default: `1`)
`limit`	integer	No	Items per page (default: `10`)
`search`	string	No	Search by customer name or email
`sortBy`	string	No	Field to sort by (e.g., `name`, `createdAt`)
`sortOrder`	string	No	`asc` or `desc` (default: `desc`)
`startDate`	string	No	Filter customers created on or after this date (ISO 8601)
`endDate`	string	No	Filter customers created on or before this date (ISO 8601)

{
  "statusCode": 200,
  "message": "Customers retrieved successfully.",
  "data": {
    "items": [
      {
        "id": "cus_def456",
        "businessId": "biz_xyz789",
        "name": "Zenith Enterprises",
        "email": "[email protected]",
        "phone": "+2348055551234",
        "TIN": "98765432-0001",
        "city": "Lagos",
        "state": "Lagos",
        "country": "Nigeria",
        "createdAt": "2026-03-13T11:00:00.000Z"
      },
      {
        "id": "cus_ghi012",
        "businessId": "biz_xyz789",
        "name": "Pinnacle Solutions",
        "email": "[email protected]",
        "phone": "+2349088887777",
        "TIN": "11223344-0002",
        "city": "Abuja",
        "state": "FCT",
        "country": "Nigeria",
        "createdAt": "2026-03-10T08:15:00.000Z"
      }
    ],
    "meta": {
      "totalItems": 2,
      "itemCount": 2,
      "itemsPerPage": 10,
      "totalPages": 1,
      "currentPage": 1
    }
  }
}

Filtering by date range

Combine startDate and endDate to retrieve customers created within a specific window:

curl "https://e-invoicing.earnipay.com/v1/customers?businessId=biz_xyz789&startDate=2026-02-01T00:00:00.000Z&endDate=2026-02-28T23:59:59.000Z" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Both parameters are optional. Use startDate alone to get all customers from a date forward, or endDate alone to get all customers up to a date.

Get Customer Details

Retrieve the full details of a specific customer.

curl https://e-invoicing.earnipay.com/v1/customers/cus_def456 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "statusCode": 200,
  "message": "Customer retrieved successfully.",
  "data": {
    "id": "cus_def456",
    "businessId": "biz_xyz789",
    "name": "Zenith Enterprises",
    "email": "[email protected]",
    "phone": "+2348055551234",
    "TIN": "98765432-0001",
    "address": "8 Broad Street",
    "city": "Lagos",
    "state": "Lagos",
    "country": "Nigeria",
    "createdAt": "2026-03-13T11:00:00.000Z",
    "updatedAt": "2026-03-13T11:00:00.000Z"
  }
}

Update a Customer

Update one or more customer fields. Send only the fields you want to change.

curl -X PATCH https://e-invoicing.earnipay.com/v1/customers/cus_def456 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "address": "25 Adeola Odeku Street"
  }'

{
  "statusCode": 200,
  "message": "Customer updated successfully.",
  "data": {
    "id": "cus_def456",
    "businessId": "biz_xyz789",
    "name": "Zenith Enterprises",
    "email": "[email protected]",
    "phone": "+2348055551234",
    "TIN": "98765432-0001",
    "address": "25 Adeola Odeku Street",
    "city": "Lagos",
    "state": "Lagos",
    "country": "Nigeria",
    "createdAt": "2026-03-13T11:00:00.000Z",
    "updatedAt": "2026-03-13T15:30:00.000Z"
  }
}

Delete a Customer

Soft-delete a customer. The record is preserved for historical invoices but no longer appears in list queries or can be assigned to new invoices.

curl -X DELETE https://e-invoicing.earnipay.com/v1/customers/cus_def456 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "statusCode": 200,
  "message": "Customer deleted successfully."
}

⚠️
Deleting a customer is a soft delete. Existing invoices that reference this customer remain intact, but you cannot assign this customer to new invoices.

Error Handling

Status Code	Error	Description
`400`	Bad Request	Missing required fields or invalid parameters
`401`	Unauthorized	Missing or expired access token
`403`	Forbidden	You don't have permission for this business
`404`	Not Found	Customer ID doesn't exist or was deleted
`409`	Conflict	A customer with this name already exists in the business

{
  "statusCode": 409,
  "message": "A customer with the name 'Zenith Enterprises' already exists in this business.",
  "error": "Conflict"
}