Customers

Customers can be accessed through the API via the customers base URL:

$ curl https://app.handshake-app.com/api/v2/customers

• Supported list methods: GET POST
• Supported detail methods: GET PUT DELETE

Fields

customer.id (string)

The user-defined ID for this customer (users normally set this to the ID of this customer in their ERP or CRM system). This is not the same as the numeric objID which is set by the system. See the bulk import docs for more information.

customer.name (string)

customer.contact (string)

customer.email (string)

customer.billTo (readonly reference to Address)

The Address object for this customer's billing address.

• When doing a POST on a new customer, you must provide the details of the billTo address inline, even if this means simply posting an empty dictionary to create a blank billing address. Every customer must have a billTo even if all of its fields are blank.

• When doing a PUT on an existing customer, you cannot provide a different resource_uri for the billTo address to connect the customer to a different address resource. The billTo that is on the customer when it is created stays with it for its lifetime and this relationship cannot be broken.

customer.shipTos (collection of Address)

A (possibly empty) collection of Address objects that represent this customer's additional shipping addresses.

customer.creditCards (collection of CreditCard)

A (possibly empty) collection of CreditCard objects representing the credit cards that are attached to this customer.

customer.salesOrders (collection of SalesOrder)

A (possibly empty) collection of SalesOrder objects representing the orders that have been written for this customer. This will be returned with the oldest orders first.

customer.userGroup (reference to UserGroup)

The UserGroup representing the user group that this customer has been restricted to. This customer's orders will always be restricted to the same group.

A customer will always be in a user group. If you pass null for the userGroup when creating a new customer, it will be automatically linked to the master user group.

customer.customerGroup (reference to CustomerGroup)

A reference to the CustomerGroup that this customer is in, which will be one of the groups defined here.

customer.shippingMethod (string)

The default shipping method for this customer, as selected from the available choices.

customer.paymentTerms (string)

The default payment terms for this customer, as selected from the available choices.

customer.currency (readonly string)

The three-letter currency code (e.g. "USD", "GBP" etc) that applies to this customer.

The reason that this field is read-only is that it is actually derived from the customer group this customer belongs to, or the company itself if no customer groups are defined.

customer.locale (readonly string)

The locale code (e.g. "en_US", "fr_FR" or similar) that applies to this customer. This field is read-only for the same reason as currency above.

Filter Parameters

id (string)

Filters customers by an exact match against the user-defined id described above. When applying this filter you will get either 0 or 1 results.

# Filter for the customer with user-defined ID 'C1234'
$ curl https://app.handshake-app.com/api/v2/customers?id=C1234

customerGroup (string)

Filters customers by customer group. Pass the customer group's ID (not its name) as the filter parameter. For example:

# Filter for customers in the 'Preferred' customer group
$ curl https://app.handshake-app.com/api/v2/customers?customerGroup=Preferred

userGroup (string)

Filters customers by user group. Use the user group's ID (not its name). Results include customers in that user group or any of its sub-groups. For example:

# Filter for customers in the 'NorthWest' user group
$ curl https://app.handshake-app.com/api/v2/customers?userGroup=NorthWest

Example

{
   "billTo":{
      "btCustomer":"/api/v2/customers/43",
      "city":"Brooklyn",
      "country":"US",
      "fax":"555-555-5559",
      "objID":44,
      "phone":"123-456-7894",
      "postcode":"11217",
      "resource_uri":"/api/v2/addresses/44",
      "stCustomer":null,
      "state":"NY",
      "street":"8051 Brown Road",
      "street2":""
   },
   "cdate":"2010-10-06",
   "contact":"Kelly Slater",
   "creditCards":[
    ],
   "ctime":"2010-10-06T21:02:20Z",
   "customerGroup":{
      "id":"US",
      "manufacturer":null,
      "name":"US Retailers",
      "objID":946,
      "parent":null,
      "resource_uri":"/api/v2/categories/946",
      "subType":"Customer",
      "subcategories":[
       ]
   },
   "email":"[email protected]",
   "entityType":"Customer",
   "id":"C1004",
   "mtime":"2011-08-22T11:00:25Z",
   "name":"The Globe",
   "objID":43,
   "owner":"Demo",
   "paymentTerms":"NET 30",
   "resource_uri":"/api/v2/customers/43",
   "shipTos":[
    ],
   "shippingMethod":"FEDEX",
   "userGroup":{
      "id":"master",
      "manufacturer":null,
      "name":"Master",
      "objID":109039,
      "parent":null,
      "resource_uri":"/api/v2/categories/109039",
      "subType":"UserProfile",
      "subcategories":[
         "/api/v2/categories/109180"
      ]
   },
   "uuid":"01ed46bc-ac2d-4749-8a3a-47c699c9d756"
}