Customer Management

Creation, Reading, Updating and Deleting of customers

Availability

This endpoint is available to both administrators and manufacturers.

Data Structures

Customer Record

{
    "id": 1234,
    "manufacturer_id": 7891,
    "name": "John Doe Kitchens",
    "email": "john@example.com",
    "phone": "52 1234 1234",
    "mobile": "0480123456",
    "cc_email": "harry@example.com",
    "price_adjustment": 0,
    "minimum_charge_amount": 30,
    "minimum_freight_amount": 0,
    "contact_address": {
        "street": [
            "123 Summer St"
        ],
        "suburb": "Boggy Creek",
        "state": "Victoria",
        "state_code": "VIC",
        "postcode": "3268",
        "country": "Australia",
        "country_code": "AU"
    },
    "delivery_address": [
        {
            "external_id": "Id-123",
            "name": "Shop",
            "street": [
                "123 Summer St"
            ],
            "suburb": "Boggy Creek",
            "state": "Victoria",
            "state_code": "VIC",
            "postcode": "3268",
            "country": "Australia",
            "country_code": "AU",
            "default": true
        }, {
            "external_id": null,
            "name": "Warehouse",
            "street": [
                "123 Back Road"
            ],
            "suburb": "Boggy Creek",
            "state": "Victoria",
            "state_code": "VIC",
            "postcode": "3268",
            "country": "Australia",
            "country_code": "AU",
            "default": false
        },
    ],
    "default_depot_id": 12,
    "external_id": "AW-1234",
    "settings": {
        "is_beta": true,
        "is_assembly_enabled": false,
        "is_suspended": false
    }
}

Field	Type	Mandatory	Description
`id`	ID	No*	Unique identifier
`manufacturer_id`	ID	No*	Identifier of the manufacturer the customer belongs to
`name`	string	Yes	Full name
`email`	email	Yes	String containing the customer's email address / login
`phone`	phone number	Yes	Primary phone number
`mobile`	phone number	No	Mobile number
`cc_email`	email	No	String containing an email to be CC'd on all emails to the customer
`price_adjustment`	percentage	No	Amount to adjust prices by for this customer
`minimum_charge_amount`	number	No	Minimum job cost
`minimum_freight_amount`	number	No	Minimum / default freight cost
`contact_address`	`Address`	Yes*	Primary contact / billing address
`delivery_address`	list of `DeliveryAddress`	No*	Delivery addresses. Note that only one will be flagged as "default"
`default_depot_id`	ID	No	Identifier of the customer's default depot - this is ignored if depots aren't enabled
`external_id`	string	No	String (or JSON blob) containing an ID from another system
`settings`	`CustomerSettings`	No	Customer settings

Mandatory fields are required to be present and non-blank on creation and cannot be cleared or unset when updating customers.

Notes:

id - this is not settable when creating and is ignored when updating, but will always be unique and present when retrieving customers.
manufacturer_id - this is not settable when creating and is ignored when updating, but will always be present when retrieving customers.
email - email addresses must be unique across the entire customer database as they're used for logging in.
contact_address and delivery_address - A contact address must be specified, however if a contact address isn't specified and delivery addresses are, the first delivery address will be used as the contact address

Address Record

{
    "street": [
        "123 Summer St"
    ],
    "suburb": "Boggy Creek",
    "state": "Victoria",
    "state_code": "VIC",
    "postcode": "3268",
    "country": "Australia",
    "country_code": "AU"
}

Field	Type	Mandatory	Description
`street`	List of strings	No	Address lines, the last one will usually be the actual street address
`suburb`	string	No	Suburb
`state`	string	Yes	State
`state_code`	string	Yes*	Short code for the state
`postcode`	string	No	Postcode
`country`	string	No*	Country
`country_code`	string	No*	Short code for the country

Note that items may be omitted, blank, empty or null depending on which parts are required to represent the customer's address in their country.

Specifying a state is mandatory and if the country is omitted, the country the state is in will be used. If a state and country are both specified, the state must be in that country. *_code fields can be specified instead of the state or country and if both are specified then they must refer to the same state or country.

DeliveryAddress Record

{
    "external_id": "Id-123",
    "name": "Shop",
    "street": [
        "123 Summer St"
    ],
    "suburb": "Boggy Creek",
    "state": "Victoria",
    "state_code": "VIC",
    "postcode": "3268",
    "country": "Australia",
    "country_code": "AU",
    "default": true
}

This is an Address record with two extra fields:

Field	Type	Mandatory	Description
`external_id`	string	No	Unique external id of the address
`name`	string	No	Name of the delivery address as set by the customer
`default`	boolean	No*	Whether the address is the default delivery address

Note:

The name may be omitted, blank or null if the customer has not specified a name for this address.
Only one delivery address will have default set to true.
If no delivery addresses have default set, the first one will be used as the default delivery address and have this set to true.

CustomerSettings Record

"settings": {
    "is_beta": true,
    "is_assembly_enabled": false,
    "is_suspended": false
}

Field	Type	Mandatory	Description
`is_beta`	boolean	No	Whether the customer can access beta features
`is_assembly_enabled`	boolean	No	Whether the customer is permitted to order assembled cabinets
`is_suspended`	boolean	No	Whether the customer is suspended

Creation

Customers are created by sending a POST request to /api/admin/customers.

Request

The request consists of a single Customer record only.

Note:

The id key will be silently ignored
The manufacturer_id key will be silently ignored if the API key used belongs to a manufacturer. In this case, the manufacturer_id will be set to the ID of the manufacturer the API key belongs to.
If password authentication is enabled on the manufacturer's portal, emails will be sent to validate the email and request that the customer set a password

Response

If the customer is successfully created, this will return a 200 status code and a response containing a single customer record. Note that the success response is identical to the response returned when reading or updating a customer.

If the customer cannot be created, this will return an appropriate status code and an error response explaining how the customer creation failed. Note that the list of error messages returned is not exhaustive and multiple attempts may be required to resolve all issues preventing the customer from being created.

Example Error Response

POST /api/admin/customers

{
    "name": "John Doe Kitchens",
    "email": "INVALID EMAIL ADDRESS",
    "phone": "52 1234 1234",
    "mobile": "0480123456",
    "cc_email": "harry@example.com",
    "price_adjustment": 0,
    "minimum_charge_amount": 30,
    "minimum_freight_amount": 0,
    "contact_address": {
        "street": [
            "123 Summer St"
        ],
        "suburb": "Boggy Creek",
        "state": "Victoria",
        "state_code": "VIC",
        "postcode": "3268",
        "country": "Australia",
        "country_code": "AU"
    },
    "delivery_address": [],
    "default_depot_id": 12,
    "external_id": "AW-1234",
    "settings": {
        "is_beta": true,
        "is_assembly_enabled": false,
        "is_suspended": false
    }
}

{
    "success": 0,
    "error": {
        "messages" : [
            "Invalid email address",
            "A delivery address must be specified"
        ]
    }
}

Example Success Response

POST /api/admin/customers

{
    "name": "John Doe Kitchens",
    "email": "john@example.com",
    "phone": "52 1234 1234",
    "mobile": "0480123456",
    "cc_email": "harry@example.com",
    "price_adjustment": 0,
    "minimum_charge_amount": 30,
    "minimum_freight_amount": 0,
    "contact_address": {
        "street": [
            "123 Summer St"
        ],
        "suburb": "Boggy Creek",
        "state": "Victoria",
        "state_code": "VIC",
        "postcode": "3268",
        "country": "Australia",
        "country_code": "AU"
    },
    "delivery_address": [
        {
            "name": "Shop",
            "street": [
                "123 Summer St"
            ],
            "suburb": "Boggy Creek",
            "state": "Victoria",
            "state_code": "VIC",
            "postcode": "3268",
            "country": "Australia",
            "country_code": "AU",
            "default": true
        }, {
            "name": "Warehouse",
            "street": [
                "123 Back Road"
            ],
            "suburb": "Boggy Creek",
            "state": "Victoria",
            "state_code": "VIC",
            "postcode": "3268",
            "country": "Australia",
            "country_code": "AU",
            "default": false
        },
    ],
    "default_depot_id": 12,
    "external_id": "AW-1234",
    "settings": {
        "is_beta": true,
        "is_assembly_enabled": false,
        "is_suspended": false
    }
}

{
    "success": 1,
    "customer": {
        "id": 1234,
        "manufacturer_id": 7891,
        "name": "John Doe Kitchens",
        "email": "john@example.com",
        "phone": "52 1234 1234",
        "mobile": "0480123456",
        "cc_email": "harry@example.com",
        "price_adjustment": 0,
        "minimum_charge_amount": 30,
        "minimum_freight_amount": 0,
        "contact_address": {
            "street": [
                "123 Summer St"
            ],
            "suburb": "Boggy Creek",
            "state": "Victoria",
            "state_code": "VIC",
            "postcode": "3268",
            "country": "Australia",
            "country_code": "AU"
        },
        "delivery_address": [
            {
                "name": "Shop",
                "street": [
                    "123 Summer St"
                ],
                "suburb": "Boggy Creek",
                "state": "Victoria",
                "state_code": "VIC",
                "postcode": "3268",
                "country": "Australia",
                "country_code": "AU",
                "default": true
            }, {
                "name": "Warehouse",
                "street": [
                    "123 Back Road"
                ],
                "suburb": "Boggy Creek",
                "state": "Victoria",
                "state_code": "VIC",
                "postcode": "3268",
                "country": "Australia",
                "country_code": "AU",
                "default": false
            },
        ],
        "default_depot_id": 12,
        "external_id": "AW-1234",
        "settings": {
            "is_beta": true,
            "is_assembly_enabled": false,
            "is_suspended": false
        }
    }
}

Listing

A list of customers is returned from GET requests to /api/admin/customers.

Features

This endpoint supports search criteria.

Search Criteria

The following fields are searchable, using one of the filter conditions documented.

Field	Description
id	The customer identifier
manufacturer_id	The associated manufacturer identifier
name	The customer name
email	The customer email address
phone	The customer telephone number
cc_email	The customer CC email address
price_adjustment	The discount price adjustment applied to each job
minimum_charge_amount	The minimum job cost for an order
minimum_freight_amount	The minimum freight cost for an order
contact_address.street	The contact address street
contact_address.suburb	The contact address suburb
contact_address.state	The contact address state
contact_address.postcode	The contact address postcode
settings.is_beta	Whether beta features are available
settings.is_assembly_enabled	Whether assembly is available
settings.is_suspended	Whether a customer is suspended
customer_labels	Tags/Labels associated with the customer

Response

This returns a paginated response containing a list of Customer records.

Example

GET /api/admin/customers?current_page=1&page_size=10

{
    "success": 1,
    "items": [
        {
            "id": 1234,
            "manufacturer_id": 7891,
            "name": "John Doe Kitchens",
            "email": "john@example.com",
            "phone": "52 1234 1234",
            "mobile": "0480123456",
            "cc_email": "harry@example.com",
            "price_adjustment": 0,
            "minimum_charge_amount": 30,
            "minimum_freight_amount": 0,
            "contact_address": {
                "street": [
                    "123 Summer St"
                ],
                "suburb": "Boggy Creek",
                "state": "Victoria",
                "state_code": "VIC",
                "postcode": "3268",
                "country": "Australia",
                "country_code": "AU"
            },
            "delivery_address": [
                {
                    "name": "Shop",
                    "street": [
                        "123 Summer St"
                    ],
                    "suburb": "Boggy Creek",
                    "state": "Victoria",
                    "state_code": "VIC",
                    "postcode": "3268",
                    "country": "Australia",
                    "country_code": "AU",
                    "default": true
                }, {
                    "name": "Warehouse",
                    "street": [
                        "123 Back Road"
                    ],
                    "suburb": "Boggy Creek",
                    "state": "Victoria",
                    "state_code": "VIC",
                    "postcode": "3268",
                    "country": "Australia",
                    "country_code": "AU",
                    "default": false
                },
            ],
            "default_depot_id": 12,
            "external_id": "AW-1234",
            "settings": {
                "is_beta": true,
                "is_assembly_enabled": false,
                "is_suspended": false
            }
        },
        {
            "id": 1368,
            "manufacturerId": 7891,
            "name": "Stevo's Kitchens",
            "email": "steve@example.com",
            "phone": "52 4321 4321",
            "mobile": "0480654321",
            "cc_email": "donna@example.com",
            "price_adjustment": 0,
            "minimum_charge_amount": 30,
            "minimum_freight_amount": 0,
            "contact_address": {
                "street": [
                    "844 Winter St"
                ],
                "suburb": "Barwon Heads",
                "state": "Victoria",
                "state_code": "VIC",
                "postcode": "3227",
                "country": "Australia",
                "country_code": "AU"
            },
            "delivery_address": [
                {
                    "name": "",
                    "street": [
                        "844 Winter St"
                    ],
                    "suburb": "Barwon Heads",
                    "state": "Victoria",
                    "state_code": "VIC",
                    "postcode": "3227",
                    "country": "Australia",
                    "country_code": "AU",
                    "default": true
                },
            ],
            "customer_labels": [
                "Retail",
                "Trade"
            ],
            "default_depot_id": 12,
            "external_id": "AW-2345",
            "settings": {
                "is_beta": true,
                "is_assembly_enabled": true,
                "is_suspended": true
            }
        }
    ],
    "pagination": {
        "current_page": 1,
        "page_count": 10,
        "page_size": 5,
        "total_count": 46
    }
}

Reading

A single customer record can be retrieved by sending a GET request to /api/admin/customers/<ID>.

Response

This returns a single Customer record if the customer exists or a 404 status code and error response if the customer cannot be found.

Note that the success response is identical to the response returned when creating or updating a customer.

Example

GET /api/admin/customers/1234

{
    "success": 1,
    "customer": {
        "id": 1234,
        "manufacturer_id": 7891,
        "name": "John Doe Kitchens",
        "email": "john@example.com",
        "phone": "52 1234 1234",
        "mobile": "0480123456",
        "cc_email": "harry@example.com",
        "price_adjustment": 0,
        "minimum_charge_amount": 30,
        "minimum_freight_amount": 0,
        "contact_address": {
            "street": [
                "123 Summer St"
            ],
            "suburb": "Boggy Creek",
            "state": "Victoria",
            "state_code": "VIC",
            "postcode": "3268",
            "country": "Australia",
            "country_code": "AU"
        },
        "delivery_address": [
            {
                "name": "Shop",
                "street": [
                    "123 Summer St"
                ],
                "suburb": "Boggy Creek",
                "state": "Victoria",
                "state_code": "VIC",
                "postcode": "3268",
                "country": "Australia",
                "country_code": "AU",
                "default": true
            }, {
                "name": "Warehouse",
                "street": [
                    "123 Back Road"
                ],
                "suburb": "Boggy Creek",
                "state": "Victoria",
                "state_code": "VIC",
                "postcode": "3268",
                "country": "Australia",
                "country_code": "AU",
                "default": false
            },
        ],
        "default_depot_id": 12,
        "external_id": "AW-1234",
        "settings": {
            "is_beta": true,
            "is_assembly_enabled": false,
            "is_suspended": false
        }
    }
}

Updating

Updating customer records is performed by sending a PUT request to /api/admin/customers/<ID>.

Request

The request consists of a single Customer record only.

Note:

The id key in the data sent as part of the request will be silently ignored and the ID in the URL used instead.
The manufacturer_id key will be silently ignored.

Response

If the customer is successfully updated, this will return a 200 status code and a response containing a single customer record. Note that the success response is identical to the response returned when creating or reading a customer.

If the customer cannot be updated, this will return an appropriate status code and an error response explaining how the customer updating failed. Note that the list of error messages returned is not exhaustive and multiple attempts may be required to resolve all issues preventing the customer from being updated.

Example Error Response

PUT /api/admin/customers/1234

{
    "name": "John Doe Kitchens",
    "email": "INVALID EMAIL ADDRESS",
    "phone": "52 1234 1234",
    "mobile": "0480123456",
    "cc_email": "harry@example.com",
    "price_adjustment": 0,
    "minimum_charge_amount": 30,
    "minimum_freight_amount": 0,
    "contact_address": {
        "street": [
            "123 Summer St"
        ],
        "suburb": "Boggy Creek",
        "state": "Victoria",
        "state_code": "VIC",
        "postcode": "3268",
        "country": "Australia",
        "country_code": "AU"
    },
    "delivery_address": [],
    "default_depot_id": 12,
    "external_id": "AW-1234",
    "settings": {
        "is_beta": true,
        "is_assembly_enabled": false,
        "is_suspended": false
    }
}

{
    "success": 0,
    "error": {
        "messages" : [
            "Invalid email address",
            "A delivery address must be specified"
        ]
    }
}

Example Success Response

PUT /api/admin/customers/1234

{
    "name": "John Doe Kitchens",
    "email": "john@example.com",
    "phone": "52 1234 1234",
    "mobile": "0480123456",
    "cc_email": "harry@example.com",
    "price_adjustment": 0,
    "minimum_charge_amount": 30,
    "minimum_freight_amount": 0,
    "contact_address": {
        "street": [
            "123 Summer St"
        ],
        "suburb": "Boggy Creek",
        "state": "Victoria",
        "state_code": "VIC",
        "postcode": "3268",
        "country": "Australia",
        "country_code": "AU"
    },
    "delivery_address": [
        {
            "name": "Shop",
            "street": [
                "123 Summer St"
            ],
            "suburb": "Boggy Creek",
            "state": "Victoria",
            "state_code": "VIC",
            "postcode": "3268",
            "country": "Australia",
            "country_code": "AU",
            "default": true
        }, {
            "name": "Warehouse",
            "street": [
                "123 Back Road"
            ],
            "suburb": "Boggy Creek",
            "state": "Victoria",
            "state_code": "VIC",
            "postcode": "3268",
            "country": "Australia",
            "country_code": "AU",
            "default": false
        },
    ],
    "default_depot_id": 12,
    "external_id": "AW-1234",
    "settings": {
        "is_beta": true,
        "is_assembly_enabled": false,
        "is_suspended": false
    }
}

{
    "success": 1,
    "customer": {
        "id": 1234,
        "manufacturer_id": 7891,
        "name": "John Doe Kitchens",
        "email": "john@example.com",
        "phone": "52 1234 1234",
        "mobile": "0480123456",
        "cc_email": "harry@example.com",
        "price_adjustment": 0,
        "minimum_charge_amount": 30,
        "minimum_freight_amount": 0,
        "contact_address": {
            "street": [
                "123 Summer St"
            ],
            "suburb": "Boggy Creek",
            "state": "Victoria",
            "state_code": "VIC",
            "postcode": "3268",
            "country": "Australia",
            "country_code": "AU"
        },
        "delivery_address": [
            {
                "name": "Shop",
                "street": [
                    "123 Summer St"
                ],
                "suburb": "Boggy Creek",
                "state": "Victoria",
                "state_code": "VIC",
                "postcode": "3268",
                "country": "Australia",
                "country_code": "AU",
                "default": true
            }, {
                "name": "Warehouse",
                "street": [
                    "123 Back Road"
                ],
                "suburb": "Boggy Creek",
                "state": "Victoria",
                "state_code": "VIC",
                "postcode": "3268",
                "country": "Australia",
                "country_code": "AU",
                "default": false
            },
        ],
        "default_depot_id": 12,
        "external_id": "AW-1234",
        "settings": {
            "is_beta": true,
            "is_assembly_enabled": false,
            "is_suspended": false
        }
    }
}

Deleting

Customers can be deleted by sending a DELETE request to /api/admin/customers/<ID>.

Response

If the customer is successfully deleted, this will return a 200 status code with an empty JSON response. If you require a copy of the deleted customer record, you are expected to send a GET request to retrieve the customer data before sending the DELETE request. Once the DELETE request has been processed, the customer and all associated data including job records will not be available.

If the customer cannot be deleted, this will return an appropriate status code and an error response explaining how the customer deletion failed. Note that the list of error messages returned is not exhaustive and multiple attempts might be required to resolve all issues preventing the customer from being deleted.

Example Error Response

DELETE /api/admin/customers/1234

{
    "success": 0,
    "error": {
        "messages" : [
            "Customer cannot be deleted"
        ]
    }
}

Example Success Response

DELETE /api/admin/customers/1234

{
    "success": 1
}