openapi: 3.0.1
info:
title: Pipedrive API v1 Activities DealProducts API
version: 1.0.0
description: 'Activities are appointments/tasks/events on a calendar that can be associated with a deal, a lead, a person and an organization. Activities can be of different type (such as call, meeting, lunch or a custom type - see ActivityTypes object) and can be assigned to a particular user. Note that activities can also be created without a specific date/time.
'
servers:
- url: https://api.pipedrive.com/v1
tags:
- name: DealProducts
description: 'Deal products are goods or services attached to a deal. Each deal product links a product to a deal with configurable quantity, pricing, and discounts, and contributes to the total value of the deal.
'
paths:
/deals/products:
get:
summary: Get deal products of several deals
description: Returns data about products attached to deals
x-tool-description: Retrieves product attachments across multiple deals (up to 100 IDs) in single request. Essential for bulk product analysis, revenue calculations, sales analytics, and commission calculations across deal portfolios.
x-token-cost: 10
operationId: getDealsProducts
tags:
- DealProducts
security:
- api_key: []
- oauth2:
- products:read
- products:full
- deals:read
- deals:full
parameters:
- in: query
name: deal_ids
required: true
schema:
type: array
items:
type: integer
description: An array of integers with the IDs of the deals for which the attached products will be returned. A maximum of 100 deal IDs can be provided.
- in: query
name: cursor
required: false
schema:
type: string
description: For pagination, the marker (an opaque string value) representing the first item on the next page
- in: query
name: limit
description: 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.
schema:
type: integer
example: 100
- in: query
name: sort_by
description: 'The field to sort by. Supported fields: `id`, `deal_id`, `add_time`, `update_time`, `order_nr`.'
schema:
type: string
default: id
enum:
- id
- deal_id
- add_time
- update_time
- order_nr
- in: query
name: sort_direction
description: 'The sorting direction. Supported values: `asc`, `desc`.'
schema:
type: string
default: asc
enum:
- asc
- desc
responses:
'200':
description: List of products attached to deals
content:
application/json:
schema:
title: GetDealsProductsResponse
type: object
properties:
success:
type: boolean
description: If the response is successful or not
data:
type: array
description: Array containing data for all products attached to deals
items:
allOf:
- type: object
properties:
id:
type: integer
description: The ID of the deal-product (the ID of the product attached to the deal)
sum:
type: number
description: The sum of all the products attached to the deal
tax:
type: number
description: The product tax
deal_id:
type: integer
description: The ID of the deal
name:
type: string
description: The product name
product_id:
type: integer
description: The ID of the product
product_variation_id:
type: integer
nullable: true
description: The ID of the product variation
order_nr:
type: integer
nullable: true
description: The order number of the product within the deal
add_time:
type: string
description: The date and time when the product was added to the deal
update_time:
type: string
description: The date and time when the deal product was last updated
comments:
type: string
description: The comments of the product
currency:
type: string
description: The currency associated with the deal product
discount:
type: number
default: 0
description: The value of the discount. The `discount_type` field can be used to specify whether the value is an amount or a percentage
discount_type:
type: string
enum:
- percentage
- amount
default: percentage
description: The type of the discount's value
quantity:
type: integer
description: The quantity of the product
item_price:
type: number
description: The price value of the product
tax_method:
type: string
enum:
- exclusive
- inclusive
- none
description: The tax option to be applied to the products. When using `inclusive`, the tax percentage will already be included in the price. When using `exclusive`, the tax will not be included in the price. When using `none`, no tax will be added. Use the `tax` field for defining the tax percentage amount. By default, the user setting value for tax options will be used. Changing this in one product affects the rest of the products attached to the deal
is_enabled:
type: boolean
description: Whether this product is enabled for the deal
default: true
- type: object
properties:
billing_frequency:
default: one-time
type: string
enum:
- one-time
- annually
- semi-annually
- quarterly
- monthly
- weekly
description: 'Only available in Growth and above plans
How often a customer is billed for access to a service or product
To set `billing_frequency` different than `one-time`, the deal must not have installments associated
A deal can have up to 20 products attached with `billing_frequency` different than `one-time`
'
- type: object
properties:
billing_frequency_cycles:
default: null
type: integer
nullable: true
description: 'Only available in Growth 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`
When `billing_frequency` is set to `weekly`, this field cannot 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 208
'
- type: object
properties:
billing_start_date:
default: null
type: string
format: YYYY-MM-DD
nullable: true
description: 'Only available in Growth and above plans
The billing start date. Must be between 10 years in the past and 10 years in the future
'
additional_data:
type: object
description: Pagination related data
properties:
next_cursor:
type: string
description: The first item on the next page. The value of the `next_cursor` field will be `null` if you have reached the end of the dataset and there’s no more pages to be returned.
example:
success: true
data:
- id: 3
sum: 90
tax: 0
deal_id: 1
name: Mechanical Pencil
product_id: 1
product_variation_id: null
order_nr: 50
add_time: '2019-12-19T11:36:49Z'
update_time: '2019-12-19T11:36:49Z'
comments: ''
currency: USD
discount: 0
quantity: 1
item_price: 90
tax_method: inclusive
discount_type: percentage
is_enabled: true
billing_frequency: one-time
billing_frequency_cycles: null
billing_start_date: '2019-12-19'
additional_data:
next_cursor: eyJmaWVsZCI6ImlkIiwiZmllbGRWYWx1ZSI6Nywic29ydERpcmVjdGlvbiI6ImFzYyIsImlkIjo3fQ
/deals/{id}/products:
get:
summary: List products attached to a deal
description: Lists products attached to a deal.
x-tool-description: 'Retrieves products attached to deal with detailed information: quantities, prices, and configurations. Essential for deal value analysis, product management, accurate summaries, and pricing calculations.'
x-token-cost: 10
operationId: getDealProducts
tags:
- DealProducts
security:
- api_key: []
- oauth2:
- products:read
- products:full
- deals:read
- deals:full
parameters:
- in: path
name: id
description: The ID of the deal
required: true
schema:
type: integer
- in: query
name: cursor
required: false
schema:
type: string
description: For pagination, the marker (an opaque string value) representing the first item on the next page
- in: query
name: limit
description: 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.
schema:
type: integer
example: 100
- in: query
name: sort_by
description: 'The field to sort by. Supported fields: `id`, `add_time`, `update_time`, `order_nr`.'
schema:
default: id
type: string
enum:
- id
- add_time
- update_time
- order_nr
- in: query
name: sort_direction
description: 'The sorting direction. Supported values: `asc`, `desc`.'
schema:
default: asc
type: string
enum:
- asc
- desc
responses:
'200':
description: List of products attached to deals
content:
application/json:
schema:
title: GetDealsProductsResponse
type: object
properties:
success:
type: boolean
description: If the response is successful or not
data:
type: array
description: Array containing data for all products attached to deals
items:
allOf:
- type: object
properties:
id:
type: integer
description: The ID of the deal-product (the ID of the product attached to the deal)
sum:
type: number
description: The sum of all the products attached to the deal
tax:
type: number
description: The product tax
deal_id:
type: integer
description: The ID of the deal
name:
type: string
description: The product name
product_id:
type: integer
description: The ID of the product
product_variation_id:
type: integer
nullable: true
description: The ID of the product variation
order_nr:
type: integer
nullable: true
description: The order number of the product within the deal
add_time:
type: string
description: The date and time when the product was added to the deal
update_time:
type: string
description: The date and time when the deal product was last updated
comments:
type: string
description: The comments of the product
currency:
type: string
description: The currency associated with the deal product
discount:
type: number
default: 0
description: The value of the discount. The `discount_type` field can be used to specify whether the value is an amount or a percentage
discount_type:
type: string
enum:
- percentage
- amount
default: percentage
description: The type of the discount's value
quantity:
type: integer
description: The quantity of the product
item_price:
type: number
description: The price value of the product
tax_method:
type: string
enum:
- exclusive
- inclusive
- none
description: The tax option to be applied to the products. When using `inclusive`, the tax percentage will already be included in the price. When using `exclusive`, the tax will not be included in the price. When using `none`, no tax will be added. Use the `tax` field for defining the tax percentage amount. By default, the user setting value for tax options will be used. Changing this in one product affects the rest of the products attached to the deal
is_enabled:
type: boolean
description: Whether this product is enabled for the deal
default: true
- type: object
properties:
billing_frequency:
default: one-time
type: string
enum:
- one-time
- annually
- semi-annually
- quarterly
- monthly
- weekly
description: 'Only available in Growth and above plans
How often a customer is billed for access to a service or product
To set `billing_frequency` different than `one-time`, the deal must not have installments associated
A deal can have up to 20 products attached with `billing_frequency` different than `one-time`
'
- type: object
properties:
billing_frequency_cycles:
default: null
type: integer
nullable: true
description: 'Only available in Growth 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`
When `billing_frequency` is set to `weekly`, this field cannot 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 208
'
- type: object
properties:
billing_start_date:
default: null
type: string
format: YYYY-MM-DD
nullable: true
description: 'Only available in Growth and above plans
The billing start date. Must be between 10 years in the past and 10 years in the future
'
additional_data:
type: object
description: Pagination related data
properties:
next_cursor:
type: string
description: The first item on the next page. The value of the `next_cursor` field will be `null` if you have reached the end of the dataset and there’s no more pages to be returned.
example:
success: true
data:
- id: 3
sum: 90
tax: 0
deal_id: 1
name: Mechanical Pencil
product_id: 1
product_variation_id: null
order_nr: 50
add_time: '2019-12-19T11:36:49Z'
update_time: '2019-12-19T11:36:49Z'
comments: ''
currency: USD
discount: 0
quantity: 1
item_price: 90
tax_method: inclusive
discount_type: percentage
is_enabled: true
billing_frequency: one-time
billing_frequency_cycles: null
billing_start_date: '2019-12-19'
additional_data:
next_cursor: eyJmaWVsZCI6ImlkIiwiZmllbGRWYWx1ZSI6Nywic29ydERpcmVjdGlvbiI6ImFzYyIsImlkIjo3fQ
post:
summary: Add a product to a deal
description: Adds a product to a deal, creating a new item called a deal-product.
x-tool-description: Attaches product to deal with configurable quantity, pricing, and discounts. Essential for sales processes, quote generation, and deal composition. Automatically updates deal values and maintains accurate sales tracking.
x-token-cost: 5
operationId: addDealProduct
tags:
- DealProducts
security:
- api_key: []
- oauth2:
- products:full
- deals:full
parameters:
- in: path
name: id
description: The ID of the deal
required: true
schema:
type: integer
requestBody:
content:
application/json:
schema:
title: addDealProductRequest
required:
- item_price
- quantity
- product_id
allOf:
- required:
- product_id
- item_price
- quantity
title: dealProductRequestBody
type: object
properties:
product_id:
type: integer
description: The ID of the product
item_price:
type: number
description: The price value of the product
quantity:
type: number
description: The quantity of the product
tax:
type: number
default: 0
description: The product tax
comments:
type: string
description: The comments of the product
discount:
type: number
default: 0
description: The value of the discount. The `discount_type` field can be used to specify whether the value is an amount or a percentage
is_enabled:
type: boolean
description: 'Whether this product is enabled for the deal
Not possible to disable the product if the deal has installments associated and the product is the last one enabled
Not possible to enable the product if the deal has installments associated and the product is recurring
'
default: true
tax_method:
type: string
enum:
- exclusive
- inclusive
- none
description: The tax option to be applied to the products. When using `inclusive`, the tax percentage will already be included in the price. When using `exclusive`, the tax will not be included in the price. When using `none`, no tax will be added. Use the `tax` field for defining the tax percentage amount. By default, the user setting value for tax options will be used. Changing this in one product affects the rest of the products attached to the deal
discount_type:
type: string
enum:
- percentage
- amount
default: percentage
description: The value of the discount. The `discount_type` field can be used to specify whether the value is an amount or a percentage
product_variation_id:
type: integer
nullable: true
description: The ID of the product variation
- type: object
properties:
billing_frequency:
default: one-time
type: string
enum:
- one-time
- annually
- semi-annually
- quarterly
- monthly
- weekly
description: 'Only available in Growth and above plans
How often a customer is billed for access to a service or product
To set `billing_frequency` different than `one-time`, the deal must not have installments associated
A deal can have up to 20 products attached with `billing_frequency` different than `one-time`
'
- type: object
properties:
billing_frequency_cycles:
default: null
type: integer
nullable: true
description: 'Only available in Growth 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`
When `billing_frequency` is set to `weekly`, this field cannot 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 208
'
- type: object
properties:
billing_start_date:
default: null
type: string
format: YYYY-MM-DD
nullable: true
description: 'Only available in Growth and above plans
The billing start date. Must be between 10 years in the past and 10 years in the future
'
responses:
'201':
description: Add a product to the deal
content:
application/json:
schema:
title: AddDealProductResponse
type: object
properties:
success:
type: boolean
description: If the response is successful or not
data:
allOf:
- type: object
properties:
id:
type: integer
description: The ID of the deal-product (the ID of the product attached to the deal)
sum:
type: number
description: The sum of all the products attached to the deal
tax:
type: number
description: The product tax
deal_id:
type: integer
description: The ID of the deal
name:
type: string
description: The product name
product_id:
type: integer
description: The ID of the product
product_variation_id:
type: integer
nullable: true
description: The ID of the product variation
order_nr:
type: integer
nullable: true
description: The order number of the product within the deal
add_time:
type: string
description: The date and time when the product was added to the deal
update_time:
type: string
description: The date and time when the deal product was last updated
comments:
type: string
description: The comments of the product
currency:
type: string
description: The currency associated with the deal product
discount:
type: number
default: 0
description: The value of the discount. The `discount_type` field can be used to specify whether the value is an amount or a percentage
discount_type:
type: string
enum:
- percentage
- amount
default: percentage
description: The type of the discount's value
quantity:
type: integer
description: The quantity of the product
item_price:
type: number
description: The price value of the product
tax_method:
type: string
enum:
- exclusive
- inclusive
- none
description: The tax option to be applied to the products. When using `inclusive`, the tax percentage will already be included in the price. When using `exclusive`, the tax will not be included in the price. When using `none`, no tax will be added. Use the `tax` field for defining the tax percentage amount. By default, the user setting value for tax options will be used. Changing this in one product affects the rest of the products attached to the deal
is_enabled:
type: boolean
description: Whether this product is enabled for the deal
default: true
- type: object
properties:
billing_frequency:
default: one-time
type: string
enum:
- one-time
- annually
- semi-annually
- quarterly
- monthly
- weekly
description: 'Only available in Growth and above plans
How often a customer is billed for access to a service or product
To set `billing_frequency` different than `one-time`, the deal must not have installments associated
A deal can have up to 20 products attached with `billing_frequency` different than `one-time`
'
- type: object
properties:
billing_frequency_cycles:
default: null
type: integer
nullable: true
description: 'Only available in Growth 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`
When `billing_frequency` is set to `weekly`, this field cannot 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 208
# --- truncated at 32 KB (69 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/pipedrive/refs/heads/main/openapi/pipedrive-dealproducts-api-openapi.yml