Customers

Overview

The Customer endpoints allow you to create customer profiles and retrieve customer details along with their paid invoices.

Create Customer

Create a new customer in your account.

Endpoint

POST /api/v2/customer

Request Headers

Content-Type: application/json

Request Body

Field	Type	Required	Description
`api_key`	string	Yes	Your API key for authentication
`name`	string	Yes	Customer's full name
`email`	string	Yes	Customer's email address (must be valid format)
`group`	string	No	Customer group/segment
`preferred_currency`	string	No	Preferred currency code (default: USD)
`address_line1`	string	No	Street address
`address_line2`	string	No	Apartment, suite, etc.
`city`	string	No	City
`state`	string	No	State/Province
`zip`	string	No	ZIP/Postal code
`country`	string	No	Country

Example Request

curl -X POST https://app.safepays.com/api/v2/customer \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "your_api_key_here",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "group": "Premium Customers",
    "preferred_currency": "USD",
    "address_line1": "123 Main Street",
    "address_line2": "Apt 4B",
    "city": "New York",
    "state": "NY",
    "zip": "10001",
    "country": "USA"
  }'

const response = await fetch('https://app.safepays.com/api/v2/customer', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    api_key: 'your_api_key_here',
    name: 'John Doe',
    email: 'john.doe@example.com',
    group: 'Premium Customers',
    preferred_currency: 'USD',
    address_line1: '123 Main Street',
    address_line2: 'Apt 4B',
    city: 'New York',
    state: 'NY',
    zip: '10001',
    country: 'USA'
  })
});

const result = await response.json();
console.log('Customer ID:', result.customer.id);

import requests
import json

url = 'https://app.safepays.com/api/v2/customer'
headers = {'Content-Type': 'application/json'}
data = {
    'api_key': 'your_api_key_here',
    'name': 'John Doe',
    'email': 'john.doe@example.com',
    'group': 'Premium Customers',
    'preferred_currency': 'USD',
    'address_line1': '123 Main Street',
    'address_line2': 'Apt 4B',
    'city': 'New York',
    'state': 'NY',
    'zip': '10001',
    'country': 'USA'
}

response = requests.post(url, headers=headers, data=json.dumps(data))
result = response.json()
print(f"Customer ID: {result['customer']['id']}")

Success Response

Status Code: 201 Created

{
  "status": "success",
  "message": "Customer created successfully",
  "customer": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "group": "Premium Customers",
    "preferred_currency": "USD",
    "address_line1": "123 Main Street",
    "address_line2": "Apt 4B",
    "city": "New York",
    "state": "NY",
    "zip": "10001",
    "country": "USA",
    "created_on": "2024-01-15 10:30:00"
  }
}

Error Responses

400 Bad Request — Missing required fields or invalid email format

{
  "error": "name and email are required"
}

401 Unauthorized — Invalid API key

{
  "error": "Invalid API Key"
}

409 Conflict — Customer with this email already exists

{
  "error": "Customer with this email already exists"
}

Email addresses are unique per account. If a customer with the provided email already exists, you will receive a 409 error.

Get Customer Details

Retrieve customer information along with all their paid invoices.

Endpoint

GET /api/v2/customer/{customer_id}?api_key=your_api_key_here

Path Parameters

Parameter	Type	Required	Description
`customer_id`	string	Yes	The unique customer ID (UUID)

Query Parameters

Parameter	Type	Required	Description
`api_key`	string	Yes	Your API key for authentication

Example Request

curl -X GET "https://app.safepays.com/api/v2/customer/550e8400-e29b-41d4-a716-446655440000?api_key=your_api_key_here"

const customerId = '550e8400-e29b-41d4-a716-446655440000';
const apiKey = 'your_api_key_here';

const response = await fetch(
  `https://app.safepays.com/api/v2/customer/${customerId}?api_key=${apiKey}`
);

const result = await response.json();
console.log(result);

import requests

customer_id = '550e8400-e29b-41d4-a716-446655440000'
api_key = 'your_api_key_here'
url = f'https://app.safepays.com/api/v2/customer/{customer_id}?api_key={api_key}'

response = requests.get(url)
result = response.json()
print(result)

Success Response

Status Code: 200 OK

{
  "status": "success",
  "customer": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "group": "Premium Customers",
    "preferred_currency": "USD",
    "address_line1": "123 Main Street",
    "address_line2": "Apt 4B",
    "city": "New York",
    "state": "NY",
    "zip": "10001",
    "country": "USA",
    "created_on": "2024-01-10 10:30:00"
  },
  "customer_url": "https://app.safepays.com/dashboard/customer/550e8400-e29b-41d4-a716-446655440000",
  "paid_invoices": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "amount": 125.00,
      "currency": "USD",
      "email": "john.doe@example.com",
      "provider": "card",
      "status": "Paid",
      "created_on": "15 Jan, 2024",
      "paid_on": "15 Jan, 2024",
      "payment_link": "https://app.safepays.com/pay/660e8400-e29b-41d4-a716-446655440001",
      "items": [
        {
          "name": "Product A",
          "qty": 2,
          "price": 50.00
        }
      ],
      "due_date": "2024-12-31",
      "customer_id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "total_paid_count": 1,
  "total_paid_amount": {
    "USD": 125.00
  }
}

Response Fields

Field	Type	Description
`customer`	object	Customer profile information
`customer_url`	string	Direct URL to view customer in the SafePays dashboard
`paid_invoices`	array	List of all paid invoices (sorted by payment date, newest first)
`total_paid_count`	integer	Total number of paid invoices
`total_paid_amount`	object	Total amounts by currency (currency codes as keys, totals as values)

Error Responses

400 Bad Request — Missing API key

{
  "error": "api_key parameter is required"
}

401 Unauthorized — Invalid API key

{
  "error": "Invalid API Key"
}

404 Not Found — Customer not found

{
  "error": "Customer not found"
}

Customers

On this page