How to Update Quotes via API

Update quote sections, items, and pricing in PandaDoc documents via the API using data from a CRM or other external system.

Problem

You need to update the pricing, items, or structure of a quote in an existing PandaDoc document -- for example, syncing product data from a CRM into a document's quote section via the API.

Prerequisites

  • A document with an existing quote placeholder (from a template that includes a quote, or a quote block added through the UI)
  • A PandaDoc API key or OAuth token

Solution

Step 1: Retrieve the quote structure

Call Document Details to get the id and structure of the existing quote. You'll need section and item IDs to update specific parts without losing existing data.

Step 2: Build the update payload

Pass a sections object in the Update Quote request. The example below shows the fields you can update:

{
    "sections":
    [
        {
            "id": "c51d7cc2-e0d3-4401-bf77-ef4ef02d618c",
            "name": "section 2",
            "items":
            [
                {
                    "id": "d0483d00-c765-4baf-beda-fd9070e867bc",
                    "sku": "coffee_mug",
                    "name": "Coffee Magic Mug",
                    "description": "Meticulously crafted in Italy these classic glass coffee mugs or tea cups will complete any barware collection.",
                    "qty": "30",
                    "price": "20",
                    "cost": "5",
                    "billing_frequency": "annually",
                    "contract_term": 2,
                    "pricing_method": "volume_based_flat",
                    "type": "product",
                    "reference_type": "catalog",
                    "reference_id": "091481df-9c57-7d94-43f3-389e6efc404a",
                    "options":
                    {
                        "qty_editable": true,
                        "selected": true
                    },
                    "custom_columns": {},
                    "multipliers": {},
                    "discounts": {},
                    "fees": {},
                    "taxes": {},
                    "total": "600"
                }
            ],
            "settings":
            {
                "selection_type": "custom",
                "optional": false,
                "selected": true
            }
        }
    ]
}

Step 3: Send the update

PUT the payload to the Update Quote endpoint for your document.

Demo

Updating line item images and the thumbnail

The Update Quote request can update images and the thumbnail using the same format as Document Details returns. To make it brief: the section and item IDs are required and images array contains the list of new images. Empty images array removes existing images, missing images element leaves images intact. The same for the thumbnail field: it contains the link to the thumbnail image, null to remove the thumbnail and absent to leave the thumbnail intact.

{
   "sections" : [
      {
         "id" : "23040190-7092-47f8-ae2f-8cee7e98bdf3",
         "items" : [
            {
               "name" : "A Cool product but with new images",
               "id" : "bad53c3f-8fc2-4363-9d43-f90faf4c61e3",
               "images" : [
                  "https://upload.wikimedia.org/wikipedia/commons/6/68/Theproductandlogo.jpg"
               ],
               "thumbnail" : "https://upload.wikimedia.org/wikipedia/commons/6/68/Theproductandlogo.jpg"
            }
         ]
      }
   ]
}

Limitations

  • Images are rehosted and served from PandaDoc
  • Image size must be less than 10Mb
  • Only jpg, png, gif and webp formats are supported
  • Only 5 new images per request are supported
  • Images must be publicly accessible for the duration of the API call

When you need to add more than 5 images for multiple line items, use multiple API calls. Images that are hosted by PandaDoc already do not count toward the limit.

Removing a section

Any section or item omitted from the payload will be deleted.

Adding a new section

Just include the desired section in the desired place among other sections. Your section must have a unique ID, UUDv4 (random) is a good algorithm to generate one. Adding items to the new section
works the same as for existing sections.

{
    "sections":
    [
        {
            "id": "c51d7cc2-e0d3-4401-bf77-ef4ef02d618c"
        },
        {
            "id": "988c25f6-73ee-4b60-a2ff-23c61a86dfd0",
            "name": "A new section",
            "items": [],
            "settings":
            {
                "selection_type": "custom",
                "optional": false,
                "selected": true
            }
    ]
}

Removing section columns

Any column omitted from the payload will be deleted. Sending columns as null, omitting the columns key or sending an empty array will leave the columns intact. You can retrieve the current list of columns using the document details endpoint or a previous quote update call. You will get a response like this:

{                                                                            
   "sections" : [                                                            
      {                                                                      
         "columns" : [                                                       
            {                                                                
               "formula_expression" : null,                                  
               "header" : "Product",                                         
               "hidden" : false,                                             
               "merge_name" : "Name",                                        
               "name" : "Name"                                               
            },                                                               
            {                                                                
               "formula_expression" : null,                                  
               "header" : "Description",                                     
               "hidden" : false,                                             
               "merge_name" : "Description",                                 
               "name" : "Description"                                        
            },                                                               
            {                                                                
               "formula_expression" : null,                                  
               "header" : "Price",                                           
               "hidden" : false,                                             
               "merge_name" : "Price",                                       
               "name" : "Price"                                              
            },                                                               
            {                                                                
               "formula_expression" : null,                                  
               "header" : "Quantity",                                        
               "hidden" : false,                                             
               "merge_name" : "Quantity",                                    
               "name" : "Quantity"                                           
            },                                                               
            {                                                                
               "formula_expression" : null,                                  
               "header" : "Total",                                           
               "hidden" : false,                                             
               "merge_name" : "Total",                                       
               "name" : "Total"                                              
            },                                                               
            {                                                                
               "formula_expression" : null,                                  
               "header" : "SKU",                                             
               "hidden" : true,                                              
               "merge_name" : "SKU",                                         
               "name" : "SKU"                                                
            },                                                               
            {                                                                
               "formula_expression" : null,                                  
               "header" : "Cost",                                            
               "hidden" : true,                                              
               "merge_name" : "Cost",                                        
               "name" : "Cost"                                               
            },
            {
               "formula_expression" : null,
               "header" : "Discount",
               "hidden" : false,
               "merge_name" : "Discount",
               "name" : "Discount"
            }                                                              
         ],                                                                  
         "id" : "ab1ed473-2794-43c5-995c-ed83d45ce1f8"                       
      }                                                                      
   ]                                                                         
}                                         

You can't remove Sku, Cost, Product, Description, Price, Quantity and Total columns. In the above example you can remove the Discount column by omitting it from the column list in the update call. All line item values for the Discount column will be deleted automatically.

Adding and updating formula columns

Formula columns are recalculated every time the value of referenced columns changes. Currently mathematical operations +, -, * and / are supported and other columns are referenced by wrapping them in {{ and }}. For example, a column displaying the discount as a negative value can be created by using a formula {{Discount}} * -1. The following example adds a new "Total discount" column by calculating the value using a formula {{Price}} * {{Quantity}} * 0.85

{                                                                            
   "sections" : [                                                            
      {                                                                      
         "columns" : [                                                       
            {                                                                
               "formula_expression" : null,                                  
               "header" : "Product",                                         
               "hidden" : false,                                             
               "merge_name" : "Name",                                        
               "name" : "Name"                                               
            },                                                               
            {                                                                
               "formula_expression" : null,                                  
               "header" : "Description",                                     
               "hidden" : false,                                             
               "merge_name" : "Description",                                 
               "name" : "Description"                                        
            },                                                               
            {                                                                
               "formula_expression" : null,                                  
               "header" : "Price",                                           
               "hidden" : false,                                             
               "merge_name" : "Price",                                       
               "name" : "Price"                                              
            },                                                               
            {                                                                
               "formula_expression" : null,                                  
               "header" : "Quantity",                                        
               "hidden" : false,                                             
               "merge_name" : "Quantity",                                    
               "name" : "Quantity"                                           
            },                                                               
            {                                                                
               "formula_expression" : null,                                  
               "header" : "Total",                                           
               "hidden" : false,                                             
               "merge_name" : "Total",                                       
               "name" : "Total"                                              
            },                                                               
            {                                                                
               "formula_expression" : null,                                  
               "header" : "SKU",                                             
               "hidden" : true,                                              
               "merge_name" : "SKU",                                         
               "name" : "SKU"                                                
            },                                                               
            {                                                                
               "formula_expression" : null,                                  
               "header" : "Cost",                                            
               "hidden" : true,                                              
               "merge_name" : "Cost",                                        
               "name" : "Cost"                                               
            },                                                               
            {                                                                
               "formula_expression" : "{{Price}} * {{Quantity}} * 0.85",     
               "header" : "Total Discount",                                  
               "hidden" : false,                                             
               "merge_name" : "TotalDiscount",                               
               "name" : "TotalDiscount"                                      
            }                                                                
         ],                                                                  
         "id" : "ab1ed473-2794-43c5-995c-ed83d45ce1f8"                       
      }                                                                      
   ]                                                                         
}                                         

The response of the endpoint contains the new column and it's value under the formula_columns key:

{                                                                             
   "currency" : "EUR",                                                        
   "id" : "61c894cc-da31-4a03-a204-0c425ae7c1da",                             
   "merge_rules" : [],                                                        
   "sections" : [                                                             
      {                                                                       
         "columns" : [                                                        
            {                                                                 
               "formula_error_code" : null,                                   
               "formula_expression" : null,                                   
               "header" : "Product",                                          
               "hidden" : false,                                              
               "merge_name" : "Name",                                         
               "name" : "Name"                                                
            },                                                                
            {                                                                 
               "formula_error_code" : null,                                   
               "formula_expression" : null,                                   
               "header" : "Description",                                      
               "hidden" : false,                                              
               "merge_name" : "Description",                                  
               "name" : "Description"                                         
            },                                                                
            {                                                                 
               "formula_error_code" : null,                                   
               "formula_expression" : null,                                   
               "header" : "Price",                                            
               "hidden" : false,                                              
               "merge_name" : "Price",                                        
               "name" : "Price"                                               
            },                                                                
            {                                                                 
               "formula_error_code" : null,                                   
               "formula_expression" : null,                                   
               "header" : "Quantity",                                         
               "hidden" : false,                                              
               "merge_name" : "Quantity",                                     
               "name" : "Quantity"                                            
            },                                                                
            {                                                                 
               "formula_error_code" : null,                                   
               "formula_expression" : null,                                   
               "header" : "Total",                                            
               "hidden" : false,                                              
               "merge_name" : "Total",                                        
               "name" : "Total"                                               
            },                                                                
            {                                                                 
               "formula_error_code" : null,                                   
               "formula_expression" : null,                                   
               "header" : "SKU",                                              
               "hidden" : true,                                               
               "merge_name" : "SKU",                                          
               "name" : "SKU"                                                 
            },                                                                
            {                                                                 
               "formula_error_code" : null,                                   
               "formula_expression" : null,                                   
               "header" : "Cost",                                             
               "hidden" : true,                                               
               "merge_name" : "Cost",                                         
               "name" : "Cost"                                                
            },                                                                
            {                                                                 
               "formula_error_code" : null,                                   
               "formula_expression" : "{{Price}} * {{Quantity}} * 0.85",      
               "header" : "Total Discount",                                   
               "hidden" : false,                                              
               "merge_name" : "TotalDiscount",                                
               "name" : "TotalDiscount"                                       
            }                                                                 
         ],                                                                   
         "id" : "ab1ed473-2794-43c5-995c-ed83d45ce1f8",                       
         "items" : [                                                          
            {                                                                 
               "billing_frequency" : null,                                    
               "contract_term" : null,                                        
               "cost" : "0",                                                  
               "custom_columns" : {},                                         
               "description" : "",                                            
               "discounts" : {},                                              
               "external_columns" : {},                                       
               "fees" : {},                                                   
               "formula_columns" : {                                          
                  "Total Discount" : "464.1"                                  
               },                                                             
               "id" : "cb5a3f5b-b8b0-42f2-8158-200d292803ea",                 
               "images" : [],                                                 
               "merged_data" : {                                              
                  "Cost" : "0",                                               
                  "Description" : "",                                         
                  "Images" : [],                                              
                  "Name" : "My beautiful product",                            
                  "Price" : "42",                                             
                  "Quantity" : "13",                                          
                  "SKU" : "1791785087737",                                    
                  "Thumbnail" : null,                                         
                  "TotalDiscount" : "464.1"                                   
               },                                                             
               "multipliers" : {},                                            
               "name" : "My beautiful product",                               
               "options" : {                                                  
                  "qty_editable" : false,                                     
                  "selected" : true                                           
               },                                                             
               "overall_total" : null,                                        
               "price" : "42",                                                
               "pricing_method" : "flat",                                     
               "qty" : "13",                                                  
               "reference_id" : "044e906c-1cdf-459a-a975-25ea8fbe9af5",       
               "reference_type" : "inline",                                   
               "sku" : "1791785087737",                                       
               "taxes" : {},                                                  
               "thumbnail" : null,                                            
               "total" : "546",                                               
               "total_qty" : null,                                            
               "type" : "product"                                             
            }                                                                 
         ],                                                                   
         "name" : null,                                                       
         "settings" : {                                                       
            "data_merge_enabled" : true,                                      
            "optional" : false,                                               
            "selected" : true,                                                
            "selection_type" : "custom"                                       
         },                                                                   
         "summary" : {                                                        
            "custom_fields" : {},                                             
            "discounts" : {},                                                 
            "fees" : {},                                                      
            "one_time_subtotal" : "0",                                        
            "recurring_subtotal" : [],                                        
            "subtotal" : "0",                                                 
            "taxes" : {},                                                     
            "total" : "546",                                                  
            "total_qty" : null,                                               
            "total_section_value" : null                                      
         },                                                                   
         "total" : "546"                                                      
      }                                                                       
   ],                                                                         
   "settings" : {                                                             
      "selection_type" : "custom"                                             
   },                                                                         
   "summary" : {                                                              
      "custom_fields" : {},                                                   
      "discounts" : {},                                                       
      "fees" : {},                                                            
      "one_time_subtotal" : "0",                                              
      "recurring_subtotal" : [],                                              
      "subtotal" : "0",                                                       
      "taxes" : {},                                                           
      "total" : "546",                                                        
      "total_contract_value" : null,                                          
      "total_discount" : null,                                                
      "total_fee" : null,                                                     
      "total_qty" : null,                                                     
      "total_savings" : null,                                                 
      "total_tax" : null                                                      
   },                                                                         
   "total" : "546"                                                            
}                                                                             

Formula columns can be added in the PandaDoc web app by hand as well. The formula_columns key contains columns created both from the web app and by the API. Column formulas can be updated either through the PandaDoc web app or the API as well.

Troubleshooting

Sections or items disappear after update

To preserve a section or item, always pass its id in the payload. Any section or item omitted from the payload will be deleted. To keep an item unchanged, pass just its id:

{
    "sections":
    [
        {
            "id": "c51d7cc2-e0d3-4401-bf77-ef4ef02d618c",
            "name": "Section 1",
            "items": [
                {
                    "id": "3758f0a0-3cb0-4d94-abb5-4c7b7d2013b3"
                },
                {
                    "id": "c5604762-369a-424c-b387-15650e63f032",
                    "name": "New name"
                }
            ]
        },
        {
            "id": "ec79f600-480c-4731-b15c-2d19f0476b4b"
        }
    ]
}

To delete an item, omit it from the payload entirely.

Item order changed unexpectedly

The order of sections and items in the payload determines their order in the document. If you rearrange items in the JSON, they will be reordered in the document.

Verification

  1. After updating, open the document in the PandaDoc web app and verify that quote items, pricing, and sections reflect the changes.
  2. Call Document Details again to confirm the updated quote structure matches your intent.

Related


Did this page help you?