openapi: 3.0.1
info:
title: Pipedrive API v1 Activities DealInstallments 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: DealInstallments
description: 'Deal installments are scheduled payment entries attached to a deal, enabling split payment arrangements.
'
paths:
/deals/installments:
get:
summary: List installments added to a list of deals
description: 'Lists installments attached to a list of deals.
Only available in Growth and above plans.
'
x-tool-description: Retrieves payment installments across multiple deals (up to 100 IDs) in single request. Restricted to Growth+ plans. Essential for bulk installment analysis, payment reporting, and enterprise cash flow management.
x-token-cost: 10
operationId: getInstallments
tags:
- DealInstallments
security:
- api_key: []
- oauth2:
- 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 installments 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`, `billing_date`, `deal_id`.'
schema:
default: id
type: string
enum:
- id
- billing_date
- deal_id
- 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 installments added to a deal
content:
application/json:
schema:
title: GetInstallmentsResponse
type: object
properties:
success:
type: boolean
description: If the response is successful or not
data:
type: array
description: Array containing data for all installments added to a deal
items:
type: object
properties:
id:
type: integer
description: The ID of the installment
amount:
type: number
description: The installment amount.
billing_date:
type: string
description: The date on which the installment will be charged.
description:
type: string
description: The name of installment.
deal_id:
type: integer
description: The ID of the deal the installment was added to.
example:
success: true
data:
- id: 1
amount: 10
billing_date: '2025-03-10'
deal_id: 1
description: Delivery Fee
/deals/{id}/installments:
post:
summary: Add an installment to a deal
description: "Adds an installment to a deal.\n\nAn installment can only be added if the deal includes at least one one-time product. \nIf the deal contains at least one recurring product, adding installments is not allowed.\n\nOnly available in Growth and above plans.\n"
x-tool-description: Creates payment installment for deals with one-time products, enabling split payment schedules. Restricted to Growth+ plans and incompatible with recurring products. Essential for enterprise deals and custom payment terms.
x-token-cost: 5
operationId: postInstallment
tags:
- DealInstallments
security:
- api_key: []
- oauth2:
- deals:read
- deals:full
parameters:
- in: path
name: id
description: The ID of the deal
required: true
schema:
type: integer
requestBody:
content:
application/json:
schema:
title: AddInstallmentRequestBody
required:
- description
- amount
- billing_date
properties:
description:
type: string
description: The name of the installment.
amount:
type: number
description: The installment amount. Must be a positive number (excluding 0).
billing_date:
type: string
description: The date on which the installment will be charged. Must be in the format YYYY-MM-DD.
responses:
'200':
description: Installment added to deal
content:
application/json:
schema:
title: AddAInstallmentResponse
type: object
properties:
success:
type: boolean
description: If the response is successful or not
data:
type: object
properties:
id:
type: integer
description: The ID of the installment
amount:
type: number
description: The installment amount.
billing_date:
type: string
description: The date on which the installment will be charged.
description:
type: string
description: The name of installment.
deal_id:
type: integer
description: The ID of the deal the installment was added to.
example:
success: true
data:
id: 1
amount: 10
billing_date: '2025-03-10'
deal_id: 1
description: Delivery Fee
/deals/{id}/installments/{installment_id}:
patch:
summary: Update an installment added to a deal
description: 'Edits an installment added to a deal.
Only available in Growth and above plans.
'
x-tool-description: 'Modifies existing payment installment within deal: amounts, dates, or terms. Restricted to Growth+ plans. Essential for renegotiating schedules, corrections, and maintaining flexible payment arrangements.'
x-token-cost: 5
operationId: updateInstallment
tags:
- DealInstallments
security:
- api_key: []
- oauth2:
- deals:read
- deals:full
parameters:
- in: path
name: id
description: The ID of the deal
required: true
schema:
type: integer
- in: path
name: installment_id
required: true
schema:
type: integer
description: The ID of the installment
requestBody:
content:
application/json:
schema:
title: UpdateInstallmentRequestBody
properties:
description:
type: string
description: The name of the installment.
amount:
type: number
description: The installment amount. Must be a positive number (excluding 0).
billing_date:
type: string
description: The date on which the installment will be charged. Must be in the format YYYY-MM-DD.
responses:
'200':
description: Edited installment.
content:
application/json:
schema:
title: UpdateInstallmentResponse
type: object
properties:
success:
type: boolean
description: If the response is successful or not
data:
type: object
properties:
id:
type: integer
description: The ID of the installment
amount:
type: number
description: The installment amount.
billing_date:
type: string
description: The date on which the installment will be charged.
description:
type: string
description: The name of installment.
deal_id:
type: integer
description: The ID of the deal the installment was added to.
example:
success: true
data:
id: 1
amount: 10
billing_date: '2025-03-10'
deal_id: 1
description: Delivery Fee
delete:
summary: Delete an installment from a deal
description: 'Removes an installment from a deal.
Only available in Growth and above plans.
'
x-tool-description: Removes payment installment from deal by ID, simplifying schedules or correcting structures. Restricted to Growth+ plans. Essential when payment terms change or installments are no longer needed.
x-token-cost: 3
operationId: deleteInstallment
tags:
- DealInstallments
security:
- api_key: []
- oauth2:
- deals:read
- deals:full
parameters:
- in: path
name: id
description: The ID of the deal
required: true
schema:
type: integer
- in: path
name: installment_id
required: true
schema:
type: integer
description: The ID of the installment
responses:
'200':
description: The ID of the deleted installment.
content:
application/json:
schema:
title: DeleteInstallmentResponse
type: object
properties:
success:
type: boolean
description: If the response is successful or not
data:
type: object
properties:
id:
type: integer
description: The ID of the installment that was deleted from the deal
example:
success: true
data:
id: 1
components:
securitySchemes:
basic_authentication:
type: http
scheme: basic
description: Base 64 encoded string containing the `client_id` and `client_secret` values. The header value should be `Basic <base64(client_id:client_secret)>`.
api_key:
type: apiKey
name: x-api-token
in: header
oauth2:
type: oauth2
description: For more information, see https://pipedrive.readme.io/docs/marketplace-oauth-authorization
flows:
authorizationCode:
authorizationUrl: https://oauth.pipedrive.com/oauth/authorize
tokenUrl: https://oauth.pipedrive.com/oauth/token
refreshUrl: https://oauth.pipedrive.com/oauth/token
scopes:
base: Read settings of the authorized user and currencies in an account
deals:read: Read most of the data about deals and related entities - deal fields, products, followers, participants; all notes, files, filters, pipelines, stages, and statistics. Does not include access to activities (except the last and next activity related to a deal)
deals:full: Create, read, update and delete deals, its participants and followers; all files, notes, and filters. It also includes read access to deal fields, pipelines, stages, and statistics. Does not include access to activities (except the last and next activity related to a deal)
mail:read: Read mail threads and messages
mail:full: Read, update and delete mail threads. Also grants read access to mail messages
activities:read: Read activities, its fields and types; all files and filters
activities:full: Create, read, update and delete activities and all files and filters. Also includes read access to activity fields and types
contacts:read: Read the data about persons and organizations, their related fields and followers; also all notes, files, filters
contacts:full: Create, read, update and delete persons and organizations and their followers; all notes, files, filters. Also grants read access to contacts-related fields
products:read: Read products, its fields, files, followers and products connected to a deal
products:full: Create, read, update and delete products and its fields; add products to deals
deal-fields:full: Create, read, update and delete deal fields
product-fields:full: Create, read, update and delete product fields
contact-fields:full: Create, read, update and delete person and organization fields
projects:read: Read projects and its fields, tasks and project templates
projects:full: Create, read, update and delete projects and its fields; add projects templates and project related tasks
users:read: Read data about users (people with access to a Pipedrive account), their permissions, roles and followers
recents:read: Read all recent changes occurred in an account. Includes data about activities, activity types, deals, files, filters, notes, persons, organizations, pipelines, stages, products and users
search:read: Search across the account for deals, persons, organizations, files and products, and see details about the returned results
admin: Allows to do many things that an administrator can do in a Pipedrive company account - create, read, update and delete pipelines and its stages; deal, person and organization fields; activity types; users and permissions, etc. It also allows the app to create webhooks and fetch and delete webhooks that are created by the app
leads:read: Read data about leads and lead labels
leads:full: Create, read, update and delete leads and lead labels
phone-integration: Enables advanced call integration features like logging call duration and other metadata, and play call recordings inside Pipedrive
goals:read: Read data on all goals
goals:full: Create, read, update and delete goals
video-calls: Allows application to register as a video call integration provider and create conference links
messengers-integration: Allows application to register as a messengers integration provider and allows them to deliver incoming messages and their statuses