Change Quotes and Orders

this guide introduces lifecycle manager change quotes and orders and provides request examples for every change type the same endpoint — post /cpq/change order — produces either a change quote or a change order depending on options proceedoption , so it covers both see the create change order api reference api references/openapi spec lifecycle json for the full schema lifecycle manager — change orders in lifecycle manager, a change order modifies a customer's existing subscriptions, assets, and entitlements after the initial sale — renewals, quantity and term changes, price adjustments, reconfigurations, cancellations, free trial conversions, field updates, and cross sell (adding brand new products) a single change order can contain multiple changes and can also add new products in the same request every change order is a post /cpq/change order with a top level assetchanges array (the modifications to existing subscriptions) and, optionally, a top level products array (brand new products to add — see cross sell docid\ ussheavdtd5efewfauylq below) change quote vs change order ( proceedoption ) two options fields control the outcome — the container ( proceedoption ) and whether it activates ( activateorder ) proceedoption chooses the container the change lands in createorder — create a change order createquote — create a change quote for review/approval (optionally pass an opportunityid to tie it to an existing opportunity) useexistingorder / useexistingquote — append the change into an existing draft order or quote, identified by containedobjectid activateorder controls activation note that proceedoption "createorder" does not by itself activate — pair it with activateorder to choose draft vs activated proceedoption activateorder result createorder false draft change order createorder true activated change order createquote see note change quote for review/approval (optionally on an opportunityid ) useexistingorder false / true append into an existing draft order ( containedobjectid ); activate when true useexistingquote see note append into an existing quote ( containedobjectid ) quote modes + activateorder the published api contract states that with activateorder true a quote mode is "converted to an order and activated" — but the current runtime does not cleanly do that quote modes return a quote id , skip invoice generation, and the apex activation helper only activates orders treat activateorder on createquote / useexistingquote as version dependent and verify it in your target environment rather than relying on auto activation // draft change order — createorder without activation { "options" { "proceedoption" "createorder", "activateorder" false }, "assetchanges" \[ ] } // change quote tied to an opportunity { "options" { "proceedoption" "createquote", "activateorder" false, "opportunityid" "006ru00000k5by9iaj" // optional associate with opportunity }, "assetchanges" \[ ] } note the published create change order api reference is intentionally minimal/generic — this guide is the practical examples page see the create change order api reference api references/openapi spec lifecycle json for schema field details only cross sell adding new products beyond modifying existing subscriptions through assetchanges , a change order can add brand new products in the same request using the top level products array 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 full details and examples are in new product (cross sell / cancel + replace) docid\ ussheavdtd5efewfauylq change types change type changetype what it does update quantity updatequantity increase or reduce quantity (delta) on a subscription, usage, credit, asset, or entitlement update term updateterm add or subtract months from a subscription's term ( term is a delta) renew renew renew for another term, or convert to evergreen adjust price adjustprice apply a discount % or override the net sales price reconfigure reconfigure change a bundle's add ons/configuration; also covers upgrade/downgrade/swap cancel cancel cancel a subscription immediately or at end of term new product (cross sell) newproduct / top level products add a brand new product or bundle; supports cancel and replace convert free trial convertfreetrial convert a free trial to a paid or evergreen subscription update fields on subscriptions updatefield update editable fields on an existing subscription co term coterm align subscription end dates (see update term docid\ ussheavdtd5efewfauylq ) upgrade / downgrade / swap upgrade / downgrade / swap move a subscription to a different product/edition (see reconfigure docid\ ussheavdtd5efewfauylq ) every assetchanges entry carries changetype and, for all types that modify an existing subscription, an assetnumber newproduct is the only type that does not require an assetnumber update quantity updatequantity isn't limited to subscription seats/licenses — the target assetnumber accepts a subscription number or an asset/entitlement id , and it applies to any quantity bearing line, including usage, credits, assets, and entitlements the quantity field in updatequantity operations is 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" } ] } update term term is a delta the number of months to add (positive) or subtract (negative) from the current subscription term — not the final term updateterm changes the contract length; it does not convert billing frequency (e g monthly → annual) extend subscription term add 6 months to the current subscription post /cpq/change order { "options" { "activateorder" true, "proceedoption" "createorder" }, "assetchanges" \[ { "changetype" "updateterm", "assetnumber" "sub 086067", "term" 6 } ] } extend the term by a year add 12 months to the current term because term is a delta, this extends the contract by a year — it does not change the billing frequency post /cpq/change order { "options" { "activateorder" true, "proceedoption" "createorder" }, "assetchanges" \[ { "changetype" "updateterm", "assetnumber" "sub 086067", "term" 12 } ] } co terminate subscriptions use changetype "coterm" with a cotermdate to align one or more subscriptions to the same end 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" } ] } renew 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 a fixed term to an evergreen subscription post /cpq/change order { "options" { "activateorder" true, "proceedoption" "createorder" }, "assetchanges" \[ { "changetype" "renew", "assetnumber" "sub 086067", "switchtoevergreen" true } ] } adjust price percentage discount apply a 20% discount to a subscription (optionally cascading to bundle children) post /cpq/change order { "options" { "activateorder" true, "proceedoption" "createorder" }, "assetchanges" \[ { "changetype" "adjustprice", "assetnumber" "sub 086067", "startdate" "2024 01 01", "discount" { "discountpercentage" 20, "applytochildren" true } } ] } discount applytochildren is not limited to the targeted line — when set on a bundle parent, the percentage discount cascades to the bundle's child subscriptions as well leave it off (or false ) to discount only the line named by assetnumber fixed price override set a specific net sales price for a subscription over a date range 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" } ] } true up to quantity tier when a subscription is priced by a quantity tier attribute (for example, total committed amount or number of hosts), set trueupprice true to recompute the line to the correct tier for the attribute's current value, without sending a discount or a fixed price post /cpq/change order { "options" { "activateorder" true, "proceedoption" "createorder" }, "assetchanges" \[ { "changetype" "adjustprice", "assetnumber" "sub 086067", "trueupprice" true, "startdate" "2024 01 01" } ] } over rest, a true up does not cascade to bundle children the single call applytochildren cascade for trueupprice is available on the apex global method only; the cpq rest api does not forward it yet to true up a bundle over rest, send a separate trueupprice adjustprice for the parent and one for each child subscription (the nested discount applytochildren shown under percentage discount is unaffected and still cascades a percentage change ) reconfigure reconfigure is a parent operation its nested addonchanges may contain the supported add on operations, but the same bundle, its parent, or its child subscriptions must not also be targeted by separate top level asset changes in the same request do not combine a top level reconfigure with other top level change types against the same subscription tree reconfigure does not auto derive the diff for you — you submit the concrete add on deltas yourself in addonchanges , and apex prices and persists what it receives the supported add on change types are exactly updatequantity , cancel , and newproduct adding add ons to a bundle 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 add on 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" } ] } ] } upgrade, downgrade & swap move a subscription to a different product/edition with changetype "upgrade" , "downgrade" , or "swap" , targeting the new product via targetpricebookentryid all three share the same request shape — the changetype value is the only difference; the direction (is the target really higher/lower?) is validated by the engine for a standalone product , targetpricebookentryid + startdate is all you need post /cpq/change order { "options" { "activateorder" true, "proceedoption" "createorder" }, "assetchanges" \[ { "changetype" "upgrade", "assetnumber" "sub 086067", "targetpricebookentryid" "01uru000004syy8iak", "startdate" "2024 01 15" } ] } quantity is not allowed on upgrade/downgrade/swap uds quantities are fully derived — continuing lines keep their source subscription's quantity, and new lines book at the target bundle's configured defaults sending quantity is rejected with product quantity not allowed to grow or shrink at the same time, add a separate updatequantity change on the same asset in the same request bundles upgrade/downgrade/swap with uds when the source or target is a bundle , the change is resolved by unified data structure (uds) logic the engine maps each source subscription (the bundle root and its child options) onto the target bundle's option slots two extra fields on the asset change control this field type purpose addons array declares the target bundle's configuration — which option slots are filled and with what each entry identifies its product one way ( pricebookentryid or productsku / productname ) and names the slot with productoptionid recursive for nested bundles omit it to let the server build the target from the bundle's default configuration transformations array pins that tell the engine how a specific source subscription maps onto the target when it is not obvious — see ambiguity docid\ ussheavdtd5efewfauylq and convergence docid\ ussheavdtd5efewfauylq below if the target bundle has a required feature whose options aren't satisfiable by defaults, a bare u/d/s (no addons ) is rejected with feature option count out of range — supply addons to choose the option(s) post /cpq/change order { "options" { "activateorder" false, "proceedoption" "createorder" }, "assetchanges" \[ { "changetype" "upgrade", "assetnumber" "sub 000014", // source bundle subscription (e g nue star edition) "targetpricebookentryid" "01uru0000essntl", // target bundle (e g nue essential package) "startdate" "2026 10 01", "addons" \[ { "productoptionid" "a0qru000pricebldr", // target slot "price builder" "pricebookentryid" "01uru000pricebldr" } ] } ] } when a bundle transforms, any source child option that has no matching slot in the target bundle is cancelled — the commit response reports it in messages as source cancelled (e g source sub 000015 has no candidate on the target and is cancelled ) this is expected; plan for child lines to drop when the target bundle is narrower than the source preview → resolve → commit for any non trivial bundle change, preview first post /cpq/change order\ preview takes the same request body but persists nothing and returns per source pricing — or, when a source can't be mapped unambiguously, an ambiguities\[] block instead of pricing post /cpq/change order\ preview // same body as the commit request preview tolerates ambiguity — it returns http 200 with ambiguities\[] (and a null pricesummary for that source) commit does not — if you post /cpq/change order with an unresolved source, it is refused with http 409 resolution required and the same ambiguities payload the loop is preview → read the candidates → pin each unresolved source with a transformations entry → commit resolving ambiguity (one source, many targets) an ambiguity (a "tie") is when a single source subscription could map to more than one slot in the target bundle the engine won't guess a preview surfaces the choices // response from post /cpq/change order\ preview { "results" \[ { "sourceassetnumber" "sub 000019", // the source the rep must resolve "assetnumber" "sub 000018", "pricesummary" null, // no price until the tie is resolved "ambiguities" \[ { "sourceassetnumber" "sub 000019", "sourceproductname" "quickbooks integration", "candidates" \[ { "targetproductoptionid" "a0qru000integprem", "targetpricebookentryid" "01uru000integprem", "targetproductname" "premium integrations", "changetype" "upgrade", "targetkind" "bundle", "listprice" 30 0, "recommended" true }, { "targetproductoptionid" "a0qru000integstd", "targetpricebookentryid" "01uru000integstd", "targetproductname" "standard integrations", "changetype" "swap", "targetkind" "bundle", "listprice" 9 9, "recommended" false } ] } ] } ] } pick a candidate and echo it back as a transformations pin keyed by the same sourceassetnumber , then commit a pin identifies its target exactly one way — either explicit ( targetproductoptionid + targetpricebookentryid together) or by values ( uom / custompricingattributes / billingtiming ); sending both is rejected with transformation identity conflict post /cpq/change order { "options" { "activateorder" true, "proceedoption" "createorder" }, "assetchanges" \[ { "changetype" "upgrade", "assetnumber" "sub 000018", "targetpricebookentryid" "01uru000targetbndl", "startdate" "2026 10 01", "transformations" \[ { "sourceassetnumber" "sub 000019", // resolve the ambiguous source… "targetproductoptionid" "a0qru000integprem", // …onto the chosen slot "targetpricebookentryid" "01uru000integprem" } ] } ] } convergence (many sources, one target) convergence is the opposite of a tie several source subscriptions legitimately map onto the same target slot and merge into one line for example, a customer holds two separate integration add ons — quickbooks integration and nue on salesforce — and the target bundle consolidates both under a single nue platform option both sources converge onto that one slot unlike an ambiguity, convergence isn't a tie to break — each source maps to that shared slot deterministically you express it by sending one pin per source, all naming the same target (converging pins from different sources are explicitly valid) post /cpq/change order { "options" { "activateorder" true, "proceedoption" "createorder" }, "assetchanges" \[ { "changetype" "upgrade", "assetnumber" "sub 000018", // the source bundle root "targetpricebookentryid" "01uru000targetbndl", "startdate" "2026 10 01", "transformations" \[ { "sourceassetnumber" "sub 000019", // quickbooks integration "targetproductoptionid" "a0qru000nueplatform", "targetpricebookentryid" "01uru000nueplatform" }, { "sourceassetnumber" "sub 000020", // nue on salesforce "targetproductoptionid" "a0qru000nueplatform", // same target slot → they converge "targetpricebookentryid" "01uru000nueplatform" } ] } ] } on commit, the two source subscriptions are credited/updated and the target nue platform line carries the merged result — the engine converges them onto the single slot rather than creating two lines as always, any source option that lands on no target slot is cancelled and reported via source cancelled cancel immediate cancellation cancel a 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 term post /cpq/change order { "options" { "activateorder" true, "proceedoption" "createorder" }, "assetchanges" \[ { "changetype" "cancel", "assetnumber" "sub 086067", "cancellationdate" "2024 12 31" } ] } new product (cross sell / cancel + replace) there are two ways to add brand new products as part of a change order the top level products array — the same shape and behavior as adding products on a new quote, with metrics rolling up into the change order header best for straightforward cross sell and cancel and replace the newproduct change type inside assetchanges — for adding a product/bundle alongside other asset changes, including full bundle hierarchies with configured and dynamic add ons when to use products\[] vs newproduct use… when top level products\[] straightforward cross sell or cancel and replace; you want the new quote product shape (resolve by productsku / productname , discounts, price tags) with header metric rollup recommended default newproduct in assetchanges you need to add into a bundle's add on slots ( productoptionid ), reference an explicit pricebookentryid , or use newproduct specific fields alongside other asset changes a newproduct asset change must be accompanied by at least one other change (it cannot be the only change), and newproduct is the only change type that does not require an assetnumber most builds also expect a non empty assetchanges even when using top level products\[] (a products only request may be rejected), but this is deployment dependent — confirm it in your target environment adding products via the products array (cross sell) 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 uses the new product request shape and supports the fields accepted by the deployed api version — productsku / productname (or productoptionid to target a specific bundle option slot), quantity , startdate / enddate , subscriptionterm , paymentterm , cotermasset (to co terminate the new line with an existing subscription), and nested addons verify discount, price tag, and dynamic add on behavior in your target environment — these have had api layer limitations on the change order products\[] path (see the discounts note below) 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", "renewalterm" 12 } ], "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", "cancellationdate" "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" } ] } ] on the change order products\[] path, discount , discountamount , netsalesprice , and pricetags follow the new quote product shape, but line level discounts and price tags are conditionally supported and have had api layer limitations (and preview defects) depending on the deployed version — verify them in your target environment before relying on them when they do apply, the resulting line metrics roll up into the change order header alongside the change itself the newproduct change type (bundles & add ons) use the newproduct change type inside assetchanges to add a standalone product or a full bundle hierarchy alongside other asset changes the new product's term can be set explicitly ( term ) or co termed with an existing subscription ( cotermasset ) important newproduct changes must be accompanied by at least one other change in the same request (e g , cancel, updatequantity, renew) 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 aligns 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 } ] } ] } convert free trial 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 trial to evergreen convert a trial directly to an 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 } ] } update fields on subscriptions update editable fields on an existing subscription without changing its commercial terms — for example, updating the description or a custom field use changetype "updatefield" with the target assetnumber and a fieldstoupdate list of { fieldapiname, newvalue } pairs values are always provided as strings and are coerced to the field's type on the salesforce side an optional startdate sets the effective date, and applytochildren cascades the update to a bundle's child subscriptions updatefield is currently documented and tested as a standalone change type — send it on its own, not mixed with other change types (e g adjustprice , updatequantity ) in the same request updatefield is deployment dependent it requires the corresponding backend and salesforce metadata in the target environment (e g the change type picklist value and any referenced fields); older rest deployments may not support it or may reject the request at validation before it reaches apex as of july 2026 some environments still have a registration gap — the change type picklist value or the rest route for updatefield may be missing even where the underlying apex is present — so confirm support in your target environment before relying on it field api names must be org qualified on a namespaced org (e g ruby billingperiod c ) — an unqualified name is ignored updatefield fields field type required description changetype string yes must be "updatefield" assetnumber string yes subscription (asset) number to update startdate date no effective date of the field update applytochildren boolean no cascade the update to the subscription's bundle children fieldstoupdate array yes list of fields to set on the subscription fieldstoupdate\[] fieldapiname string yes api name of the field to update (e g "description" ) fieldstoupdate\[] newvalue string yes new value to set, as a string (coerced to the field's type) update one or more fields post /cpq/change order { "options" { "activateorder" true, "proceedoption" "createorder" }, "assetchanges" \[ { "changetype" "updatefield", "assetnumber" "sub 086067", "startdate" "2026 08 01", "fieldstoupdate" \[ { "fieldapiname" "description", "newvalue" "renewed per q3 amendment" }, { "fieldapiname" "po number c", "newvalue" "po 2026 0042" } ] } ] }