Customers

Customers

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 Cin7 Core 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 Cin7 Core 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 Cin7 Core 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 Cin7 Core 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 Cin7 Core 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 Cin7 Core 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 Cin7 Core 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 Cin7 Core 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 Cin7 Core 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 Cin7 Core 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 Cin7 Core 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 Cin7 Core will set it to default value (if field has it). If there is no default value specified Cin7 Core will leave it empty.

If any optional field was not provided in payload Cin7 Core will set it to default value (if field has it). If there is no default value specified Cin7 Core 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”
}]

Was this article helpful?

Have more questions? Submit a request