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.”

}]