Change 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" \[ ] } 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 } ] } ] }