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.
Cost
10
Request
/api/v2/products
Query parameters
owner_id
integer
If supplied, only products owned by the given user will be returned
ids
string
Optional comma separated string array of up to 100 entity ids to fetch. If filter_id is provided, this is ignored. If any of the requested entities do not exist or are not visible, they are not included in the response.
filter_id
integer
The ID of the filter to use
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
custom_fields
string
Comma separated string array of custom fields keys to include. If you are only interested in a particular set of custom fields, please use this parameter for a smaller response.
A maximum of 15 keys is allowed.
Response
OK
Expand all
Copy code- true
- [ ... ]▶
- { ... }▶
Get one product
Returns data about a specific product.
Cost
1
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.
Cost
20
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.
Cost
20
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. Please note that a maximum value of 100 is allowed.
sort
string
Supported fields: id, update_time
Response
OK
Expand allCopy code- true
- [ ... ]▶
- { ... }▶
List followers of a product
Lists users who are following the product.
Cost
10
Request
/api/v2/products/{id}/followers
Path parameters
id
integer
required
The ID of the product
Query parameters
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
- [ ... ]▶
- { ... }▶
List followers changelog of a product
Lists changelogs about users have followed the product.
Cost
10
Request
/api/v2/products/{id}/followers/changelog
Path parameters
id
integer
required
The ID of the product
Query parameters
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 image of a product
Retrieves the image of a product. The public URL has a limited lifetime of 7 days.
Cost
10
Request
/api/v2/products/{id}/images
Path parameters
id
integer
required
The ID of the product
Response
OK
Expand allCopy code- true
- { ... }▶
List permitted users
Lists users permitted to access a product.
Cost
10
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.
Cost
10
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
- [ ... ]▶
- { ... }▶
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.
Cost
20
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
- { ... }▶
- { ... }▶
Add a product
Adds a new product to the Products inventory. For more information, see the tutorial for adding a product.
Cost
5
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.
Light / Growth and Professional plans
| Value | Description |
|---|---|
1 | Owner & followers |
3 | Entire company |
Premium / Ultimate 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.
custom_fields
object
An object where each key represents a custom field. All custom fields are referenced as randomly generated 40-character hashes
billing_frequency
string
Only available in Growth and above plans
How often a customer is billed for access to a service or product
Default
one-time
Values
one-time
annually
semi-annually
quarterly
monthly
weekly
billing_frequency_cycles
integer
Only available in Growth and above plans
The number of times the billing frequency repeats for a product in a deal
When billing_frequency is set to one-time, this field must be null
When billing_frequency is set to weekly, this field cannot be null
For all the other values of billing_frequency, null represents a product billed indefinitely
Must be a positive integer less or equal to 208
Response
Created
Expand allCopy code- true
- { ... }▶
Duplicate a product
Creates a duplicate of an existing product including all variations, prices, and custom fields.
Cost
5
Request
/api/v2/products/{id}/duplicate
Path parameters
id
integer
required
The ID of the product
Response
Created
Expand allCopy code- true
- { ... }▶
Add a follower to a product
Adds a user as a follower to the product.
Cost
5
Request
/api/v2/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 to add as a follower
Response
Created
Expand allCopy code- true
- { ... }▶
Upload an image for a product
Uploads an image for a product.
Cost
20
Request
/api/v2/products/{id}/images
Path parameters
id
integer
required
The ID of the product
Body parameters
multipart/form-data
data
string
required
One image supplied in the multipart/form-data encoding
Format
binary
Response
Created
Expand allCopy code- true
- { ... }▶
Add a product variation
Adds a new product variation.
Cost
5
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. The maximum length is 255 characters.
prices
array
Array of objects, each containing: currency (string), price (number), cost (number, optional), direct_cost (number, optional), notes (string, optional). When prices is omitted altogether, a default price of 0, a default cost of 0, a default direct_cost of 0 and the user's default currency will be assigned.
Response
Created
Expand allCopy code- true
- { ... }▶
Update an image for a product
Updates the image of a product.
Cost
20
Request
/api/v2/products/{id}/images
Path parameters
id
integer
required
The ID of the product
Body parameters
multipart/form-data
data
string
required
One image supplied in the multipart/form-data encoding
Format
binary
Response
OK
Expand allCopy code- true
- { ... }▶
Update a product
Updates product data.
Cost
5
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.
Light / Growth and Professional plans
| Value | Description |
|---|---|
1 | Owner & followers |
3 | Entire company |
Premium / Ultimate 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.
custom_fields
object
An object where each key represents a custom field. All custom fields are referenced as randomly generated 40-character hashes
billing_frequency
string
Only available in Growth and above plans
How often a customer is billed for access to a service or product
Values
one-time
annually
semi-annually
quarterly
monthly
weekly
billing_frequency_cycles
integer
Only available in Growth and above plans
The number of times the billing frequency repeats for a product in a deal
When billing_frequency is set to one-time, this field must be null
When billing_frequency is set to weekly, this field cannot be null
For all the other values of billing_frequency, null represents a product billed indefinitely
Must be a positive integer less or equal to 208
Response
OK
Expand allCopy code- true
- { ... }▶
Update a product variation
Updates product variation data.
Cost
5
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. The maximum length is 255 characters.
prices
array
Array of objects, each containing: currency (string), price (number), cost (number, optional), direct_cost (number, optional), notes (string, optional). When prices is omitted altogether, a default price of 0, a default cost of 0, a default direct_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.
Cost
3
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 user follower from the product.
Cost
3
Request
/api/v2/products/{id}/followers/{follower_id}
Path parameters
id
integer
required
The ID of the product
follower_id
integer
required
The ID of the following user
Response
OK
Expand allCopy code- true
- { ... }▶
Delete an image of a product
Deletes the image of a product.
Cost
6
Request
/api/v2/products/{id}/images
Path parameters
id
integer
required
The ID of the product
Response
OK
Expand allCopy code- true
- { ... }▶
Delete a product variation
Deletes a product variation.
Cost
3
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
- { ... }▶