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

OK

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

        OK

        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

            OK

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

                OK

                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

                      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

                      OK

                      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

                          OK

                          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

                              OK

                              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

                                  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

                                  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

                                  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

                                  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

                                  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
                                  201

                                  Created

                                  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

                                      Created

                                      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

                                        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

                                        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

                                        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
                                        200

                                        OK

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

                                            Delete a product

                                            Copy link
                                            Copy to clipboard
                                            DELETE

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

                                            OK

                                            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

                                              OK

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

                                                Subscribe to Pipedrive’s Developer Newsletter