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

Returns data about all products.

API v1
API v2

Endpoint is in beta

Request
GET

/api/v2/products

Query parameters

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.

Response
200

OK

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

      Search products

      Copy link

      Searches all products by name, code and/or custom fields. This endpoint is a wrapper of /v1/itemSearch with a narrower OAuth scope.

      API v1
      API v2

      Endpoint is in beta

      Request
      GET

      /api/v2/products/search

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

      Response
      200

      OK

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

          Get one product

          Copy link

          Returns data about a specific product.

          API v1
          API v2

          Endpoint is in beta

          Request
          GET

          /api/v2/products/{id}

          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

            Returns data about deals that have a product attached to it.

            API v1
            Request
            GET

            /v1/products/{id}/deals

            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

                  Lists files associated with a product.

                  API v1
                  Request
                  GET

                  /v1/products/{id}/files

                  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

                      Lists the followers of a product.

                      API v1
                      Request
                      GET

                      /v1/products/{id}/followers

                      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

                          Lists users permitted to access a product.

                          API v1
                          Request
                          GET

                          /v1/products/{id}/permittedUsers

                          Path parameters

                          id

                          integer

                          required

                          The ID of the product

                          Response
                          200

                          OK

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

                            Get all product variations

                            Copy link

                            Returns data about all product variations.

                            API v2

                            Endpoint is in beta

                            Request
                            GET

                            /api/v2/products/{id}/variations

                            Path parameters

                            id

                            integer

                            required

                            The ID of the product

                            Query parameters

                            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.

                            Response
                            200

                            OK

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

                                Add a product

                                Copy link

                                Adds a new product to the Products inventory. For more information, see the tutorial for adding a product.

                                API v1
                                API v2

                                Endpoint is in beta

                                Request
                                POST

                                /api/v2/products

                                Body parameters

                                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.

                                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

                                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

                                Response
                                201

                                Created

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

                                  Add a follower to a product

                                  Copy link

                                  Adds a follower to a product.

                                  API v1
                                  Request
                                  POST

                                  /v1/products/{id}/followers

                                  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
                                    • { ... }

                                    Add a product variation

                                    Copy link

                                    Adds a new product variation.

                                    API v2

                                    Endpoint is in beta

                                    Request
                                    POST

                                    /api/v2/products/{id}/variations

                                    Path parameters

                                    id

                                    integer

                                    required

                                    The ID of the product

                                    Body parameters

                                    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.

                                    Response
                                    201

                                    Created

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

                                      Update a product

                                      Copy link

                                      Updates product data.

                                      API v1
                                      API v2

                                      Endpoint is in beta

                                      Request
                                      PATCH

                                      /api/v2/products/{id}

                                      Path parameters

                                      id

                                      integer

                                      required

                                      The ID of the product

                                      Body parameters

                                      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.

                                      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

                                      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

                                      Response
                                      200

                                      OK

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

                                        Update a product variation

                                        Copy link

                                        Updates product variation data.

                                        API v2

                                        Endpoint is in beta

                                        Request
                                        PATCH

                                        /api/v2/products/{id}/variations/{product_variation_id}

                                        Path parameters

                                        id

                                        integer

                                        required

                                        The ID of the product

                                        product_variation_id

                                        integer

                                        required

                                        The ID of the product variation

                                        Body parameters

                                        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.

                                        Response
                                        200

                                        OK

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

                                          Delete a product

                                          Copy link

                                          Marks a product as deleted. After 30 days, the product will be permanently deleted.

                                          API v1
                                          API v2

                                          Endpoint is in beta

                                          Request
                                          DELETE

                                          /api/v2/products/{id}

                                          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

                                            Deletes a follower from a product.

                                            API v1
                                            Request
                                            DELETE

                                            /v1/products/{id}/followers/{follower_id}

                                            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
                                              • { ... }

                                              Delete a product variation

                                              Copy link

                                              Deletes a product variation.

                                              API v2

                                              Endpoint is in beta

                                              Request
                                              DELETE

                                              /api/v2/products/{id}/variations/{product_variation_id}

                                              Path parameters

                                              id

                                              integer

                                              required

                                              The ID of the product

                                              product_variation_id

                                              integer

                                              required

                                              The ID of the product variation

                                              Response
                                              200

                                              OK

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

                                                Subscribe to Pipedrive’s Developer Newsletter