ProductFamilies

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 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, Color, etc. Defaults to Option 1
Option2Name String 50 Family Option 2 name. I.e. Size, Color, etc. Defaults to Option 2
Option3Name String 50 Family Option 3 name. I.e. Size, Color, 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.

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

Was this article helpful?

Have more questions? Submit a request