Customers API

🤖 Explain with AI

Customers API is a tool that allows businesses to manage and retrieve customer information securely and efficiently. With this API, businesses can integrate customer management functionalities into their websites, applications, and other software solutions.

It supports features such as pagination, search by name or email, and detailed customer information including name, email, phone, photo, country, and custom metadata.

Get a list of all customers¶

Endpoint

GET /v1/customers/

This endpoint retrieves a paginated list of all customers for your account. By default, it returns 10 customers per page.

Query Parameters:

Parameter	Description	Type	Required
page	The page number to retrieve	integer	false
page_size	The number of customers to display per page (max 100)	integer	false
search	Search by first_name or email	string	false

Request (List All Customers):

curl -X GET 'http://127.0.0.1:8000/v1/customers/' \
     -u 'sk_test_51O62xYzAbcDef123:'

Request (With Pagination):

curl -X GET 'http://127.0.0.1:8000/v1/customers/?page=2&page_size=5' \
     -u 'sk_test_51O62xYzAbcDef123:'

Request (Search by Name or Email):

curl -X GET 'http://127.0.0.1:8000/v1/customers/?search=john' \
     -u 'sk_test_51O62xYzAbcDef123:'

Response (200 OK):

{
    "count": 38,
    "next": "http://127.0.0.1:8000/v1/customers/?page=3",
    "previous": "http://127.0.0.1:8000/v1/customers/",
    "results": [
        {
            "id": "217866f3-e1c2-465c-a242-1c04e30ba3fa",
            "developer": 2875,
            "first_name": "test",
            "last_name": "test",
            "email": "shadya.mora+401@4geeks.io",
            "phone": null,
            "photo": "https://seccdn.libravatar.org/avatar/d33b74df677623a5cc2bc9ea26d528fc?d=monsterid",
            "country": null,
            "metadata": null,
            "test": true
        },
        {
            "id": "3048a540-e825-4ccf-a693-fc4771c5f216",
            "developer": 2875,
            "first_name": "panchos",
            "last_name": "Cruz",
            "email": "marco.cruz+24@4geeks.io",
            "phone": null,
            "photo": "https://seccdn.libravatar.org/avatar/79a1c28ca1ef7df0e2b80c4eb4367cbf?d=monsterid",
            "country": "Costa Rica",
            "metadata": null,
            "test": true
        }
    ]
}

Get a specific customer¶

Endpoint

GET /v1/customers/{id}/

This endpoint retrieves the full details of a specific customer by their unique ID.

Path Parameters:

Parameter	Description	Type	Required
id	The unique identifier of a customer	string	true

Request:

curl -X GET 'http://127.0.0.1:8000/v1/customers/03124bfa-a8gd-4e63-823f-90540b9akcff/' \
     -u 'sk_test_51O62xYzAbcDef123:'

Response (200 OK):

{
    "id": "217866f3-e1c2-465c-a242-1c04e30ba3fa",
    "developer": 2875,
    "first_name": "test",
    "last_name": "test",
    "email": "shadya.mora+401@4geeks.io",
    "phone": "+50683236988",
    "photo": "https://seccdn.libravatar.org/avatar/d33b74df677623a5cc2bc9ea26d528fc?d=monsterid",
    "country": "Costa Rica",
    "metadata": null,
    "test": true
}

Search for customers¶

Endpoint

GET /v1/customers/?search={query}

This endpoint retrieves a list of customers matching a search query. Searches are performed on first_name and email fields.

Query Parameters:

Parameter	Description	Type	Required
search	The search query to match by name or email	string	true

Request:

curl -X GET 'http://127.0.0.1:8000/v1/customers/?search=alejandro' \
     -u 'sk_test_51O62xYzAbcDef123:'

Response (200 OK - Results Found):

[
    {
        "id": "004b75b1-64d9-42cc-8556-1b111611b67b",
        "developer_id": 2875,
        "first_name": "Shadya",
        "last_name": "Mora Sánchez",
        "email": "shadya.mora@4geeks.io",
        "phone": null,
        "photo": "https://storage.googleapis.com/g-payments.appspot.com/img/Shadya_Mora_test_1696356164.None",
        "country": "Costa Rica",
        "pay_providers": [
            {
                "id": "cus_NHLcuJNDnJDTnK",
                "name": "stripe"
            }
        ],
        "metadata": null,
        "created_on": "2023-02-26T06:56:07.152267Z",
        "test": false
    },
    {
        "id": "008ffa95-31be-41f8-b797-a4d75aafb9a5",
        "developer_id": 2875,
        "first_name": "Josito",
        "last_name": "Urenas",
        "email": "jose.urena+407@4geeks.io",
        "phone": "000000000",
        "photo": "https://storage.googleapis.com/g-payments.appspot.com/img/Josito_Urenas_test_1696279031.jpeg",
        "country": "Argentina",
        "pay_providers": [
            {
                "id": "cus_NWeHJ69zAJZx9Y",
                "name": "stripe"
            }
        ],
        "metadata": null,
        "created_on": "2023-03-14T16:46:08.241614Z",
        "test": true
    }
]

Response (404 Not Found - No Results):

{
    "message": {
        "code": 404,
        "title": "Customer not found",
        "content": "No customers found matching the query: 'customer_name'.",
        "type": "danger",
        "query": "customer_name"
    }
}

Address Management¶

Customers can have up to 3 addresses associated with their profile.

Error Handling¶

The API returns standard HTTP status codes to indicate the success or failure of a request. Below are common errors specific to customers:

400 Bad Request¶

Occurs when the request is malformed or missing required fields.

Scenarios:

Scenario	Error Message	Solution
Empty search query	`"The search query cannot be empty."`	Provide a non-empty search term
Missing required field	`"This field is required."`	Include all mandatory fields (first_name, last_name, email)
Invalid email format	`"Enter a valid email address."`	Check email format and try again

Example Error Response:

{
    "code": 400,
    "title": "Invalid request",
    "content": "The search query cannot be empty.",
    "type": "danger"
}

401 Unauthorized¶

Authentication failed. API Key is invalid, missing, or malformed.

Example:

{
    "detail": "Authentication credentials were not provided."
}

Solution:

Verify you included the -u 'sk_test_...: parameter or Authorization: Basic header
Ensure your API Key is correct and active
Test with Postman using Basic Auth

404 Not Found¶

The requested customer does not exist.

Example:

{
    "code": 404,
    "title": "Customer not found",
    "content": "The customer could not be found, please check the id.",
    "type": "danger"
}

Solution:

Verify the customer ID exists
Use the list endpoint to find the correct customer ID
Ensure the customer belongs to your developer account

406 Not Acceptable¶

Occurs when trying to perform an invalid action.

Example:

{
    "code": 406,
    "title": "Address registration failure",
    "content": "Customer already has 3 addresses registered.",
    "type": "danger"
}

Solution:

Delete an existing address before creating a new one
Maximum of 3 addresses per customer

Important Notes¶

!!! warning “Customer Information” - Email addresses must be unique within your account - Customers can have up to 3 addresses - Deleting a customer cannot be undone

!!! info “Photo Upload” - Photos can be uploaded as multipart form data - Supported formats: JPEG, PNG - Maximum file size: 5MB

!!! note “Metadata” - Metadata is stored as JSON and can contain custom key-value pairs - Use metadata to store application-specific customer information - Maximum metadata size: 10KB

!!! note “Test vs Production” - Use your Test Key (sk_test_...) for development and testing - Use your Live Key (sk_live_...) for real transactions - The system automatically detects the mode based on the API Key used

Best Practices¶

Validate email addresses - Ensure emails are unique and valid before creating
Use metadata wisely - Store relevant business data in metadata for easy filtering later
Keep addresses updated - Maintain current address information for accurate shipping
Handle pagination - Use page numbers and page_size for large customer lists
Search efficiently - Use search parameters to find customers quickly
Use default addresses - Mark preferred addresses as default for convenience

Troubleshooting¶

Problem: “Customer already has 3 addresses registered”¶

Cause: Attempting to add more than 3 addresses to a customer
Solution:

Delete an existing address first
Use the DELETE endpoint to remove an unused address
Then create the new address

Problem: “The customer could not be found”¶

Cause: Customer ID doesn’t exist or belongs to a different developer account
Solution:

Verify the customer ID using the list endpoint
Ensure you’re using the correct API Key
Check that the customer hasn’t been deleted

Problem: “Authentication credentials were not provided”¶

Cause: Missing or invalid API Key authentication
Solution:

Use -u 'sk_test_...: in cURL
Or use Authorization: Basic <base64_encoded_key> header
Verify your API Key is active

FAQ¶

Q: Can I have duplicate email addresses?
A: No, email addresses must be unique within your developer account. Attempting to create a duplicate will result in an error.

Q: What happens to payment history when I delete a customer?
A: The payment logs are preserved. You can still view transaction history even after customer deletion.

Q: How many addresses can a customer have?
A: Each customer can have up to 3 addresses. Delete an existing address before adding a new one if the limit is reached.

Q: Can I search by multiple fields?
A: The search parameter searches across first_name and email fields. To search by other fields, retrieve all customers and filter on your end.

Q: What data can I store in metadata?
A: Metadata accepts any valid JSON object (max 10KB). Common uses include customer type, registration source, loyalty points, etc.

Q: How often should I update customer information?
A: Update information whenever it changes. There are no rate limits on updates.

Login or signup into Console.
Check out the changelog.