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
Returns data about all products.
Request
/api/v2/products
Query parameters
owner_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
cursor
string
For pagination, the marker (an opaque string value) representing the first item on the next page
limit
integer
For pagination, the limit of entries to be returned. If not provided, 100 items will be returned. Please note that a maximum value of 500 is allowed.
sort_by
string
The field to sort by. Supported fields: id, name, add_time, update_time
Default
id
Values
id
name
add_time
update_time
sort_direction
string
The sorting direction. Supported values: asc, desc
Default
asc
Values
asc
desc
Response
OK
Expand all
Copy code- true
- [ ... ]▶
- { ... }▶
Search products
Searches all products by name, code and/or custom fields. This endpoint is a wrapper of /v1/itemSearch with a narrower OAuth scope.
Request
/api/v2/products/search
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. Only the following custom field types are searchable: address, varchar, text, varchar_auto, double, monetary and phone. Read more about searching by custom fields here.
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.
include_fields
string
Supports including optional fields in the results which are not provided by default
Values
product.price
limit
integer
For pagination, the limit of entries to be returned. If not provided, 100 items will be returned. Please note that a maximum value of 500 is allowed.
cursor
string
For pagination, the marker (an opaque string value) representing the first item on the next page
Response
OK
Expand allCopy code- true
- { ... }▶
- { ... }▶
Get one product
Returns data about a specific product.
Request
/api/v2/products/{id}
Path parameters
id
integer
required
The ID of the product
Response
OK
Expand allCopy code- true
- { ... }▶
Get deals where a product is attached to
Returns data about deals that have a product attached to it.
Request
/v1/products/{id}/deals
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
Lists files associated with a product.
Request
/v1/products/{id}/files
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
Lists the followers of a product.
Request
/v1/products/{id}/followers
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
Lists users permitted to access a product.
Request
/v1/products/{id}/permittedUsers
Path parameters
id
integer
required
The ID of the product
Response
OK
Expand allCopy code- true
- [ ... ]▶
Get all product variations
Returns data about all product variations.
Request
/api/v2/products/{id}/variations
Path parameters
id
integer
required
The ID of the product
Query parameters
cursor
string
For pagination, the marker (an opaque string value) representing the first item on the next page
limit
integer
For pagination, the limit of entries to be returned. If not provided, 100 items will be returned. Please note that a maximum value of 500 is allowed.
Response
OK
Expand allCopy code- true
- [ ... ]▶
- { ... }▶
Add a product
Adds a new product to the Products inventory. For more information, see the tutorial for adding a product.
Request
/api/v2/products
Body parameters
application/json
name
string
required
The name of the product. Cannot be an empty string
code
string
The product code
description
string
The product description
unit
string
The unit in which this product is sold
tax
number
The tax percentage
Default
0
category
number
The category of the product
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.
is_linkable
boolean
Whether this product can be added to a deal or not
Default
true
visible_to
number
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
prices
array
An array of objects, each containing: currency (string), price (number), cost (number, optional), direct_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 the user's default currency will be assigned.
billing_frequency
string
The billing frequency. Only available for Advanced plans and above
Default
one-time
Values
one-time
annually
semi-annually
quarterly
monthly
weekly
billing_frequency_cycles
number
The billing frequency cycles. Only available for Advanced plans and above. When billing_frequency is set to one-time, this field must be null
Default
null
Response
Created
Expand allCopy code- true
- { ... }▶
Add a follower to a product
Adds a follower to a product.
Request
/v1/products/{id}/followers
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
- { ... }▶
Add a product variation
Adds a new product variation.
Request
/api/v2/products/{id}/variations
Path parameters
id
integer
required
The ID of the product
Body parameters
application/json
name
string
required
The name of the product variation
prices
array
Array of objects, each containing: currency (string), price (number), cost (number, optional). When prices is omitted altogether, a default price of 0, a default cost of 0, and the user's default currency will be assigned.
Response
Created
Expand allCopy code- true
- { ... }▶
Update a product
Updates product data.
Request
/api/v2/products/{id}
Path parameters
id
integer
required
The ID of the product
Body parameters
application/json
name
string
The name of the product. Cannot be an empty string
code
string
The product code
description
string
The product description
unit
string
The unit in which this product is sold
tax
number
The tax percentage
Default
0
category
number
The category of the product
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.
is_linkable
boolean
Whether this product can be added to a deal or not
Default
true
visible_to
number
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
prices
array
An array of objects, each containing: currency (string), price (number), cost (number, optional), direct_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 the user's default currency will be assigned.
billing_frequency
string
The billing frequency. Only available for Advanced plans and above
Default
one-time
Values
one-time
annually
semi-annually
quarterly
monthly
weekly
billing_frequency_cycles
number
The billing frequency cycles. Only available for Advanced plans and above. When billing_frequency is set to one-time, this field must be null
Default
null
Response
OK
Expand allCopy code- true
- { ... }▶
Update a product variation
Updates product variation data.
Request
/api/v2/products/{id}/variations/{product_variation_id}
Path parameters
id
integer
required
The ID of the product
product_variation_id
integer
required
The ID of the product variation
Body parameters
application/json
name
string
The name of the product variation
prices
array
Array of objects, each containing: currency (string), price (number), cost (number, optional). When prices is omitted altogether, a default price of 0, a default cost of 0, and the user's default currency will be assigned.
Response
OK
Expand allCopy code- true
- { ... }▶
Delete a product
Marks a product as deleted. After 30 days, the product will be permanently deleted.
Request
/api/v2/products/{id}
Path parameters
id
integer
required
The ID of the product
Response
OK
Expand allCopy code- true
- { ... }▶
Delete a follower from a product
Deletes a follower from a product.
Request
/v1/products/{id}/followers/{follower_id}
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
- { ... }▶
Delete a product variation
Deletes a product variation.
Request
/api/v2/products/{id}/variations/{product_variation_id}
Path parameters
id
integer
required
The ID of the product
product_variation_id
integer
required
The ID of the product variation
Response
OK
Expand allCopy code- true
- { ... }▶