Customers

Base URL

/api/v3/admin/customers/customer

Authentication

Required permissions for using this API:

• For read operations: customer:read
• For write operations: customer:update

List Customers

Retrieves a list of customers.

• URL: /
• Method: GET
• Query Parameters:
  • filter[name]: Filter by customer name
  • filter[email]: Filter by email address
  • filter[platform]: Filter by registration platform
  • filter[customerGroupId]: Filter by customer group ID
  • filter[trashed]: Filter archived customers
  • include: Used to include related data
    • customer_group: Customer group information
    • segments: Customer segments
    • representative: Representative information
    • group: Customer group information
  • append: Additional calculated fields
    • currentBalance: Current balance
    • pointsBalance: Points balance
    • balanceSum: Total balance sum
  • sort: Sort by field (prefix with - for descending)
    • Allowed fields: id, createdAt, loginAt
• Response: Paginated list of customers

Create Customer

Creates a new customer.

• URL: /
• Method: POST
• Headers:
  • Content-Type: application/json
• Permissions: customer:update
• Request Body:

{
    "name": "John",                        // Required
    "surname": "Doe",                      // Required
    "email": "john.doe@example.com",       // Required, must be unique
    "password": "securepass123",           // Required for new customers
    "company": "Example Corp",             // Optional
    "customerGroupId": 1,                  // Optional
    "mobilePhone": "+905321234567",        // Required
    "businessPhone": "+902121234567",      // Optional
    "countryCode": "TR",                   // Optional
    "cityCode": "34",                      // Optional
    "address": "Sample Address",           // Optional
    "status": 1,                          // Optional, default: 1
    "currency": "TRY",                    // Optional
    "notification": true,                 // Optional, email notifications
    "smsNotification": true,              // Optional, SMS notifications
    "phoneCallNotification": false        // Optional, phone call notifications
}

• Response: Created customer object

Get Single Customer

Retrieves a single customer by ID.

• URL: /{id}
• Method: GET
• Permissions: customer:read
• URL Parameters:
  • id: Customer ID
• Query Parameters:
  • include: Used to include related data
    • group: Customer group details
    • relation_metadata: Additional metadata
  • append: Additional calculated fields
    • currentBalance: Current balance
    • pointsBalance: Points balance
    • balanceSum: Total balance sum
• Response: Customer details

Update Customer

Updates an existing customer. Supports partial updates (only send fields that need to be updated).

• URL: /{id}
• Method: PUT
• Permissions: customer:update
• URL Parameters:
  • id: Customer ID
• Request Body:

{
    "name": "John",                        // Optional
    "surname": "Doe",                      // Optional
    "email": "john.doe@example.com",       // Optional, must be unique
    "company": "Updated Corp",             // Optional
    "customerGroupId": 2,                  // Optional
    "mobilePhone": "+905321234567",        // Optional
    "status": 1,                          // Optional
    "currency": "USD",                    // Optional
    "notification": true,                 // Optional
    "smsNotification": true,              // Optional
    "phoneCallNotification": false        // Optional
}

• Response: Updated customer object
• Note: Thanks to partial update support, you can send only the fields you want to update. Unspecified fields will retain their current values.

Delete Customer

Deletes a customer.

• URL: /{id}
• Method: DELETE
• URL Parameters:
  • id: Customer ID
• Permissions: Delete permission required
• Response: Deleted customer object

All Available Fields

Basic Information

Field	Type	Description	Required
name	string	First name	Yes
surname	string	Last name	Yes
email	string	Email address	Yes
password	string	Password (only for creation)	Yes*
company	string	Company name	No
idNumber	string	National ID number	No
gender	string	Gender	No

Contact Information

Field	Type	Description	Required
mobilePhone	string	Mobile phone number	Yes
businessPhone	string	Business phone number	No
address	string	Address	No
countryCode	string	Country code	No
cityCode	string	City code	No
districtCode	string	District code	No
provinceCode	string	Province code	No
townCode	string	Town code	No

Business Information

Field	Type	Description	Required
customerGroupId	integer	Customer group ID	No
taxOffice	string	Tax office	No
taxNumber	string	Tax number	No
wsAccountCode	string	Web service account code	No
representativeId	integer	Representative ID	No
posMerchantId	string	POS merchant ID	No

Notifications

Field	Type	Description	Required
notification	boolean	Email notification status	No
smsNotification	boolean	SMS notification status	No
phoneCallNotification	boolean	Phone call notification status	No

System Fields

Field	Type	Description	Required
status	integer	Account status	No
platform	string	Registration platform	No
currency	string	Preferred currency	No
segmentIds	array	Segment IDs	No
priceField	string	Price field	No
credibility	integer	Credibility score	No

Flags and Restrictions

Field	Type	Description	Required
risked	boolean	Risk status	No
riskedNote	string	Risk note	No
banned	boolean	Ban status	No
payAtDoor	boolean	Pay at door permission	No
cargoFree	boolean	Free cargo status	No

Error Codes

• 401: Authentication error
• 403: Permission error
• 404: Customer not found
• 422: Validation error
  • email.unique: Email address already exists
  • email.email: Invalid email format
  • mobilePhone.regex: Invalid phone number format
  • password.min: Password must be at least 8 characters
  • idNumber.unique: National ID number already exists

Changelog

2024-09

• Added support for metadata relations in customer includes
• Enhanced model relationships for metafields

2024-06

• Added password change requirement date functionality
• Implemented mandatory password change feature

2024-04

• Added new customer filtering capabilities
• Added support for filtering by web service code

2024-03

• Added sorting capability for registration date and last login date
• Implemented customer authorization definitions

2024-02

• Refactored total debt/credit/balance operations
• Fixed customer name-surname search functionality
• Added current balance and points balance information to customer service

2024-01

• Added customer group filter
• Fixed filter field in CustomerController

2023-12

• Added information fields to customer filtering

2023-10

• Implemented customer archive and recovery functionality
• Enhanced order product and customer filters

2023-09

• Added representative module
• Implemented representative structure in V5 panel

2023-08

• Added representative filter in customers page
• Implemented XML generation for API V3
• Enhanced customer group assignments

2023-07

• Implemented API V3 resources
• Added base collection functionality
• Fixed various API V3 issues

2023-06

• Initial release of Customer API V3
• Implemented customer group and segment functionality

---

This document was generated by AI. For support: api-support@tsoft.com.tr