Skip to main content

​
Customers API

Customers represent the people or businesses you bill. All endpoints require X-Api-Key.

​
Customer object

Customer list and retrieve endpoints preload subscriptions, paymentSources, and payments. 
{
  "id": "98e4fd8d-662a-4e21-9217-841a1748a129",
  "createdAt": "2026-07-02T09:05:00Z",
  "updatedAt": "2026-07-02T09:05:00Z",
  "name": "Ada Lovelace",
  "email": "customer@example.com",
  "phoneNumber": "+2348012345678",
  "code": "CUST_9XyZ456q",
  "externalRef": "user_123",
  "paymentSources": [],
  "subscriptions": [],
  "payments": []
}

​
POST /v1/customer/

Create a customer. 
curl -X POST https://nombasub.oluwadunsin.dev/v1/customer/ \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: sub_xxx" \
  -d '{
    "email": "customer@example.com",
    "name": "Ada Lovelace",
    "phoneNumber": "+2348012345678",
    "externalRef": "user_123"
  }'

​
Request body

FieldTypeRequiredDescription
emailstringYesCustomer email. Must be unique per tenant.
namestringNoCustomer display name.
phoneNumberstringNoCustomer phone number.
externalRefstringNoID from your own system.

​
Response

{
  "status": "success",
  "message": "Customer created successfully",
  "data": {
    "id": "98e4fd8d-662a-4e21-9217-841a1748a129",
    "createdAt": "2026-07-02T09:05:00Z",
    "updatedAt": "2026-07-02T09:05:00Z",
    "name": "Ada Lovelace",
    "email": "customer@example.com",
    "phoneNumber": "+2348012345678",
    "code": "CUST_9XyZ456q",
    "externalRef": "user_123"
  }
}

​
GET /v1/customer/

List customers. 
curl "https://nombasub.oluwadunsin.dev/v1/customer/?page=1&limit=10" \
  -H "X-Api-Key: sub_xxx"

​
Response

{
  "status": "success",
  "message": "Customers retrieved successfully",
  "data": {
    "data": [
      {
        "id": "98e4fd8d-662a-4e21-9217-841a1748a129",
        "createdAt": "2026-07-02T09:05:00Z",
        "updatedAt": "2026-07-02T09:05:00Z",
        "name": "Ada Lovelace",
        "email": "customer@example.com",
        "phoneNumber": "+2348012345678",
        "code": "CUST_9XyZ456q",
        "externalRef": "user_123",
        "paymentSources": [
          {
            "id": "4f7b8d02-82ca-4dbb-94d9-0c128e78420b",
            "createdAt": "2026-07-02T09:10:00Z",
            "updatedAt": "2026-07-02T09:10:00Z",
            "customerId": "98e4fd8d-662a-4e21-9217-841a1748a129",
            "type": "card",
            "card": {
              "type": "visa",
              "pan": "539983******1234",
              "last4Digits": "1234",
              "currency": "NGN",
              "authorizationToken": "tok_live_xxx",
              "expiryMonth": "12",
              "expiryYear": "2028"
            },
            "status": "active",
            "expirationMailSent": false
          }
        ],
        "subscriptions": [
          {
            "id": "1f3e2db6-12bb-4bd0-a910-86bd8f8edbee",
            "createdAt": "2026-07-02T09:12:00Z",
            "updatedAt": "2026-07-02T09:12:00Z",
            "customerId": "98e4fd8d-662a-4e21-9217-841a1748a129",
            "planId": "0a7c1f34-9b12-4d6c-8d45-4db61f463678",
            "code": "SUB_a1b2c3d4",
            "planVersionId": "af3c828b-37f8-494a-8ca2-80570d0a6739",
            "paymentSourceId": "4f7b8d02-82ca-4dbb-94d9-0c128e78420b",
            "paymentSourceType": "card",
            "interval": "monthly",
            "amount": 500000,
            "currency": "NGN",
            "intervalCount": 1,
            "trialPeriodDays": 0,
            "trialStartDate": null,
            "trialEndDate": null,
            "trialEndingSoonSent": false,
            "currentBillingCycleStart": "2026-07-02T09:12:00Z",
            "currentBillingCycleEnd": "2026-08-02T09:12:00Z",
            "cancelledAtEndOfBillingCycle": false,
            "startedAt": "2026-07-02T09:12:00Z",
            "cancelledAt": null,
            "completedAt": null,
            "pausedAt": null,
            "invoiceLimit": null,
            "invoiceCount": 1,
            "latestInvoiceId": "633d90ef-60e5-4777-a071-70cc5157276e",
            "status": "active"
          }
        ],
        "payments": [
          {
            "id": "11fbd53a-4933-449d-bab3-e55ecf69eb17",
            "createdAt": "2026-07-02T09:13:00Z",
            "updatedAt": "2026-07-02T09:13:00Z",
            "customerId": "98e4fd8d-662a-4e21-9217-841a1748a129",
            "subscriptionId": "1f3e2db6-12bb-4bd0-a910-86bd8f8edbee",
            "invoiceId": "633d90ef-60e5-4777-a071-70cc5157276e",
            "planId": "0a7c1f34-9b12-4d6c-8d45-4db61f463678",
            "planVersionId": "af3c828b-37f8-494a-8ca2-80570d0a6739",
            "paymentSourceId": "4f7b8d02-82ca-4dbb-94d9-0c128e78420b",
            "paymentSourceType": "card",
            "code": "PAY_h7k2Lm9q",
            "reference": "nombasub_l34cEf9012GHIjklmnOPqrsT",
            "idempotencyKey": null,
            "providerResponse": null,
            "providerTransactionId": null,
            "providerTransactionReference": null,
            "providerRefundTransactionId": null,
            "providerRefundTransactionReference": null,
            "amount": 500000,
            "currency": "NGN",
            "failureReason": null,
            "status": "SUCCESS",
            "attemptedAt": "2026-07-02T09:13:00Z",
            "completedAt": "2026-07-02T09:13:03Z",
            "failedAt": null
          }
        ]
      }
    ],
    "totalCount": 1,
    "page": 1,
    "limit": 10,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPreviousPage": false
  }
}

​
GET /v1/customer/:emailOrCode

Retrieve a customer by email or generated customer code. 
curl https://nombasub.oluwadunsin.dev/v1/customer/customer@example.com \
  -H "X-Api-Key: sub_xxx"

​
Response

{
  "status": "success",
  "message": "Customer retrieved successfully",
  "data": {
    "id": "98e4fd8d-662a-4e21-9217-841a1748a129",
    "createdAt": "2026-07-02T09:05:00Z",
    "updatedAt": "2026-07-02T09:05:00Z",
    "name": "Ada Lovelace",
    "email": "customer@example.com",
    "phoneNumber": "+2348012345678",
    "code": "CUST_9XyZ456q",
    "externalRef": "user_123",
    "paymentSources": [],
    "subscriptions": [],
    "payments": []
  }
}

​
PUT /v1/customer/:emailOrCode

Update customer details. 
curl -X PUT https://nombasub.oluwadunsin.dev/v1/customer/CUST_9XyZ456q \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: sub_xxx" \
  -d '{
    "name": "Ada L.",
    "phoneNumber": "+2348099999999",
    "externalRef": "user_123_updated"
  }'

​
Response

{
  "status": "success",
  "message": "Customer updated successfully",
  "data": {
    "id": "98e4fd8d-662a-4e21-9217-841a1748a129",
    "createdAt": "2026-07-02T09:05:00Z",
    "updatedAt": "2026-07-02T10:00:00Z",
    "name": "Ada L.",
    "email": "customer@example.com",
    "phoneNumber": "+2348099999999",
    "code": "CUST_9XyZ456q",
    "externalRef": "user_123_updated"
  }
}