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 name and sorting mode (field_name_1 ASC or field_name_1 DESC). Supported fields: update_time, id

                      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

                                boolean

                                Whether this product will be made active or not

                                Default

                                true

                                selectable

                                boolean

                                Whether this product can be selected in deals or not

                                Default

                                true

                                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

                                      boolean

                                      Whether this product will be made active or not

                                      Default

                                      true

                                      selectable

                                      boolean

                                      Whether this product can be selected in deals or not

                                      Default

                                      true

                                      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