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

Copy link
Copy to clipboard
GET

/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
200

List of products

Expand all
Copy code
    • true
    • [ ... ]
      • { ... }
        • { ... }

        Search products

        Copy link
        Copy to clipboard
        GET

        /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).

        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
        200

        Success

        Expand all
        Copy code
          • true
          • { ... }
            • { ... }

            Get one product

            Copy link
            Copy to clipboard
            GET

            /v1/products/{id}

            Returns data about a specific product.

            Path parameters

            id

            integer

            required

            The ID of the product

            Response
            200

            Get product information by id

            Expand all
            Copy code
              • true
              • { ... }
                • { ... }

                Get deals where a product is attached to

                Copy link
                Copy to clipboard
                GET

                /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 fetched.

                Default

                all_not_deleted

                Values

                open

                won

                lost

                deleted

                all_not_deleted

                Response
                200

                The data of deals that have a product attached

                Expand all
                Copy code
                  • true
                  • [ ... ]

                  List files attached to a product

                  Copy link
                  Copy to clipboard
                  GET

                  /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

                  include_deleted_files

                  number

                  When enabled, the list of files will also include deleted files. Please note that trying to download these files will not work.

                  Values

                  0

                  1

                  sort

                  string

                  The field names and sorting mode separated by a comma (field_name_1 ASC, field_name_2 DESC). Only first-level field keys are supported (no nested keys). Supported fields: id, user_id, deal_id, person_id, org_id, product_id, add_time, update_time, file_name, file_type, file_size, comment.

                  Response
                  200

                  Success

                  Expand all
                  Copy code
                    • true
                    • [ ... ]
                      • { ... }

                      List followers of a product

                      Copy link
                      Copy to clipboard
                      GET

                      /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
                      200

                      Lists the followers of a product

                      Expand all
                      Copy code
                        • true
                        • [ ... ]
                          • { ... }

                          List permitted users

                          Copy link
                          Copy to clipboard
                          GET

                          /v1/products/{id}/permittedUsers

                          Lists users permitted to access a product.

                          Path parameters

                          id

                          integer

                          required

                          The ID of the product

                          Response
                          200

                          Lists users permitted to access a product

                          Expand all
                          Copy code
                            • true
                            • [ ... ]
                              • { ... }

                              Add a product

                              Copy link
                              Copy to clipboard
                              POST

                              /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

                              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

                              number

                              Whether this product will be made active or not

                              Default

                              1

                              Values

                              0

                              1

                              selectable

                              number

                              Whether this product can be selected in deals or not

                              Default

                              1

                              Values

                              0

                              1

                              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

                              ValueDescription
                              1Owner & followers
                              3Entire company

                              Professional / Enterprise plan

                              ValueDescription
                              1Owner only
                              3Owner's visibility group
                              5Owner's visibility group and sub-groups
                              7Entire 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

                              object

                              Object containing price objects, where each key is the price currency code, and each value is the price object. Each price object contains: 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, no prices will be set up for the product.

                              Response
                              201

                              Add product data

                              Expand all
                              Copy code
                                • true
                                • { ... }
                                  • { ... }

                                  Add a follower to a product

                                  Copy link
                                  Copy to clipboard
                                  POST

                                  /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
                                  201

                                  Adds a follower to a product

                                  Expand all
                                  Copy code
                                    • true
                                    • { ... }

                                    Update a product

                                    Copy link
                                    Copy to clipboard
                                    PUT

                                    /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

                                    number

                                    Whether this product will be made active or not

                                    Default

                                    1

                                    Values

                                    0

                                    1

                                    selectable

                                    number

                                    Whether this product can be selected in deals or not

                                    Default

                                    1

                                    Values

                                    0

                                    1

                                    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

                                    ValueDescription
                                    1Owner & followers
                                    3Entire company

                                    Professional / Enterprise plan

                                    ValueDescription
                                    1Owner only
                                    3Owner's visibility group
                                    5Owner's visibility group and sub-groups
                                    7Entire 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

                                    object

                                    Object containing price objects, where each key is the price currency code, and each value is the price object. Each price object contains: 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, no prices will be set up for the product.

                                    Response
                                    200

                                    Updates product data

                                    Expand all
                                    Copy code
                                      • true
                                      • { ... }
                                        • { ... }

                                        Delete a product

                                        Copy link
                                        Copy to clipboard
                                        DELETE

                                        /v1/products/{id}

                                        Marks a product as deleted.

                                        Path parameters

                                        id

                                        integer

                                        required

                                        The ID of the product

                                        Response
                                        200

                                        Deletes a product

                                        Expand all
                                        Copy code
                                          • true
                                          • { ... }

                                          Delete a follower from a product

                                          Copy link
                                          Copy to clipboard
                                          DELETE

                                          /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
                                          200

                                          Deletes a follower from a product

                                          Expand all
                                          Copy code
                                            • true
                                            • { ... }

                                            Subscribe to Pipedrive’s Developer Newsletter