Customers

Create, list, retrieve, and update customers.

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": "[e-mail]",
  "phoneNumber": "[phone]",
  "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": "[e-mail]",
    "name": "Ada Lovelace",
    "phoneNumber": "[phone]",
    "externalRef": "user_123"
  }'

Request body

Field	Type	Required	Description
email	string	Yes	Customer email. Must be unique per tenant.
name	string	No	Customer display name.
phoneNumber	string	No	Customer phone number.
externalRef	string	No	ID 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": "[e-mail]",
    "phoneNumber": "[phone]",
    "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": "[e-mail]",
        "phoneNumber": "[phone]",
        "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/[e-mail] \
  -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": "[e-mail]",
    "phoneNumber": "[phone]",
    "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": "[phone]",
    "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": "[e-mail]",
    "phoneNumber": "[phone]",
    "code": "CUST_9XyZ456q",
    "externalRef": "user_123_updated"
  }
}