Products

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 Products resource allows Products to be listed, viewed, created, and updated. Here are some example URIs:

/Products/E6E8163F-6911-40e9-B740-90E5A0A3A996 - returns details of a particular product;
/Products?page=2 - returns the second page of 100 Products;
/Products - returns the first 100 active Products because page number 1 is the default;
/Products?page=2&limit=500 - returns the second page of 500 Products; i.e. the 501st to 1000th Products;
/Products?includeDeprecated=1 - returns the first page of 100 Productsincluding deprecated Products;
/Products?name=ABC - returns the first page of 100 Products with name starting with ABC;
/Products?sku=ABC - returns the first page of 100 Products with sku starting with ABC;

The full range of URIs and HTTP Verbs supported are:

Operation	HTTP Action
List of paginated Products	GET /Products?page={pageNumber}
View any Product	GET /Products/{id}
Create Product	POST /Products
Update Product	PUT /Products

These filters can be used with the GET Products endpoint:

Filter	Description
limit	Specifies the page size for pagination. Default page size is 100 Products.
name	Only return Products which name starting with ‘name’
sku	Only return Products which SKU starting from ‘sku’
modifiedSince	Only return Products modified since a specified date (UTC time)
includeDeprecated	Returns all Products, including deprecated, if set to true. If set to false or if it is not specified then returns only active (ie. non-deprecated) Products

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

Available Fields for Product:

Property	Type	Length	Required	Notes
ID	Guid			Ignored by POST action. Required for PUT action
SKU	String	50	Yes	Must be unique
Name	String	256	Yes	Product name. QuickBooks Online limitations: maximum length is 100 characters and must be unique
Category	String	256	Yes	Category name
Brand	String	256		Brand name
Type	String		Yes	Valid values: “Stock” or “Service”
CostingMethod	String		Yes	Valid values: “FIFO”, “Special - Batch”, “Special - Serial Number”, “FIFO - Serial Number”, “FIFO - Batch”, “FEFO - Batch”, “FEFO - Serial Number”
DefaultLocation	String	256	Yes	Name of the default Location for product. (Location with this name must exist in Locations reference book)
Length	Decimal Nullable			Length dimension, Defaults to 0
Width	Decimal Nullable			Width dimension, Defaults to 0
Height	Decimal Nullable			Height dimension, Defaults to 0
Weight	Decimal Nullable			Product Weight (in kilograms) , Defaults to 0
Barcode	String	256		Product barcode
UOM	String	50	Yes	Product Unit of Measure (Unit of measure with this name must exist in Unitsof measure reference book)
MinimumBeforeReorder	Decimal Nullable			Minimum available product quantity for this product to appear on Reorder report/forms. Defaults to 0
ReorderQuantity	Decimal Nullable			Default quantity to put into purchase order when reordering this product. Not applicable to reorder backordered form. Defaults to 0
PriceTier1	Decimal			Product Sale Price used when Price Tier 1 is selected in Sale Task. Up to 4 decimal places.
PriceTier2	Decimal			Product Sale Price used when Price Tier 2 is selected in Sale Task. Up to 4 decimal places.
PriceTier3	Decimal			Product Sale Price used when Price Tier 3 is selected in Sale Task. Up to 4 decimal places.
PriceTier4	Decimal			Product Sale Price used when Price Tier 4 is selected in Sale Task. Up to 4 decimal places.
PriceTier5	Decimal			Product Sale Price used when Price Tier 5 is selected in Sale Task. Up to 4 decimal places.
PriceTier6	Decimal			Product Sale Price used when Price Tier 6 is selected in Sale Task. Up to 4 decimal places.
PriceTier7	Decimal			Product Sale Price used when Price Tier 7 is selected in Sale Task. Up to 4 decimal places.
PriceTier8	Decimal			Product Sale Price used when Price Tier 8 is selected in Sale Task. Up to 4 decimal places.
PriceTier9	Decimal			Product Sale Price used when Price Tier 9 is selected in Sale Task. Up to 4 decimal places.
PriceTier10	Decimal			Product Sale Price used when Price Tier 10 is selected in Sale Task. Up to 4 decimal places.
PriceTiers	object		Optional	Object contain list with real price tier names and values for each listed price. This parameter is optional for specifying price. It required if PriceTierN parameters are not specified. IMPORTANT: It will be disabled in case if some of tenant price tiers have identical names.
AverageCost	Decimal			Read-only field. Average Unit Cost of this product. Up to 4 decimal places
Description	String	Unlimited		Multiline description of the product
AdditionalAttribute1	String	256		Value of the product’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 product’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 product’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 product’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 product’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 product’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 product’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 product’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 product’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 product’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 product’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)
DiscountRule	String	128		Valid discount name (discount with this name must exist in Product Discounts reference book and should be active)
Tags	String	256		Comma delimited list of custom tags
Status	String		Yes	The only valid values are “Active” and “Deprecated”
StockLocator	String	256		Location of this product in your warehouse
COGSAccount	String	50		Account code of an active EXPENSE class account from Chart Of Accounts. Only applicable to products of type Stock and ignored for Service products.
RevenueAccount	String	50		Account code of an active REVENUE class account from Chart Of Accounts
ExpenseAccount	String	50		Account code of an active EXPENSE class account from Chart Of Accounts. Only applicable to products of type Service and ignored for Stock products.
InventoryAccount	String	50		Account code of an active ASSET class account from Chart Of Accounts with Type not equal to FIXED or BANK. Only applicable to products of type Stock and ignored for Service products.
PurchaseTaxRule	String	50		Tax rule used for this product in Purchases. Tax Rule with this name must exist in Taxation Rules reference book and should be Active and have For Purchases flag set to “true” in API
SaleTaxRule	String	50		Tax rule used for this product in Sales. Tax Rule with this name must exist in Taxation Rules reference book and should be Active and have For Sales flag set to “true” in API
DropShipMode	String			One of these values: “No Drop Ship”, “Optional Drop Ship”, “Always Drop Ship”. Default value is “No Drop Ship”
LastModifiedOn	Nullable DateTime			UTC Time

Create new Product

To create new Product you need to send POST request to Products endpoint with Product structure (see above) as payload.

Product creation details

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

ID
AverageCost
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.

Sample of POST request

POST /Products

{ "SKU": "TEST-PROD-1", "Name": "Yet another Test product", "Category": "Accessories", "Brand": "Test brand", "Type": "Stock", "CostingMethod": "FIFO", "DropShipMode": "No Drop Ship", "Length": 0.1, "Width": 0.1, "Height": 0.1, "Weight": 0.1, "UOM": "Item", "PriceTier1": 100, "Status": "Active", "StockLocator": "Shelf #3" }

{ "SKU": "TEST-PROD-1", "Name": "Yet another Test product", "Category": "Accessories", "Brand": "Test brand", "Type": "Stock", "CostingMethod": "FIFO", "DropShipMode": "No Drop Ship", "Length": 0.1, "Width": 0.1, "Height": 0.1, "Weight": 0.1, "UOM": "Item", "PriceTiers": { “Retail price”: 100 }, "Status": "Active }

Return value

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

[{ “ErrorCode”:400, “Exception”:”Error explanation will be here” }, { “ErrorCode”:400, “Exception”:”Required attribute ‘SKU’ not provided.” }]

Update existing Product

To update Product you need to send PUT request to Products endpoint with part of Product 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.

Product update details

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

ID
AverageCost
LastModifiedOn

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

Samples of Product Family update

Next sample will update price in PriceTier1 for Product

PUT /Products {“ID”:”_some_guid_”, “PriceTier1”:”99.99”}

Update description and tags

PUT /Products {“ID”:”_some_guid_”, “Description”:”new description” , “Tags”:”one,two,three,four,five”}

Return value

In case if no errors occurred you will receive response with updated Product structure, otherwise you will receive response with list of validation errors like this:

[{ “ErrorCode”:400, “Exception”:”Error explanation will be here” }, { “ErrorCode”:400, “Exception”:”Attribute ‘PriceTier’ is invalid.” }]

Products

Was this article helpful?

Thank you for the positive feedback! Could you please share what was most helpful?

Sorry that this wasn't helpful! Can you tell us more?