Guides and Examples
...
Quotes
Custom Fields
14 min
custom fields the nue cpq quote api supports custom fields on quote headers custom field names in the request body map directly to fields on the quote object this allows you to set business specific metadata such as salesforce custom fields, department codes, regions, or approval flags directly when creating or previewing a quote how custom fields work when the api receives a create quote request, it processes all standard fields (like name , opportunityid , products ) through the pricing engine any additional top level fields in the request body are treated as custom fields and stored on the quote header key behaviors behavior details flat json mapping custom field names in the request map directly to quote object fields pricing engine passthrough custom fields survive the pricing engine they are not overwritten during pricing calculations preview and commit custom fields appear in both preview and commit responses supported types string, number, boolean, and date values are all supported line item custom fields not directly supported in the create quote request (see use case 4) authentication const myheaders = new headers(); myheaders append("nue api key", "your api key here"); myheaders append("content type", "application/json"); use case 1 custom fields on quote header (committed) set custom fields as top level properties in the request body when creating a committed quote the field names must match the api names of the custom fields on your quote object (e g , salesforce custom field api names like ruby customtext c ) const myheaders = new headers(); myheaders append("nue api key", "your api key here"); myheaders append("content type", "application/json"); const quotedata = { opportunityid "006xx000001abc123", name "enterprise license custom fields", subscriptionstartdate "2026 01 01", subscriptionenddate "2027 01 01", subscriptiontermdimension "month", subscriptionterm 12, "ruby customtext c" "hello", "ruby customnumber c" 42 50, "ruby customdate c" "2026 06 15", "ruby customcheckbox c" true, products \[ { productsku "nue on salesforce", uom "user/month", quantity 25 } ] }; fetch('https //api nue io/cpq/quotes', { method 'post', headers myheaders, body json stringify(quotedata) }) then(response => response json()) then(result => { console log(`quote id ${result quote id}`); console log(`custom text ${result quote\['ruby customtext c']}`); // "hello" console log(`custom number ${result quote\['ruby customnumber c']}`); // 42 50 console log(`custom date ${result quote\['ruby customdate c']}`); // "2026 06 15" console log(`custom checkbox ${result quote\['ruby customcheckbox c']}`); // true console log(`total amount $${result quote totalamount}`); }) catch(error => console log('error ', error)); curl x post 'https //api nue io/cpq/quotes' \\ h 'nue api key your api key here' \\ h 'content type application/json' \\ d '{ "opportunityid" "006xx000001abc123", "name" "enterprise license custom fields", "subscriptionstartdate" "2026 01 01", "subscriptionenddate" "2027 01 01", "subscriptiontermdimension" "month", "subscriptionterm" 12, "ruby customtext c" "hello", "ruby customnumber c" 42 50, "ruby customdate c" "2026 06 15", "ruby customcheckbox c" true, "products" \[ { "productsku" "nue on salesforce", "uom" "user/month", "quantity" 25 } ] }' the response includes all custom fields on the quote object alongside the standard pricing fields the pricing engine calculates totalamount , listtotalprice , etc , without affecting the custom field values use case 2 custom fields on quote header (preview) custom fields work identically in preview mode they appear in the response even though no data is persisted const quotedata = { opportunityid "006xx000001abc123", name "preview with custom fields", subscriptionstartdate "2026 01 01", subscriptionenddate "2027 01 01", subscriptiontermdimension "month", subscriptionterm 12, "ruby customtext c" "preview value", "ruby customnumber c" 99 99, "ruby customdate c" "2026 12 31", products \[ { productsku "nue on salesforce", uom "user/month", quantity 10 } ] }; fetch('https //api nue io/cpq/quotes\ preview', { method 'post', headers myheaders, body json stringify(quotedata) }) then(response => response json()) then(result => { console log(`quote id ${result quote id}`); // null preview mode console log(`custom text ${result quote\['ruby customtext c']}`); // "preview value" console log(`custom number ${result quote\['ruby customnumber c']}`); // 99 99 console log(`custom date ${result quote\['ruby customdate c']}`); // "2026 12 31" console log(`total amount $${result quote totalamount}`); }) catch(error => console log('error ', error)); curl x post 'https //api nue io/cpq/quotes\ preview' \\ h 'nue api key your api key here' \\ h 'content type application/json' \\ d '{ "opportunityid" "006xx000001abc123", "name" "preview with custom fields", "subscriptionstartdate" "2026 01 01", "subscriptionenddate" "2027 01 01", "subscriptiontermdimension" "month", "subscriptionterm" 12, "ruby customtext c" "preview value", "ruby customnumber c" 99 99, "ruby customdate c" "2026 12 31", "products" \[ { "productsku" "nue on salesforce", "uom" "user/month", "quantity" 10 } ] }' the custom fields survive the pricing engine and appear in the preview response since this is preview mode, quote id is null and nothing is persisted use case 3 custom fields with bundle products when the pricing engine processes bundles, it calculates list prices, discounts, and totals for parent and child line items custom fields on the quote header are not affected by these calculations they pass through untouched const quotedata = { opportunityid "006xx000001abc123", name "bundle quote with custom fields", subscriptionstartdate "2026 01 01", subscriptionenddate "2027 01 01", subscriptiontermdimension "month", subscriptionterm 12, "ruby customtext c" "bundle deal", "ruby customnumber c" 1500 00, "ruby customdate c" "2026 03 01", discount 10, products \[ { productsku "enterprise bundle", uom "license/month", quantity 50, addons \[ { productsku "addon support", uom "license/month", quantity 1 }, { productsku "addon storage", uom "gb/month", quantity 200 } ] } ] }; fetch('https //api nue io/cpq/quotes\ preview', { method 'post', headers myheaders, body json stringify(quotedata) }) then(response => response json()) then(result => { // custom fields preserved after bundle pricing console log(`custom text ${result quote\['ruby customtext c']}`); // "bundle deal" console log(`custom number ${result quote\['ruby customnumber c']}`); // 1500 00 console log(`custom date ${result quote\['ruby customdate c']}`); // "2026 03 01" // pricing fields calculated normally console log(`total amount $${result quote totalamount}`); console log(`discount ${result quote discount}%`); }) catch(error => console log('error ', error)); curl x post 'https //api nue io/cpq/quotes\ preview' \\ h 'nue api key your api key here' \\ h 'content type application/json' \\ d '{ "opportunityid" "006xx000001abc123", "name" "bundle quote with custom fields", "subscriptionstartdate" "2026 01 01", "subscriptionenddate" "2027 01 01", "subscriptiontermdimension" "month", "subscriptionterm" 12, "ruby customtext c" "bundle deal", "ruby customnumber c" 1500 00, "ruby customdate c" "2026 03 01", "discount" 10, "products" \[ { "productsku" "enterprise bundle", "uom" "license/month", "quantity" 50, "addons" \[ { "productsku" "addon support", "uom" "license/month", "quantity" 1 }, { "productsku" "addon storage", "uom" "gb/month", "quantity" 200 } ] } ] }' the pricing engine calculates bundle totals, applies the 10% header discount to all eligible lines, and returns the custom fields unchanged on the quote header use case 4 line item custom fields (workaround) custom fields on individual quote line items are not directly supported in the create quote request this is a current feature gap line item custom fields require a two step workflow step 1 create the quote using post /cpq/quotes (commit mode) to get the quote id and line item ids step 2 update individual line items with custom fields using the standard nue api (e g , graphql mutation or record update endpoint) // step 1 create the quote const quotedata = { opportunityid "006xx000001abc123", name "quote with line item custom fields", subscriptionstartdate "2026 01 01", subscriptionenddate "2027 01 01", subscriptiontermdimension "month", subscriptionterm 12, products \[ { productsku "nue on salesforce", uom "user/month", quantity 10 }, { productsku "nue platform", uom "user/year", quantity 5 } ] }; const createresponse = await fetch('https //api nue io/cpq/quotes', { method 'post', headers myheaders, body json stringify(quotedata) }); const created = await createresponse json(); const quoteid = created quote id; const lineitemid = created quotelineitems\[0] id; console log(`quote id ${quoteid}`); console log(`first line item id ${lineitemid}`); // step 2 update the line item with custom fields via the standard api // use the quote line item update endpoint or graphql mutation \# step 1 create the quote curl x post 'https //api nue io/cpq/quotes' \\ h 'nue api key your api key here' \\ h 'content type application/json' \\ d '{ "opportunityid" "006xx000001abc123", "name" "quote with line item custom fields", "subscriptionstartdate" "2026 01 01", "subscriptionenddate" "2027 01 01", "subscriptiontermdimension" "month", "subscriptionterm" 12, "products" \[ { "productsku" "nue on salesforce", "uom" "user/month", "quantity" 10 }, { "productsku" "nue platform", "uom" "user/year", "quantity" 5 } ] }' \# step 2 use the returned quote id and line item ids to update custom fields \# via the standard nue record update api or graphql mutation custom field summary behavior supported notes quote header custom fields (commit) yes include as top level properties in request body quote header custom fields (preview) yes fields appear in response, not persisted preserved during bundle pricing yes pricing engine does not overwrite custom fields preserved during discount calculation yes custom fields are independent of discount logic line item custom fields (direct) no not supported in create quote request line item custom fields (two step) yes create quote first, then update line items via standard api field naming conventions convention example notes salesforce custom fields ruby customtext c use the full api name including namespace prefix and c suffix standard custom fields customfield1 use camelcase for non salesforce custom fields date format "2026 06 15" use iso 8601 date format (yyyy mm dd) number format 42 50 use standard json number format boolean format true / false use json boolean values important notes custom field names must not conflict with standard field names (e g , avoid using name , discount , products , opportunityid ) if a custom field name matches a standard field, the standard field behavior takes precedence custom fields that do not exist on the quote object in your org are silently ignored during commit but still appear in preview responses