Products
Products are the goods or services you are dealing with. Each product can have N different price points - firstly, each product can have a price in N different currencies, and secondly, each product can have N variations of itself, each having N prices in different currencies. Note that only one price per variation per currency is supported. Products can be instantiated to deals. In the context of instatiation, a custom price, quantity, duration and discount can be applied.
Get all products
/v1/products
Returns data about all products.
Query parameters
user_id
integer
If supplied, only products owned by the given user will be returned
filter_id
integer
The ID of the filter to use
ids
array
An array of integers with the IDs of the products that should be returned in the response
first_char
string
If supplied, only products whose name starts with the specified letter will be returned (case insensitive)
get_summary
boolean
If supplied, the response will return the total numbers of products in the additional_data.summary.total_count property
start
integer
Pagination start
Default
0
limit
integer
Items shown per page
Response
OK
Expand all
Copy code- true
- [ ... ]▶
- { ... }▶
- { ... }▶
Search products
/v1/products/search
Searches all products by name, code and/or custom fields. This endpoint is a wrapper of /v1/itemSearch with a narrower OAuth scope.
Query parameters
term
string
required
The search term to look for. Minimum 2 characters (or 1 if using exact_match). Please note that the search term has to be URL encoded.
fields
string
A comma-separated string array. The fields to perform the search from. Defaults to all of them.
Values
code
custom_fields
name
exact_match
boolean
When enabled, only full exact matches against the given term are returned. It is not case sensitive.
Values
true
false
include_fields
string
Supports including optional fields in the results which are not provided by default
Values
product.price
start
integer
Pagination start. Note that the pagination is based on main results and does not include related items when using search_for_related_items parameter.
Default
0
limit
integer
Items shown per page
Response
OK
Expand allCopy code- true
- { ... }▶
- { ... }▶
Get one product
/v1/products/{id}
Returns data about a specific product.
Path parameters
id
integer
required
The ID of the product
Response
OK
Expand allCopy code- true
- { ... }▶
- { ... }▶
Get deals where a product is attached to
/v1/products/{id}/deals
Returns data about deals that have a product attached to it.
Path parameters
id
integer
required
The ID of the product
Query parameters
start
integer
Pagination start
Default
0
limit
integer
Items shown per page
status
string
Only fetch deals with a specific status. If omitted, all not deleted deals are returned. If set to deleted, deals that have been deleted up to 30 days ago will be included.
Default
all_not_deleted
Values
open
won
lost
deleted
all_not_deleted
Response
OK
Expand allCopy code- true
- [ ... ]▶
- { ... }▶
- { ... }▶
List files attached to a product
/v1/products/{id}/files
Lists files associated with a product.
Path parameters
id
integer
required
The ID of the product
Query parameters
start
integer
Pagination start
Default
0
limit
integer
Items shown per page
sort
string
The field name and sorting mode (field_name_1 ASC or field_name_1 DESC). Supported fields: update_time, id
Response
OK
Expand allCopy code- true
- [ ... ]▶
- { ... }▶
List followers of a product
/v1/products/{id}/followers
Lists the followers of a product.
Path parameters
id
integer
required
The ID of the product
Query parameters
start
integer
Pagination start
Default
0
limit
integer
Items shown per page
Response
OK
Expand allCopy code- true
- [ ... ]▶
- { ... }▶
List permitted users
/v1/products/{id}/permittedUsers
Lists users permitted to access a product.
Path parameters
id
integer
required
The ID of the product
Response
OK
Expand allCopy code- true
- [ ... ]▶
Add a product
/v1/products
Adds a new product to the Products inventory. For more information, see the tutorial for adding a product.
Body parameters
application/json
name
string
required
The name of the product
code
string
The product code
unit
string
The unit in which this product is sold
tax
number
The tax percentage
Default
0
active_flag
boolean
Whether this product will be made active or not
Default
true
selectable
boolean
Whether this product can be selected in deals or not
Default
true
visible_to
string
The visibility of the product. If omitted, the visibility will be set to the default visibility setting of this item type for the authorized user. Read more about visibility groups here.
Essential / Advanced plan
| Value | Description |
|---|---|
1 | Owner & followers |
3 | Entire company |
Professional / Enterprise plan
| Value | Description |
|---|---|
1 | Owner only |
3 | Owner's visibility group |
5 | Owner's visibility group and sub-groups |
7 | Entire company |
Values
1
3
5
7
owner_id
integer
The ID of the user who will be marked as the owner of this product. When omitted, the authorized user ID will be used.
prices
array
An array of objects, each containing: currency (string), price (number), cost (number, optional), overhead_cost (number, optional). Note that there can only be one price per product per currency. When prices is omitted altogether, a default price of 0 and a default currency based on the company's currency will be assigned.
Response
Created
Expand allCopy code- true
- { ... }▶
- { ... }▶
Add a follower to a product
/v1/products/{id}/followers
Adds a follower to a product.
Path parameters
id
integer
required
The ID of the product
Body parameters
application/json
user_id
integer
required
The ID of the user
Response
Created
Expand allCopy code- true
- { ... }▶
Update a product
/v1/products/{id}
Updates product data.
Path parameters
id
integer
required
The ID of the product
Body parameters
application/json
name
string
The name of the product
code
string
The product code
unit
string
The unit in which this product is sold
tax
number
The tax percentage
Default
0
active_flag
boolean
Whether this product will be made active or not
Default
true
selectable
boolean
Whether this product can be selected in deals or not
Default
true
visible_to
string
The visibility of the product. If omitted, the visibility will be set to the default visibility setting of this item type for the authorized user. Read more about visibility groups here.
Essential / Advanced plan
| Value | Description |
|---|---|
1 | Owner & followers |
3 | Entire company |
Professional / Enterprise plan
| Value | Description |
|---|---|
1 | Owner only |
3 | Owner's visibility group |
5 | Owner's visibility group and sub-groups |
7 | Entire company |
Values
1
3
5
7
owner_id
integer
The ID of the user who will be marked as the owner of this product. When omitted, the authorized user ID will be used.
prices
array
An array of objects, each containing: currency (string), price (number), cost (number, optional), overhead_cost (number, optional). Note that there can only be one price per product per currency. When prices is omitted altogether, a default price of 0 and a default currency based on the company's currency will be assigned.
Response
OK
Expand allCopy code- true
- { ... }▶
- { ... }▶
Delete a product
/v1/products/{id}
Marks a product as deleted. After 30 days, the product will be permanently deleted.
Path parameters
id
integer
required
The ID of the product
Response
OK
Expand allCopy code- true
- { ... }▶
Delete a follower from a product
/v1/products/{id}/followers/{follower_id}
Deletes a follower from a product.
Path parameters
id
integer
required
The ID of the product
follower_id
integer
required
The ID of the relationship between the follower and the product
Response
OK
Expand allCopy code- true
- { ... }▶
