search-icon

The Customers resource allows Customers to be listed, viewed, created, and updated. Here are some example URIs:

 

· /Customers/E6E8163F-6911-40e9-B740-90E5A0A3A996 - returns details of a particular customer;

· /Customers?page=2 - returns the second page of 100 customers;

· /Customers - returns the first 100 active customers because page number 1 is the default;

· /Customers?page=2&limit=500 - returns the second page of 500 customers; ie. the 501st to 1000th customers;

· /Customers?includeDeprecated=1 - returns the first page of 100 customers including deprecated customers;

· /Customers?name=ABC - returns the first page of 100 customers with name starting with ABC;

 

The full range of URIs and HTTP Verbs supported are:
















Operation


HTTP Action


List of paginated Customers


GET /Customers?page={pageNumber}


View any Customer


GET /Customers/{id}


Create a set of Customers


POST /Customers


Update a set of Customers


PUT /Customers


These filters can be used with the GET Customers endpoint:















Filter


Description


limit


Specifies the page size for pagination. Default page size is 100 customers.


name


Only return customers that start with the specific customer name


modifiedSince


Only return customers modified since a specified date (UTC time)


includeDeprecated


Returns all customers, including deprecated, if set to true. If set to false or if it is not specified then returns only active (ie. non-deprecated) customers


Filters are used by adding the filter and value to the URI: /Customers?name=ABC&includeDeprecated=true


Available Fields for Customer:


























































































































































































Property


Type


Length


Required


Notes


Addresses


Address collection, see below


Contacts


Contact collection, see below


ID


Guid




Ignored by POST action. Required for PUT action


Name


String


256


Yes


Must be unique


Currency


String


3


Yes


ISO code


PaymentTerm


String


50


Yes


Valid payment term name (payment term with this name must exist in Payment Terms reference book and should be active)


Discount


Nullable Decimal




Discount percentage, applied for all sales to this customer by default. Range from 0 to 100


TaxRule


String


50


Yes


Valid taxation rule name (taxation rule with this name must exist in Taxation Rules reference book and should have For Sales flag set to “true” in API)


Carrier


String


256



Default Carrier to use when Shipping goods to this Customer (Carrier with this name must exist in Carriers reference book)


SalesRepresentative


String


256



Name of the Contact from Company Contacts with type Sales


Location


String


256



Name of the default Location used to dispatch sales to this customer from. (Location with this name must exist in Locations reference book)


Comments


String


2000



Multiline comment field. Automatically copied to Notes field in sale task when the customer is selected.


AccountReceivable


String


50


Yes


Account code of active account from chart of accounts with Account Receivable=true


RevenueAccount


String


50


Yes


Account code of active account from chart of accounts with Class=Revenue


PriceTier


String


50



Name of the price tier to use for the customer. If not provided then first price tier is used by default.


TaxNumber


String


256



Taxation number of the customer used to report to tax authorities


AdditionalAttribute1


String


256



Value of the customer’s additional attribute 1. Ignored when current DEAR Subscription plan is Small or Medium or when AttributeSet name is not provided.


AdditionalAttribute2


String


256



Value of the customer’s additional attribute 2. Ignored when current DEAR Subscription plan is Small or Medium or when AttributeSet name is not provided.


AdditionalAttribute3


String


256



Value of the customer’s additional attribute 3. Ignored when current DEAR Subscription plan is Small or Medium or when AttributeSet name is not provided.


AdditionalAttribute4


String


256



Value of the customer’s additional attribute 4. Ignored when current DEAR Subscription plan is Small or Medium or when AttributeSet name is not provided.


AdditionalAttribute5


String


256



Value of the customer’s additional attribute 5. Ignored when current DEAR Subscription plan is Small or Medium or when AttributeSet name is not provided.


AdditionalAttribute6


String


256



Value of the customer’s additional attribute 6. Ignored when current DEAR Subscription plan is Small or Medium or when AttributeSet name is not provided.


AdditionalAttribute7


String


256



Value of the customer’s additional attribute 7. Ignored when current DEAR Subscription plan is Small or Medium or when AttributeSet name is not provided.


AdditionalAttribute8


String


256



Value of the customer’s additional attribute 8. Ignored when current DEAR Subscription plan is Small or Medium or when AttributeSet name is not provided.


AdditionalAttribute9


String


256



Value of the customer’s additional attribute 9. Ignored when current DEAR Subscription plan is Small or Medium or when AttributeSet name is not provided.


AdditionalAttribute10


String


256



Value of the customer’s additional attribute 10. Ignored when current DEAR Subscription plan is Small or Medium or when AttributeSet name is not provided.


AttributeSet


String


50



Name of the customer’s additional attribute set. Ignored when current DEAR Subscription plan is Small or Medium. (AttributeSet with this name must exist in Additional Attribute Sets reference book)


Tags


String


256



Comma delimited list of custom tags


Status


String



Yes


The only valid values are “Active” and “Deprecated”


LastModifiedOn


Nullable DateTime





CreditLimit


Nullable Decimal




Credit Limit that applies to this customer. If left blank or is 0 then no credit limit is applied. Represents maximum amount of credit in customer currency.


 

Addresses:






















































Property


Type


Length


Required


Notes


Line1


String


256


Yes



Line2


String


256




Type


String


8


Yes


Billing, Shipping or Business


DefaultForType


Boolean



Yes


“true” if specified address should be used as default for it’s Type (Shipping). Default addresses are selected by default when customer is selected in sale task.


City


String


256




State


String


256




Postcode


String


20




Country


String


32



Name of the country


 

Contacts:
















































Property


Type


Length


Required


Notes


Name


String


256


Yes


Contact person’s name


Phone


String


50




Fax


String


50




Email


String


256




Website


String


256




Default


Boolean



Yes


True if this contact is the customer’s default contact. Will be selected automatically when the customer is selected in sale task.


Comment


String


256



Multiline comment field. Copied to Notes area in sale task when this customer is selected.


IncludeInEmailBoolean 
Specify this property as True if you want to include particular contact to be added to CC field in Send Email dialogue for Purchase and Sale Tasks

 

Create new Customer

To create new Customer you need to send POST request to Customers endpoint with Customer structure (see above) as payload serialized to Json.

Customer creation details

The following properties of the Customer are read-only. If any of these properties are included in the request, it will be ignored.

· ID

· LastModifiedOn


The properties marked “Required” are required for POST request. The request won’t be fulfilled unless these properties are valid.

If any optional field was not provided in payload DEAR will set it to default value (if field has it). If there is no default value specified DEAR will leave it empty.


Sample of Customer creation

Next sample request will create new customer:

POST /Customers

{
 "Addresses": [
 {
 "Line1": "The First ave",
 "Line2": "",
 "City": "City X",
 "State": "NewState",
 "Postcode": "12345",
 "Country": "US",
 "Type": "Shipping",
 "DefaultForType": true
 },
 {
 "Line1": "The First ave",
      "Line2": "",
 "City": "City X",
 "State": "NewState",
 "Postcode": "12345",
 "Country": "US",
 "Type": "Billing",
 "DefaultForType": true
 }
 ],
 "Contacts": [
 {
 "Name": "John Smith",
 "Phone": "1-555-555-55-55",
 "Email": "email@sample.com",
 "Default": true
 }
 ],
 "Name": "Sample Company",
 "Currency": "USD",
 "PaymentTerm": "30 days term",
 "Discount": 0,
 "TaxRule": "Tax on Sales",
 "Carrier": "DHL",
 "Location": "Main Warehouse",
 "Comments": "Sample customer",
 "AccountReceivable": "610",
 "RevenueAccount": "200",
 "PriceTier": "Default Price Tier",
 "Tags": "sample, customer",
 "Status": "Active",
 "CreditLimit": 0
}


 

Return value

In case if no errors occurred you will receive response with newly created Customer structure, otherwise you will receive response with error list, like this:

[{
“ErrorCode”:400,
“Exception”:”Error explanation will be here”
},
{
“ErrorCode”:404,
“Exception”:”Tax Rule was not found”
}]


 

 

Update existing Customer

To update Product Family you need to send PUT request to Customers endpoint with part of Customer structure as payload. You also could provide full structure’s data as payload, but in this case all not read-only fields will be updated.

Customer update details

The following properties of the Customer are read-only. You can’t update it. If any of these properties are included in the request, it will be ignored.

· ID

· LastModifiedOn

All provided fields of Customer, except read-only fields will be updated.

 

Samples of Customer update

Next sample will update customer’s Sale Price Tier to first for Customer


PUT /Customers/ {“ID”:”_some_guid_”, “PriceTier”:”Price Tier 1”}
Or
PUT /Customers/_some_guid_/ {“PriceTier” : “Price Tier 1”}

Note

If you want to update Addresses or Contacts related to Customer, provide list of new and modified objects. No Addresses or Contacts will not deleted.

 

Return value

In case if no errors occurred you will receive response with updated Customer structure, otherwise you will receive response with error list, like this:

[{
“ErrorCode”:400,
“Exception”:”Error explanation will be here”
},
{
“ErrorCode”:404,
“Exception”:”Tax Rule was not found”
}]


 


Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.