Products

Products are the goods or services you are dealing with. Each product can have N different price points - first, each Product can have a price in N different currencies, and secondly, each Product can have N variations of itself, each having N prices 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

ids

array

An array of integers with the IDs of the Products that sould 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, 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
          • { ... }
            • { ... }

            Find products by name

            Copy link
            Copy to clipboard
            GET

            /v1/products/find

            Deprecated endpoint

            This endpoint is deprecated. Please use /v1/products/search or /v1/itemSearch instead.
            Returns data about the products that were found. If currency was set in request, prices in that currency are served back.

            Query parameters

            term

            string

            required

            Search term to look for, minimum 3 characters.

            currency

            string

            Currency code in which prices should be returned in. If omitted, prices in user's default currency will be returned.

            start

            integer

            Pagination start

            Default

            0

            limit

            integer

            Items shown per page

            Response
            200

            Returns data about the Products that were found

            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

                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.

                    Path parameters

                    id

                    integer

                    required

                    ID of the product

                    Query parameters

                    start

                    integer

                    Pagination start

                    Default

                    0

                    limit

                    integer

                    Items shown per page

                    status

                    string

                    Only fetch deals with 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

                      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

                      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

                          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

                              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 on how to add a product, see this tutorial.

                                  Body parameters

                                  application/json

                                  name

                                  string

                                  Name of the product.

                                  code

                                  string

                                  Product code.

                                  unit

                                  string

                                  Unit in which this product is sold

                                  tax

                                  number

                                  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

                                  Visibility of the product. If omitted, visibility will be set to the default visibility setting of this item type for the authorized user.

                                  ValueDescription
                                  1Owner & followers (private)
                                  3Entire company (shared)

                                  Values

                                  1

                                  3

                                  owner_id

                                  integer

                                  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

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

                                      ID of the product

                                      Body parameters

                                      application/json

                                      user_id

                                      integer

                                      required

                                      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

                                        ID of the product

                                        Body parameters

                                        application/json

                                        name

                                        string

                                        Name of the product.

                                        code

                                        string

                                        Product code.

                                        unit

                                        string

                                        Unit in which this product is sold

                                        tax

                                        number

                                        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

                                        Visibility of the product. If omitted, visibility will be set to the default visibility setting of this item type for the authorized user.

                                        ValueDescription
                                        1Owner & followers (private)
                                        3Entire company (shared)

                                        Values

                                        1

                                        3

                                        owner_id

                                        integer

                                        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

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

                                            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

                                              ID of the product

                                              follower_id

                                              integer

                                              required

                                              ID of the follower

                                              Response
                                              200

                                              Deletes a follower from a Product

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

                                                Subscribe to Pipedrive’s Developer Newsletter