Change Quotes and Orders

this guide provides comprehensive examples of different change order scenarios using the revenue lifecycle management apis each example includes both the api request and explanation of the business use case understanding createquote vs createorder when making change order requests, you can choose between two proceedoption values createorder directly creates and activates the change order in salesforce use when you want immediate execution of the change createquote creates a quote in salesforce that can be reviewed and approved before activation use when you need approval workflows when using createquote , you can optionally pass an opportunityid to associate the quote with an existing salesforce opportunity this enables native opportunity management workflows within salesforce // example with createquote and opportunityid { "options" { "activateorder" false, "proceedoption" "createquote", "opportunityid" "006ru00000k5by9iaj" // optional associate with opportunity }, "assetchanges" \[ ] } adding new products to a change order beyond modifying existing subscriptions through assetchanges , a change order can also add brand new products in the same request using the top level products array this is useful for expansion and cross sell motions where you both change existing lines and add new lines in a single atomic change order for each entry in products , the behavior is exactly the same as adding new products in a new quote — same shape as create quote guides and examples/customer lifecycle/cpq revenue lifecycle/quotes/create quote overview\ mdx products, resolved and priced through the same pricing pipeline the products array is additive to assetchanges , which remains required and non empty the one difference is at the header the new products' metrics — arr, cmrr, tcv, and acv — roll up into the change order header together with the metrics of the change itself in other words, the header totals reflect both the assetchanges and the newly added products combined post /cpq/change order { "options" { "activateorder" true, "proceedoption" "createorder" }, "assetchanges" \[ { "changetype" "updatequantity", "assetnumber" "sub 086067", "quantity" 25, "startdate" "2024 01 01" } ], "products" \[ { "productsku" "sku addon 01", "quantity" 5, "subscriptionterm" 12, "subscriptiontermdimension" "months" } ] } each entry supports the full add product field set — productsku / productname (or productoptionid to target a specific bundle option slot), quantity , startdate / enddate , subscriptionterm , netsalesprice or discount , paymentterm , cotermasset (to co terminate the new line with an existing subscription), and nested addons expansion (renew + new product) renew an existing subscription and add a brand new product in the same change order the assetchanges entry renews the existing line; the products entry adds the new line both roll up into the same change order header, so arr, cmrr, tcv, and acv reflect the renewal and the new product combined post /cpq/change order { "options" { "activateorder" true, "proceedoption" "createorder" }, "assetchanges" \[ { "changetype" "renew", "assetnumber" "sub 086067", "subscriptionterm" 12, "subscriptiontermdimension" "months", "startdate" "2026 08 01" } ], "products" \[ { "productsku" "sku addon 01", "quantity" 10, "subscriptionterm" 12, "subscriptiontermdimension" "months" } ] } cancel and replace (swap editions) cancel an existing product or bundle and replace it with a different one in a single change order — for example, replace nue gem edition with nue rise edition the cancel change removes the old subscription; the products entry adds the replacement header metrics (arr, cmrr, tcv, acv) net the cancellation against the replacement post /cpq/change order { "options" { "activateorder" true, "proceedoption" "createorder" }, "assetchanges" \[ { "changetype" "cancel", "assetnumber" "sub 086067", "startdate" "2026 08 01" } ], "products" \[ { "productname" "nue rise edition", "quantity" 100, "subscriptionterm" 36, "subscriptiontermdimension" "months" } ] } when the item being replaced is a bundle, cancelling the original bundle cancels its child lines too, and the replacement bundle's children are added automatically — exactly as in a new quote applying discounts and price tags to new products products added through products accept the same discounting inputs as a new quote provide exactly one of discount (percentage), discountamount (fixed amount), or netsalesprice (explicit unit price) per line, and/or attach pricetags (price and discount tags referenced by code or id ) percentage discount "products" \[ { "productname" "nue rise edition", "quantity" 100, "subscriptionterm" 36, "subscriptiontermdimension" "months", "discount" 15 } ] fixed discount amount "products" \[ { "productsku" "sku addon 01", "quantity" 10, "discountamount" 500 } ] price / discount tags (same as a new quote) "products" \[ { "productname" "nue rise edition", "quantity" 100, "pricetags" \[ { "code" "promo 2026" } ] } ] discount , discountamount , netsalesprice , and pricetags behave identically to adding a product on a new quote the only difference is that the resulting line metrics roll up into the change order header alongside the change itself subscription upgrades basic upgrade upgrade a customer from a basic to premium plan { "options" { "activateorder" true, "proceedoption" "createorder" }, "assetchanges" \[ { "changetype" "upgrade", "assetnumber" "sub 086067", "targetpricebookentryid" "01uru000004syy8iak", "startdate" "2024 01 15" } ] } response { "headerobjectids" \["801xx000003abcd"], "messages" \["subscription sub 086067 upgraded to premium plan"], "assets" \[ { "id" "02ixx000005mnop", "name" "sub 086067", "product" "premium plan", "mrr" 299 00 } ] } quantity changes the quantity field in updatequantity operations represents a delta (change amount), not the final absolute quantity current quantity delta value result 10 seats +25 35 seats 100 licenses 30 70 licenses 50 users +50 100 users seat expansion add 25 more user licenses to an existing subscription (e g , from 10 → 35 seats) post /cpq/change order { "options" { "activateorder" true, "proceedoption" "createorder" }, "assetchanges" \[ { "changetype" "updatequantity", "assetnumber" "sub 086067", "quantity" 25, // delta adds 25 to current quantity (10 + 25 = 35) "startdate" "2024 01 01" } ] } seat reduction reduce quantity by 5 (e g , from 35 → 30 seats) post /cpq/change order { "options" { "activateorder" true, "proceedoption" "createorder" }, "assetchanges" \[ { "changetype" "updatequantity", "assetnumber" "sub 086067", "quantity" 5, // delta reduces current quantity (35 5 = 30) "startdate" "2024 01 01" } ] } bundle reconfiguration adding new products add additional features to an existing bundle post /cpq/change order { "options" { "activateorder" false, "proceedoption" "createquote", "opportunityid" "006ru00000k5by9iaj" }, "assetchanges" \[ { "changetype" "reconfigure", "assetnumber" "sub 086067", "startdate" "2024 01 15", "addonchanges" \[ { "changetype" "newproduct", "productoptionid" "a8fru0000002bomiai", "pricebookentryid" "01uru000004syy7iak", "productoptionquantity" 3, "term" 12 } ] } ] } complex bundle changes multiple changes to a bundle in one operation post /cpq/change order { "options" { "activateorder" true, "proceedoption" "createorder" }, "assetchanges" \[ { "changetype" "reconfigure", "assetnumber" "sub 086067", "startdate" "2024 01 15", "addonchanges" \[ { "changetype" "newproduct", "productoptionid" "a8fru0000002bomiai", "pricebookentryid" "01uru000004syy7iak", "productoptionquantity" 2 }, { "changetype" "updatequantity", "assetnumber" "sub 086068", "productoptionquantitychange" 5 }, { "changetype" "cancel", "assetnumber" "sub 086069", "cancellationdate" "2024 12 31" } ] } ] } price adjustments percentage discount apply a 20% discount to a subscription post /cpq/change order { "options" { "activateorder" true, "proceedoption" "createorder" }, "assetchanges" \[ { "changetype" "adjustprice", "assetnumber" "sub 086067", "startdate" "2024 01 01", "discount" { "discountpercentage" 20, "applytochildren" true } } ] } fixed price override set a specific price for a subscription post /cpq/change order { "options" { "activateorder" true, "proceedoption" "createorder" }, "assetchanges" \[ { "changetype" "adjustprice", "assetnumber" "sub 086067", "netsalesprice" 1200 00, "startdate" "2024 01 01", "enddate" "2024 12 31" } ] } renewal operations standard renewal renew a subscription for another 12 months post /cpq/change order { "options" { "activateorder" true, "proceedoption" "createorder" }, "assetchanges" \[ { "changetype" "renew", "assetnumber" "sub 086067", "renewalterm" 12 } ] } convert to evergreen change from fixed term to evergreen subscription post /cpq/change order { "options" { "activateorder" true, "proceedoption" "createorder" }, "assetchanges" \[ { "changetype" "renew", "assetnumber" "sub 086067", "switchtoevergreen" true } ] } term modifications extend subscription term add 6 months to current subscription post /cpq/change order { "options" { "activateorder" true, "proceedoption" "createorder" }, "assetchanges" \[ { "changetype" "updateterm", "assetnumber" "sub 086067", "term" 6 } ] } convert monthly to annual change billing frequency from monthly to annual post /cpq/change order { "options" { "activateorder" true, "proceedoption" "createorder" }, "assetchanges" \[ { "changetype" "updateterm", "assetnumber" "sub 086067", "term" 12 } ] } co termination align subscription end dates align multiple subscriptions to end on the same date post /cpq/change order { "options" { "activateorder" true, "proceedoption" "createorder" }, "assetchanges" \[ { "changetype" "coterm", "assetnumber" "sub 086067", "cotermdate" "2024 12 31" }, { "changetype" "coterm", "assetnumber" "sub 086068", "cotermdate" "2024 12 31" } ] } cancellations immediate cancellation cancel subscription immediately post /cpq/change order { "options" { "activateorder" true, "proceedoption" "createorder" }, "assetchanges" \[ { "changetype" "cancel", "assetnumber" "sub 086067", "cancellationdate" "2024 01 01" } ] } end of term cancellation cancel at the end of the current billing period post /cpq/change order { "options" { "activateorder" true, "proceedoption" "createorder" }, "assetchanges" \[ { "changetype" "cancel", "assetnumber" "sub 086067", "cancellationdate" "2024 12 31" } ] } free trial conversions convert trial to paid convert a free trial to a paid subscription post /cpq/change order { "options" { "activateorder" true, "proceedoption" "createorder" }, "assetchanges" \[ { "changetype" "convertfreetrial", "assetnumber" "sub 086067", "startdate" "2024 01 15", "term" 12, "overridetrialend" true } ] } convert to evergreen convert trial directly to evergreen subscription post /cpq/change order { "options" { "activateorder" true, "proceedoption" "createorder" }, "assetchanges" \[ { "changetype" "convertfreetrial", "assetnumber" "sub 086067", "startdate" "2024 01 15", "switchtoevergreen" true, "cotermtobundlesubscription" false } ] } new product (cross sell) add a completely new product to the account as part of a change order supports standalone products and full bundle hierarchies with configured and dynamic add ons the new product's term can be set explicitly or co termed with an existing subscription important newproduct changes must be accompanied by at least one other change type (e g , cancel, updatequantity, renew) in the same request newproduct cannot be the only change in a change order newproduct fields field type required description changetype string yes must be "newproduct" pricebookentryid string yes price book entry id identifying the product to add startdate date yes effective start date for the new product quantity decimal yes quantity to add (must be positive) term decimal one of term/cotermasset subscription term in months mutually exclusive with cotermasset cotermasset string one of term/cotermasset existing subscription number (e g sub 000192 ) to co term with the new product's end date will align to this subscription's end date netsalesprice decimal no override the calculated net sales price addons array no bundle add ons to include with the product (see add on structure below) autorenew boolean no whether the subscription should auto renew defaultrenewalterm decimal no renewal term in months when auto renew is enabled billingtiming string no billing timing, e g in advance , in arrears billingperiod string no billing frequency, e g month , year billcycleday string no day of the billing cycle billcyclestartmonth string no starting month for annual billing cycles pricetagids array no price tag ids to apply discounts pricetagcodes array no price tag codes (alternative to ids) description string no custom description customfields object no custom field values to populate on the order product add on structure each add on can contain nested addons , supporting recursive bundle hierarchies field type required description changetype string yes must be "newproduct" productoptionid string yes (configured) product option id for configured add ons pricebookentryid string yes (dynamic) price book entry id for dynamic add ons productoptionquantity decimal yes quantity of the add on subscriptionterm decimal no term in months if different from parent cotermasset string no co term with an existing subscription subscriptionstartdate date no start date if different from parent netsalesprice decimal no override net sales price for this add on billingtiming string no billing timing override billingperiod string no billing period override billcycleday string no bill cycle day override billcyclestartmonth string no bill cycle start month override pricetagids array no price tag ids pricetagcodes array no price tag codes addons array no nested add ons (recursive) customfields object no custom field values basic new product cancel an existing subscription and add a new product with a 12 month term post /cpq/change order { "options" { "activateorder" true, "proceedoption" "createorder" }, "assetchanges" \[ { "changetype" "cancel", "assetnumber" "sub 000192", "cancellationdate" "2025 02 15" }, { "changetype" "newproduct", "pricebookentryid" "01uru000004syy8iak", "startdate" "2025 02 15", "quantity" 3, "term" 12 } ] } new product with bundle add ons add a new bundle product with configured and dynamic add ons post /cpq/change order { "options" { "activateorder" true, "proceedoption" "createorder" }, "assetchanges" \[ { "changetype" "cancel", "assetnumber" "sub 000192", "cancellationdate" "2025 02 15" }, { "changetype" "newproduct", "pricebookentryid" "01uru000004syy8iak", "startdate" "2025 02 15", "quantity" 3, "term" 12, "addons" \[ { "changetype" "newproduct", "productoptionid" "a0jru0000002bomiai", "productoptionquantity" 3 }, { "changetype" "newproduct", "productoptionid" "a0jru0000002boniai", "pricebookentryid" "01uru000004syy7iak", "productoptionquantity" 10 } ] } ] } new product co termed with existing subscription align the new product's end date to an existing subscription instead of specifying a term post /cpq/change order { "options" { "activateorder" true, "proceedoption" "createorder" }, "assetchanges" \[ { "changetype" "cancel", "assetnumber" "sub 000192", "cancellationdate" "2025 02 15" }, { "changetype" "newproduct", "pricebookentryid" "01uru000004syy8iak", "startdate" "2025 02 15", "quantity" 5, "cotermasset" "sub 000200" } ] } new product with price override override the calculated price at both the parent and add on level post /cpq/change order { "options" { "activateorder" false, "proceedoption" "createquote" }, "assetchanges" \[ { "changetype" "cancel", "assetnumber" "sub 000192", "cancellationdate" "2025 02 15" }, { "changetype" "newproduct", "pricebookentryid" "01uru000004syy8iak", "startdate" "2025 02 15", "quantity" 3, "term" 12, "netsalesprice" 450 00, "addons" \[ { "changetype" "newproduct", "productoptionid" "a0jru0000002bomiai", "productoptionquantity" 10, "netsalesprice" 25 00 } ] } ] }