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 DEAR 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 DEAR will set it to default value (if field has it). If there is no default value specified DEAR 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”
}]