The latest version of the Cin7 Core API (V2) is available, with more advanced functionality and support for recent system changes. See the full API documentation to get started.
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 (see below) | ||||
| Contacts (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 | ||
| 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” }]