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
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:
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
- After updating, open the document in the PandaDoc web app and verify that quote items, pricing, and sections reflect the changes.
- Call Document Details again to confirm the updated quote structure matches your intent.
Related
- Working with Pricing Tables -- pricing table operations
- Working with Tables -- managing regular table content
- Update Quote API reference -- complete endpoint parameters
Updated 7 days ago