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.
Returns data about all products.
/api/v2/products
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
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.
OK
Searches all products by name, code and/or custom fields. This endpoint is a wrapper of /v1/itemSearch with a narrower OAuth scope.
/api/v2/products/search
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
OK
Returns data about a specific product.
/api/v2/products/{id}
id
integer
required
The ID of the product
OK
Returns data about deals that have a product attached to it.
/v1/products/{id}/deals
id
integer
required
The ID of the product
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
OK
Lists files associated with a product.
/v1/products/{id}/files
id
integer
required
The ID of the product
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
.
OK
Lists the followers of a product.
/v1/products/{id}/followers
id
integer
required
The ID of the product
start
integer
Pagination start
Default
0
limit
integer
Items shown per page
OK
Lists users permitted to access a product.
/v1/products/{id}/permittedUsers
id
integer
required
The ID of the product
OK
Returns data about all product variations.
/api/v2/products/{id}/variations
id
integer
required
The ID of the product
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.
OK
Adds a new product to the Products inventory. For more information, see the tutorial for adding a product.
/api/v2/products
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.
Value | Description |
---|---|
1 | Owner & followers |
3 | Entire company |
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
Only available in Advanced 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 Advanced 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
For all the other values of billing_frequency
, null
represents a product billed indefinitely
Must be a positive integer less or equal to 312
Created
Adds a follower to a product.
/v1/products/{id}/followers
id
integer
required
The ID of the product
application/json
user_id
integer
required
The ID of the user
Created
Adds a new product variation.
/api/v2/products/{id}/variations
id
integer
required
The ID of the product
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.
Created
Updates product data.
/api/v2/products/{id}
id
integer
required
The ID of the product
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.
Value | Description |
---|---|
1 | Owner & followers |
3 | Entire company |
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
Only available in Advanced 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 Advanced 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
For all the other values of billing_frequency
, null
represents a product billed indefinitely
Must be a positive integer less or equal to 312
OK
Updates product variation data.
/api/v2/products/{id}/variations/{product_variation_id}
id
integer
required
The ID of the product
product_variation_id
integer
required
The ID of the product variation
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.
OK
Marks a product as deleted. After 30 days, the product will be permanently deleted.
/api/v2/products/{id}
id
integer
required
The ID of the product
OK
Deletes a follower from a product.
/v1/products/{id}/followers/{follower_id}
id
integer
required
The ID of the product
follower_id
integer
required
The ID of the relationship between the follower and the product
OK
Deletes a product variation.
/api/v2/products/{id}/variations/{product_variation_id}
id
integer
required
The ID of the product
product_variation_id
integer
required
The ID of the product variation
OK