ProductFamilies

The ProductFamilies resource allows Product Families to be listed, viewed, create and modified. Here are some examples URIs:

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

The full range of URIs and HTTP Verbs supported are:

Operation	HTTP Action
List of paginated Product Families	GET /ProductFamilies?page={pageNumber}
View any Product Family	GET /ProductFamilies/{id}
Create new Product Family	POST /ProductFamilies
Update existing Product Family	PUT /ProductFamilies

These filters can be used with the GET ProductFamilies endpoint:

Filter	Description
limit	Specifies the page size for pagination. Default page size is 100 ProductFamilies.
name	Only return ProductFamilies that start with the specific product name
sku	Only return ProductFamilies that have this specific sku
modifiedSince	Only return ProductFamilies modified since a specified date (UTC time)

Filters are used by adding the filter and value to the URI: /ProductFamilies?sku=ABC

Available Fields for ProductFamily:

Property	Type	Length	Required	Notes
Products	Array of Products	Min 1 element	Yes	List of Products included in the Family. See description below.
ID	Guid			Unique ID. Required for PUT request
SKU	String	45	Yes	Must be unique. Product Family SKU, used to generate Product SKUs
Name	String	256	Yes	Product Family name, used to generate Product names
Category	String	256	Yes	Category name
Brand	String	256		Brand name
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 family. (Location with this name must exist in Locations reference book)
UOM	String	50	Yes	Unit of Measure (Unit of measure with this name must exist in Units of 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.
Description	String	Unlimited		Multiline description of the product
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
COGSAccount	String	50		Account code of an active EXPENSE class account from Chart Of Accounts.
RevenueAccount	String	50		Account code of an active REVENUE class account from Chart Of Accounts
InventoryAccount	String	50		Account code of an active ASSET class account from Chart Of Accounts with Type not equal to FIXED or BANK.
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”
Option1Name	String	50	Yes	Family Option 1 name. I.e. Size, Colour, etc. Defaults to Option 1
Option2Name	String	50		Family Option 2 name. I.e. Size, Colour, etc. Defaults to Option 2
Option3Name	String	50		Family Option 3 name. I.e. Size, Colour, etc. Defaults to Option 3
Option1Values	String			Comma-delimited list of all possible values for Option 1. Combination of unique values of Option 1 Value for product family products.
Option2Values	String			Comma-delimited list of all possible values for Option 2. Combination of unique values of Option 2 Value for product family products.
Option3Values	String			Comma-delimited list of all possible values for Option 3. Combination of unique values of Option 3 Value for product family products.
LastModifiedOn	Nullable DateTime			UTC Time

Products:

Property	Type	Length	Required	Notes
ID	Guid		Yes	Unique Product ID
SKU	String	50		Must be unique across all products. Ignored in POST and PUT
Name	String	256		Product variation name. Ignored in POST and PUT
Option1	String	256	Yes	The value that corresponds to the Option 1. Should be included in Option1Values
Option2	String	256		The value that corresponds to the Option 2. Should be included in Option2Values. Should be empty if Option 2 wasn’t set.
Option3	String	256		The value that corresponds to the Option 3. Should be included in Option3Values. Should be empty if Option 3 wasn’t set.

Create new Product Family

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

Product Family creation details

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

ID
LastModifiedOn
Option1Values
Option2Values
Option3Values

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 request for creation

POST /ProductFamilies

{
"Products": [
{
"ID": "0f4b6d4e-a411-40a9-9fd0-b147744e42eb",
"Option1": "Ultimate"
}
],
"SKU": "TEST-FAM",
"Name": "[Test] product family for testing",
"Category": "Accessories",
"CostingMethod": "FIFO",
"UOM": "Item",
"MinimumBeforeReorder": 0,
"ReorderQuantity": 0,
"PriceTier1": 29,
"PriceTier2": 0,
"PriceTier3": 0,
"PriceTier4": 0,
"PriceTier5": 0,
"PriceTier6": 0,
"PriceTier7": 0,
"PriceTier8": 0,
"PriceTier9": 0,
"PriceTier10": 0,
"Description": "Test description",
"DropShipMode": "No Drop Ship",
"Option1Name": "Test option",
"Option1Values": "Ultimate"
}

Return value

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

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

Update existing Product Family

To update Product Family you need to send PUT request to ProductFamilies endpoint with part of ProductFamily 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 Family update details

The following properties of the ProductFamily are read-only for PUT request. You can’t update it.

ID
LastModifiedOn
Option1Values
Option2Values
Option3Values

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

Samples of Product Family update

Next sample will update price in PriceTier1 for Product Family

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

Update description and Tags

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

Note

If you want provide products inside ProductFamilies PUT request, it will be added or updated. Delete operations are not allowed. So, it will be added to family it there are no such products were already added to product family, or it will be updated in case if these products are already were added before.

Return value

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

[{
“ErrorCode”:400,
“Exception”:”Error explanation will be here”
}]

ProductFamilies

Was this article helpful?