Customers API

Customer management endpoints.

Customers API

The Customers API provides endpoints for managing customer information, billing addresses, order history, and customer relationship management.

Endpoints

GET /api/customers

Retrieve customers.

Query Parameters:

  • is_active (boolean): Filter by active status
  • search (string): Search by name or email
  • page (number): Page number
  • limit (number): Items per page

Response:

{
  "data": [
    {
      "id": "cust_456",
      "name": "Customer XYZ",
      "email": "orders@customerxyz.com",
      "phone": "+1-555-0456",
      "website": "https://customerxyz.com",
      "billing_address": {
        "line1": "456 Customer Blvd",
        "line2": "Floor 3",
        "city": "Customer City",
        "state": "NY",
        "postal_code": "10001",
        "country": "US"
      },
      "shipping_address": {
        "line1": "456 Customer Blvd",
        "city": "Customer City",
        "state": "NY",
        "postal_code": "10001",
        "country": "US"
      },
      "payment_terms": "net_15",
      "credit_limit": 10000.00,
      "current_balance": 2500.00,
      "customer_since": "2023-06-15T00:00:00Z",
      "is_active": true,
      "created_at": "2023-06-15T00:00:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "total": 150,
    "page": 1,
    "limit": 20,
    "hasMore": true
  }
}

GET /api/customers/:id

Retrieve a specific customer by ID.

Response:

{
  "data": {
    "id": "cust_456",
    "name": "Customer XYZ",
    "email": "orders@customerxyz.com",
    "phone": "+1-555-0456",
    "fax": "+1-555-0457",
    "website": "https://customerxyz.com",
    "tax_id": "98-7654321",
    "billing_address": {
      "line1": "456 Customer Blvd",
      "line2": "Floor 3",
      "city": "Customer City",
      "state": "NY",
      "postal_code": "10001",
      "country": "US"
    },
    "shipping_address": {
      "line1": "456 Customer Blvd",
      "city": "Customer City",
      "state": "NY",
      "postal_code": "10001",
      "country": "US"
    },
    "contacts": [
      {
        "id": "cont_101",
        "name": "Alice Johnson",
        "title": "Procurement Manager",
        "email": "alice.johnson@customerxyz.com",
        "phone": "+1-555-0458",
        "is_primary": true
      }
    ],
    "payment_terms": "net_15",
    "currency": "USD",
    "credit_limit": 10000.00,
    "current_balance": 2500.00,
    "discount_rate": 5.0,
    "preferred_shipping": "UPS_GROUND",
    "customer_since": "2023-06-15T00:00:00Z",
    "lifetime_value": 45000.00,
    "total_orders": 75,
    "is_active": true,
    "notes": "High-value customer with consistent orders",
    "created_at": "2023-06-15T00:00:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

POST /api/customers

Create a new customer.

Request Body:

{
  "name": "New Customer Corp",
  "email": "orders@newcustomer.com",
  "phone": "+1-555-0999",
  "website": "https://newcustomer.com",
  "tax_id": "12-9876543",
  "billing_address": {
    "line1": "123 New Customer St",
    "city": "Business City",
    "state": "CA",
    "postal_code": "90210",
    "country": "US"
  },
  "shipping_address": {
    "line1": "456 Warehouse Ave",
    "city": "Distribution City",
    "state": "CA",
    "postal_code": "90211",
    "country": "US"
  },
  "contacts": [
    {
      "name": "Bob Wilson",
      "title": "Operations Manager",
      "email": "bob.wilson@newcustomer.com",
      "phone": "+1-555-1000",
      "is_primary": true
    }
  ],
  "payment_terms": "net_30",
  "currency": "USD",
  "credit_limit": 5000.00,
  "discount_rate": 2.5,
  "preferred_shipping": "FEDEX_GROUND"
}

Response:

{
  "data": {
    "id": "cust_457",
    "name": "New Customer Corp",
    "email": "orders@newcustomer.com",
    "phone": "+1-555-0999",
    "billing_address": {
      "line1": "123 New Customer St",
      "city": "Business City",
      "state": "CA",
      "postal_code": "90210",
      "country": "US"
    },
    "contacts": [
      {
        "id": "cont_102",
        "name": "Bob Wilson",
        "title": "Operations Manager",
        "email": "bob.wilson@newcustomer.com",
        "phone": "+1-555-1000",
        "is_primary": true
      }
    ],
    "payment_terms": "net_30",
    "currency": "USD",
    "credit_limit": 5000.00,
    "current_balance": 0.00,
    "discount_rate": 2.5,
    "customer_since": "2024-01-15T21:30:00Z",
    "is_active": true,
    "created_at": "2024-01-15T21:30:00Z",
    "updated_at": "2024-01-15T21:30:00Z"
  }
}

PUT /api/customers/:id

Update an existing customer.

Request Body:

{
  "name": "Updated Customer Name",
  "email": "new.orders@customer.com",
  "credit_limit": 15000.00,
  "discount_rate": 7.5,
  "is_active": true
}

Response:

{
  "data": {
    "id": "cust_456",
    "name": "Updated Customer Name",
    "email": "new.orders@customer.com",
    "credit_limit": 15000.00,
    "discount_rate": 7.5,
    "updated_at": "2024-01-15T22:00:00Z"
  }
}

GET /api/customers/:id/orders

Get sales orders for a specific customer.

Query Parameters:

  • status (string): Filter by order status
  • date_from (string): Start date
  • date_to (string): End date
  • page (number): Page number
  • limit (number): Items per page

Response:

{
  "data": [
    {
      "id": "so_123",
      "order_number": "SO-2024-001",
      "status": "delivered",
      "order_date": "2024-01-15T00:00:00Z",
      "ship_date": "2024-01-16T00:00:00Z",
      "delivery_date": "2024-01-18T00:00:00Z",
      "total_amount": 299.95,
      "items_count": 3,
      "shipping_address": {
        "line1": "456 Customer Blvd",
        "city": "Customer City",
        "state": "NY",
        "postal_code": "10001"
      }
    }
  ],
  "meta": {
    "total": 75,
    "page": 1,
    "limit": 20,
    "hasMore": true
  }
}

GET /api/customers/:id/analytics

Get customer analytics and insights.

Query Parameters:

  • period (string): Time period (30d, 90d, 1y, all)

Response:

{
  "data": {
    "customer": {
      "id": "cust_456",
      "name": "Customer XYZ"
    },
    "overview": {
      "lifetime_value": 45000.00,
      "total_orders": 75,
      "avg_order_value": 600.00,
      "last_order_date": "2024-01-15T00:00:00Z",
      "customer_since": "2023-06-15T00:00:00Z",
      "days_since_last_order": 5
    },
    "financial_summary": {
      "total_revenue": 45000.00,
      "current_balance": 2500.00,
      "credit_limit": 10000.00,
      "credit_utilization": 25.0,
      "avg_payment_days": 12
    },
    "order_history": [
      {
        "month": "2024-01",
        "orders": 8,
        "revenue": 4800.00,
        "avg_order_value": 600.00
      },
      {
        "month": "2023-12",
        "orders": 6,
        "revenue": 3600.00,
        "avg_order_value": 600.00
      }
    ],
    "top_products": [
      {
        "product_id": "prod_123",
        "product_name": "Smart Widget",
        "quantity_ordered": 150,
        "revenue": 7500.00
      }
    ],
    "customer_segment": "high_value",
    "risk_score": "low"
  }
}

POST /api/customers/:id/contacts

Add a contact to a customer.

Request Body:

{
  "name": "Sarah Davis",
  "title": "Finance Manager",
  "email": "sarah.davis@customer.com",
  "phone": "+1-555-1100",
  "is_primary": false
}

Response:

{
  "data": {
    "id": "cont_103",
    "name": "Sarah Davis",
    "title": "Finance Manager",
    "email": "sarah.davis@customer.com",
    "phone": "+1-555-1100",
    "is_primary": false,
    "customer_id": "cust_456",
    "created_at": "2024-01-15T22:30:00Z"
  }
}

PUT /api/customers/:id/contacts/:contact_id

Update a customer contact.

Request Body:

{
  "title": "Senior Finance Manager",
  "phone": "+1-555-1101",
  "is_primary": true
}

DELETE /api/customers/:id/contacts/:contact_id

Remove a contact from a customer.

Response:

{
  "data": {
    "message": "Contact successfully removed"
  }
}

POST /api/customers/:id/credit-check

Perform a credit check for a customer.

Response:

{
  "data": {
    "customer_id": "cust_456",
    "credit_score": 750,
    "credit_rating": "excellent",
    "recommended_credit_limit": 15000.00,
    "current_credit_limit": 10000.00,
    "risk_assessment": "low",
    "last_checked": "2024-01-15T23:00:00Z"
  }
}