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.

IncludeInEmail Boolean  
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”
}]