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 DEAR 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 DEAR 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 DEAR 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 DEAR 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 DEAR 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 DEAR 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 DEAR 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 DEAR 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 DEAR 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 DEAR 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 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 |
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 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 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"
}
Or
{
"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.”
}]