What is changing?

The duration and duration_unit request body and response parameters will be removed from three deal-products endpoints on June 10th, 2024:

• GET /deals/{id}/products
• POST /deals/{id}/products
• PUT /deals/{id}/products/{product_attachment_id}

  <p><b>What is changing?</b></p>
  <p>We’re replacing product durations with a new recurring products feature to allow users to attach products with a recurring billing cycle to deals. Users will be able to see the revenue of recurring products based on the billing frequency, cycles and start dates in reporting and forecasting via the Insights feature. This change should better serve the needs of our customers who sell subscriptions, licenses and recurring products and services.</p>
  <p>New fields are now available for customers who <b>meet both</b> of the terms below:</p>
  <ul>
  	<li>Have a subscription to Advanced plans and above.</li>
    <li>Have previously used durations in the POST and PUT endpoints to edit the billing frequency and billing cycles (for example, a monthly subscription active for 12 months).</li>
  </ul>
  
  <p>Instead of using product durations in product attachments as a time quantity, users can now use a combination of the product attachment quantity and the product unit fields. For example, a service charged by the number of work hours.</p>
  
  <p><b>Migration guide</b></p>
  
  <p>On the API change’s effective date of June 10th, 2024, the product attachments’ <b><code>duration</code></b> and <b><code>duration_unit</code></b> fields will be removed from the API.</p>
  <ul>
  	<li>The product attachment <b><code>duration</code></b> field value will be merged into the <b><code>quantity</code></b> field value where <code>quantity = quantity * duration</code>.</li>
    <li>The <b><code>duration_unit</code></b> values will be lost.</li>
  </ul>
  
  <p>To migrate duration data to the new product subscriptions feature, it’s now possible to move values to the new <b><code>billing frequency</code></b> and <b><code>billing cycles</code></b> product attachment fields through these endpoints:</p>
   <ul>
     <li><code><a href="https://developers.pipedrive.com/docs/api/v1/Deals#addDealProduct" target="blank">POST /deals/{id}/products</a></code></li>
     <li><code><a href="https://developers.pipedrive.com/docs/api/v1/Deals#updateDealProduct" target="blank">PUT /deals/{id}/products/{product_attachment_id}</a></code></li>
  </ul>
  
  <p>The fields are available in beta testing for users subscribed to the <b>Advanced</b> plan and above with previously used durations. Customers who aren’t included in the beta testing group can contact Pipedrive’s support and ask to be included. These are the new fields request body parameters:</p>
  
  <ul>
  	<li><b><code>billing_frequency</code></b></li>
    	<ul>
  			<li>Type: <code><b>string</b></code></li>
    		<li>Description: <code>How often a customer is billed for access to a service or product.</code></li>
            <li>Values: <code><b>one-time</b>, <b>annually</b>, <b>semi-annually</b>, <b>quarterly</b>, <b>monthly</b>, <b>weekly</b></code></li>
            	<ul>
  					<li>Default: <code><b>one-time</b></code></li>
            	</ul>
  		</ul>
    <li><b><code>billing_frequency_cycles</code></b></li>
    	<ul>
  			<li>Type: <code><b>number</b></code></li>
    		<li>Description: <code>The number of times the billing frequency repeats for a product in a deal. It can be set to null if the number of cycles is infinite, in which case the deal value will be incremented with 1 year of cycles.</code></li>
            <li>Values: <code><b>null</b></code> or higher than <code><b>1</b></code>. When billing frequency is set to <code><b>one-time</b></code>, this value must be set to <code><b>null</b></code>.</li>
            	<ul>
  					<li>Default: <code><b>null</b></code></li>
            	</ul>
  		</ul>
  </ul>
  
  <p>Some things to consider when copying the <b><code>duration</code></b> values to the new fields:</p>
  
  <ul>
  	<li>The <b><code>duration</code></b> value should be set to <code><b>1</b></code> so that it’s no longer considered for the deal value.</li>
    <li>The <b>deal value</b> will change if there are <b>amount discounts</b> in either the updated product attachment or additional discounts.</li>
    <li>For <b>companies</b> in the <b>Essential plan</b>, we recommend merging the <b><code>duration</code></b> value with <b><code>quantity</code></b> and updating the product unit with the <b><code>duration_unit</code></b> value.</li>
  </ul>


  <p>If you have any questions or comments, please let us know in <a href="https://devcommunity.pipedrive.com/">the Developer’s Community</a>.</p>

	</div>