Skip to main content
A Customer represents a business or individual that purchases your products or services. It allows you to track subscriptions, payments, invoices, and usage for a specific entity.

​
👤 Creating a Customer

You should create a Customer in Credibill when a user signs up for your application. This endpoint is used to register a new customer in the system. It is authenticated via an API Key passed as a Bearer Token in the Authorization header.
  • Endpoint: https://giant-goldfish-922.convex.site/api/v1/customers/create
  • Method: POST
  • Authentication: Authorization: Bearer <CREDIBILL_API_KEY>
Request Body Schema:
FieldTypeRequiredDescription
emailstringYesThe customer’s primary email address (must be unique).
first_namestringNoThe customer’s first name.
last_namestringNoThe customer’s last name.
phonestringNoThe customer’s phone number.
externalCustomerIdstringNoAn ID from your internal system.
metadataobjectNoArbitrary JSON data.

​
Example (React + TS)

// src/api/customers.ts

// --- Data Types for Customer Creation ---
export type CustomerData = {
email: string;
first_name?: string;
last_name?: string;
phone?: string;
externalCustomerId?: string;
metadata?: Record<string, any>;
type?: string;
status?: string;
};

export type CustomerCreationResponse = {
  success: boolean,
  customerId: string,
};

// Replace with your actual Convex URL
const CONVEX_URL = 'https://YOUR_CONVEX_URL.convex.site';
const ENDPOINT = '/api/v1/customers/create';

/\*\*

- Handles the HTTP POST request to create a new customer.
- @param data - The customer payload.
- @param apiKey - The Credibill API Key for Bearer authentication.
- @returns A promise resolving to the API response data.
  \*/
  export async function createCustomer(
  data: CustomerData,
  apiKey: string
  ): Promise<CustomerCreationResponse> {
  // 1. Validate API Key presence
  if (!apiKey) {
  throw new Error("API Key is required for authentication.");
  }

// 2. Fetch API Call
const response = await fetch(`${CREDIBILL_URL}${ENDPOINT}`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
// Mandatory authentication header
'Authorization': `Bearer ${apiKey}`,
},
body: JSON.stringify(data),
});

// 3. Handle API Response Errors
if (!response.ok) {
const errorBody = await response.json();
// Throw error to be caught by React Query's useMutation onError
throw new Error(errorBody.error || `HTTP error! Status: ${response.status}`);
}

// 4. Return successful response body
return response.json();
}

​
Response

When you create a customer, the API responds with a JSON object containing the success status and the unique customer ID. 
{
  "success": true,
  "customerId": "j97bp2fjzhbx59ayye52ag2gsd7ydw1c"
}

​
Getting Customer Details

Retrieve customer information by listing all customers for your app or fetching a specific customer by ID.
  • Endpoint: https://giant-goldfish-922.convex.site/api/customers
  • Method: GET
  • Authentication: Authorization: Bearer <CREDIBILL_API_KEY>

​
Query Parameters

ParameterTypeRequiredDescription
customerIdstringNoThe unique ID of the customer. If omitted, lists all customers.

​
Examples

// src/hooks/useGetCustomers.ts

import { useQuery, UseQueryOptions } from "@tanstack/react-query";

export type Customer = {
  _id: string,
  email: string,
  first_name?: string,
  last_name?: string,
  phone?: string,
  externalCustomerId?: string,
  metadata?: Record<string, any>,
  [key: string]: any,
};

export type GetCustomersResponse = {
  customers?: Customer[],
  customer?: Customer,
};

const useApiKey = () => {
// !! REPLACE THIS PLACEHOLDER !!
const apiKey = 'YOUR_CREDIBILL_API_KEY';
return apiKey;
};

const CREDIBILL_URL = 'https://giant-goldfish-922.convex.site';
const ENDPOINT = '/api/customers';

type UseGetCustomersOptions = Omit<UseQueryOptions<
GetCustomersResponse,
Error

> , 'queryFn' | 'queryKey'>;

/\*\*

- Custom React Query hook for fetching customer(s)
- @param customerId - (Optional) Fetch a specific customer by ID. If omitted, fetches all customers
- @param options - Optional configuration options for useQuery
- @returns The query object provided by TanStack Query
  \*/
  export const useGetCustomers = (
  customerId?: string,
  options?: UseGetCustomersOptions
  ) => {
  const apiKey = useApiKey();

return useQuery<GetCustomersResponse, Error>({
queryKey: ['customers', customerId],
queryFn: async () => {
if (!apiKey) {
throw new Error("API Key is required for authentication.");
}

      const url = new URL(`${CREDIBILL_URL}${ENDPOINT}`);
      if (customerId) {
        url.searchParams.append('customerId', customerId);
      }

      const response = await fetch(url.toString(), {
        method: 'GET',
        headers: {
          'Content-Type': 'application/json',
          'Authorization': `Bearer ${apiKey}`,
        },
      });

      if (!response.ok) {
        const errorBody = await response.json();
        throw new Error(errorBody.error || `HTTP error! Status: ${response.status}`);
      }

      return response.json();
    },
    ...options,

});
};

​
Response Examples

Get Single Customer: 
{
  "customer": {
    "_id": "j97bp2fjzhbx59ayye52ag2gsd7ydw1c",
    "email": "[email protected]",
    "first_name": "Jane",
    "last_name": "Doe",
    "phone": "+1234567890",
    "externalCustomerId": "app-user-12345",
    "metadata": {
      "plan": "premium",
      "signup_date": "2024-01-01"
    }
  }
}
List All Customers: 
{
  "customers": [
    {
      "_id": "j97bp2fjzhbx59ayye52ag2gsd7ydw1c",
      "email": "[email protected]",
      "first_name": "Jane",
      "last_name": "Doe",
      "metadata": {}
    },
    {
      "_id": "k89cq3gkzhiys60bzuf53bh3hte8zx2d",
      "email": "[email protected]",
      "first_name": "John",
      "last_name": "Smith",
      "metadata": {}
    }
  ]
}