Customers
By Maxim
By Maxim
Customers
Customers: the companies and people you sell your products to. Via the API you can create, edit and delete them, and get a list and a customer's details. Method paths are given relative to the base API URL; the rules common to all methods (authorization, request format, partial editing, pagination) are described in API Overview and Common Rules. Methods | Method | What it does | |---|---| | v1/customers/add | Creates a customer | | v1/customers/edit | Updates a customer | | v1/customers/delete | Deletes a customer | | v1/customers/get_list | Returns the company's customers | | v1/customers/get_entry | Returns a customer's details |
Creating a Customer
Creates a customer. v1/customers/add.php Parameters | Field | Type | Required | Description | |---|---|---|---| | name | string | Yes | Name | | email | string | No | Email | | phone | string | No | Phone | | address_legal | string | No | Legal address | | address_real | string | No | Delivery address | | agreement | string | No | Agreement | | manager_name | string | No | Manager | | manager_post | string | No | Manager's position | | notes | string | No | Notes | A customer can also be created together with a sale, see v1/orders/add. Example request { "name": "Furniture Yard", "email": "orders@furnitureyard.com", "phone": "+1 212 555-0123", "address_legal": "5 Forest St, New York", "address_real": "12 Warehouse Rd, New York", "agreement": "No. 15 of 10 Jan 2026", "manager_name": "Peter Johnson", "manager_post": "CEO" } Example response { "success": true, "customer_id": 512 } Errors | Error | Reason | |---|---| | No name in input | name is missing or null | | Name must not be empty | Empty name | | Name must be a string | name passed as an array or object |
Editing a Customer
Updates a customer. Only the fields you pass are changed, the rest stay as they were. v1/customers/edit.php Parameters | Field | Type | Required | Description | |---|---|---|---| | customer_id | int | Yes | Customer ID | | name | string | No | Name | | email | string | No | Email | | phone | string | No | Phone | | address_legal | string | No | Legal address | | address_real | string | No | Delivery address | | agreement | string | No | Agreement | | manager_name | string | No | Manager | | manager_post | string | No | Manager's position | | notes | string | No | Notes | To clear a field, pass an empty string. Passing null leaves the field unchanged, as if it were not sent. Example request { "customer_id": 512, "phone": "+1 212 555-0199", "address_real": "3 Factory St, New York" } Example response { "success": true } Errors | Error | Reason | |---|---| | No customer_id in input | customer_id is missing | | Customer not found or access denied | Customer not found or deleted | | Name must not be empty | An empty name was passed | | Name must be a string | name passed as an array or object |
Deleting a Customer
Deletes a customer. v1/customers/delete.php Parameters | Field | Type | Required | Description | |---|---|---|---| | customer_id | int | Yes | Customer ID | Example request { "customer_id": 512 } Example response { "success": true } Errors | Error | Reason | |---|---| | No customer_id in input | customer_id is missing | | Customer not found or access denied | Customer not found or already deleted |
Retrieving a List of Customers
Returns the company's customers, sorted by name. Deleted customers are not included. v1/customers/get_list.php Parameters | Field | Type | Required | Description | |---|---|---|---| | limit | int | No | Page size, from 1 to 1000 | | offset | int | No | How many records to skip | Without limit the whole list is returned. See Common Rules for pagination. Response An array customers with the customer's fields. The total field holds the total number of customers. | Field | Type | Description | |---|---|---| | id | int | Customer ID | | name | string | Name | | email | string | Email | | phone | string | Phone | | address_legal | string | Legal address | | address_real | string | Delivery address | | agreement | string | Agreement | | manager_name | string | Manager | | manager_post | string | Manager's position | | notes | string | Notes | Example request { "limit": 100, "offset": 0 } Example response { "success": true, "customers": [ { "id": 513, "name": "Anna Smith", "email": "anna@example.com", "phone": "+1 617 555-0134", "address_legal": "", "address_real": "20 Main St, Boston", "agreement": "", "manager_name": "", "manager_post": "", "notes": "" }, { "id": 512, "name": "Furniture Yard", "email": "orders@furnitureyard.com", "phone": "+1 212 555-0123", "address_legal": "5 Forest St, New York", "address_real": "12 Warehouse Rd, New York", "agreement": "No. 15 of 10 Jan 2026", "manager_name": "Peter Johnson", "manager_post": "CEO", "notes": "" } ], "total": 2 } Errors | Error | Reason | |---|---| | Invalid limit value. Must be between 1 and 1000 | Invalid limit | | Invalid offset value. Must be 0 or greater | Invalid offset | | Offset requires limit | offset passed without limit |
Retrieving a Customer
Returns a customer's details. v1/customers/get_entry.php Parameters | Field | Type | Required | Description | |---|---|---|---| | customer_id | int | Yes | Customer ID | A deleted customer is not returned. Response An object customer with the customer's fields. The fields from the response can be sent to v1/customers/edit unchanged, adding customer_id. | Field | Type | Description | |---|---|---| | id | int | Customer ID | | name | string | Name | | email | string | Email | | phone | string | Phone | | address_legal | string | Legal address | | address_real | string | Delivery address | | agreement | string | Agreement | | manager_name | string | Manager | | manager_post | string | Manager's position | | notes | string | Notes | Customer files are neither sent nor returned via the API. Example request { "customer_id": 512 } Example response { "success": true, "customer": { "id": 512, "name": "Furniture Yard", "email": "orders@furnitureyard.com", "phone": "+1 212 555-0123", "address_legal": "5 Forest St, New York", "address_real": "12 Warehouse Rd, New York", "agreement": "No. 15 of 10 Jan 2026", "manager_name": "Peter Johnson", "manager_post": "CEO", "notes": "" } } Errors | Error | Reason | |---|---| | No customer_id in input | customer_id is missing | | Customer not found or access denied | Customer not found or deleted |