Change Order Data Reference

this comprehensive reference covers all change order related data structures, field definitions, behaviors, and requirements in the nue self service api change orders allow you to modify existing subscriptions without creating new orders overview change orders modify existing subscriptions and support various types of modifications each change type has specific behavior and requirements all change orders start as draft previews before activation, allowing you to see the pricing impact before committing to changes core change order concepts asset based changes target specific subscriptions using their asset numbers (sub xxxxxx) delta behavior some changes (updatequantity, updateterm) add to current values preview mode all change orders can be previewed before activation pricing impact see billing adjustments and prorated charges flexible timing control when changes take effect change order types and behaviors complete change order types reference updatequantity delta quantity increase/decrease behavior adds or subtracts from the current subscription quantity current quantity 5 users updatequantity with quantity 3 result 8 users total (5 + 3) use cases adding more user seats to an existing subscription reducing seats when team size decreases scaling usage based on business growth { "changetype" "updatequantity", "assetnumber" "sub 00000279", "quantity" 3, // delta adds 3 to current quantity "startdate" "2025 02 01" } required fields quantity , startdate updateterm delta term extension behavior adds months to the current subscription term current term 12 months remaining updateterm with term 6 result 18 months total (12 + 6) use cases extending subscription length before renewal adding time for contract amendments accommodating payment schedule changes { "changetype" "updateterm", "assetnumber" "sub 00000279", "term" 6 // delta adds 6 months to current term } required fields term optional fields startdate renew subscription renewal behavior extends the subscription for a new term period starting from the current subscription end date use cases annual subscription renewals early renewals with updated terms multi year contract extensions { "changetype" "renew", "assetnumber" "sub 00000279", "renewalterm" 12, // new 12 month term } required fields renewalterm optional fields pricetagcodes upgrade move to higher tier product behavior switches subscription to a more expensive/feature rich product tier use cases moving from basic to premium plan adding features through product upgrade increasing service levels { "changetype" "upgrade", "assetnumber" "sub 00000279", "targetpricebookentryid" "pbe premium plan", "startdate" "2025 02 01" } required fields targetpricebookentryid , startdate optional fields quantity downgrade move to lower tier product behavior switches subscription to a less expensive/fewer features product tier use cases moving from premium to basic plan reducing costs during budget constraints right sizing service levels { "changetype" "downgrade", "assetnumber" "sub 00000279", "targetpricebookentryid" "pbe basic plan", "startdate" "2025 02 01" } required fields targetpricebookentryid , startdate optional fields quantity swap switch to different product (same tier) behavior changes to a different product at the same price/tier level use cases switching between equivalent product variants changing product features without cost impact regional product substitutions { "changetype" "swap", "assetnumber" "sub 00000279", "targetpricebookentryid" "pbe equivalent product", "startdate" "2025 02 01" } required fields targetpricebookentryid , startdate optional fields quantity coterm align subscription end dates behavior adjusts the subscription end date to align with a specific date, typically to synchronize multiple subscriptions use cases aligning multiple subscriptions to same renewal date synchronizing billing cycles contract consolidation { "changetype" "coterm", "assetnumber" "sub 00000279", "cotermdate" "2025 12 31" // new end date } required fields cotermdate cancel end subscription behavior terminates the subscription on the specified date use cases customer cancellations service discontinuation contract terminations { "changetype" "cancel", "assetnumber" "sub 00000279", "cancellationdate" "2025 06 30" } required fields cancellationdate convertfreetrial convert trial to paid behavior converts a free trial subscription to a paid subscription use cases trial to paid conversions promotional period endings pilot program conversions { "changetype" "convertfreetrial", "assetnumber" "sub 00000279", "startdate" "2025 02 01", "term" 12 } required fields startdate , term optional fields quantity reconfigure add bundle add ons behavior adds product options (add ons) from existing bundle subscriptions for self service management includes support for dynamic product options use cases adding analytics modules to existing bundles self service subscription customization mid term bundle adjustments { "changetype" "reconfigure", "assetnumber" "sub 000050", "startdate" "2025 08 26", "addons" \[ { "productoptionid" "a0g7z000007guxuaam", "reconfigureeffectivedate" "2025 08 26", "productoptionquantity" 2 } ] } required fields startdate , addons optional fields none add on structure productoptionid (string, required) product option id for bundle add on reconfigureeffectivedate (string, required) when add on change takes effect productoptionquantity (number, required) quantity of the add on important notes cannot be combined with other change types in a single transaction maximum nesting is one level; deeper configurations not permitted "linktobundlequantity" add ons automatically update quantities with bundle changes real time validation prevents invalid configurations change order fields reference asset changes field type required for description example changetype string all type of change to perform "updatequantity" assetnumber string all subscription identifier (always starts with "sub ") "sub 00000279" quantity number updatequantity delta quantity amount to add/subtract 5 (adds 5 to current) startdate string updatequantity, upgrade, downgrade, swap, convertfreetrial, reconfigure when change takes effect "2025 02 01" term number updateterm delta term months to add to current term 6 (adds 6 months) renewalterm number renew new subscription term in months 12 cotermdate string coterm target end date for alignment "2025 12 31" cancellationdate string cancel when subscription ends "2025 06 30" targetpricebookentryid string upgrade, downgrade, swap salesforce price book entry id to switch to "01uea000008icdgiac" addons array reconfigure array of add on configurations see add on structure change type requirements summary change type required fields optional fields behavior updatequantity quantity , startdate pricetagcodes delta adds to current quantity updateterm term startdate delta adds to current term renew renewalterm pricetagcodes extends subscription coterm cotermdate aligns end dates cancel cancellationdate terminates subscription convertfreetrial startdate , term quantity trial to paid conversion upgrade targetpricebookentryid , startdate quantity move to higher tier downgrade targetpricebookentryid , startdate quantity move to lower tier swap targetpricebookentryid , startdate quantity switch to equivalent reconfigure startdate , addons add bundle add ons important notes delta behavior updatequantity and updateterm are additive they add to the current values, not replace them asset numbers always start with "sub " prefix for subscription identifiers date formats all dates must be in iso 8601 format (yyyy mm dd) price tags price tags are not supported for product relationship changes (upgrade, downgrade, swap) validation target products for upgrade/downgrade/swap must be valid and available reconfigure restrictions reconfigure change orders cannot be combined with other change types in a single transaction change order request structure basic change order request { "options" { "previewinvoice" true, "calculatetax" false }, "assetchanges" \[ { "changetype" "updatequantity", "assetnumber" "sub 00000279", "quantity" 3, "startdate" "2025 02 01" } ] } reconfigure bundle subscription { "options" { "previewinvoice" true, "calculatetax" true }, "assetchanges" \[ { "changetype" "reconfigure", "assetnumber" "sub 000050", "startdate" "2025 08 26", "addons" \[ { "productoptionid" "a0g7z000007guxuaam", "reconfigureeffectivedate" "2025 08 26", "productoptionquantity" 2 } ] } ] } multiple changes in one request { "options" { "previewinvoice" true, "calculatetax" true }, "assetchanges" \[ { "changetype" "updatequantity", "assetnumber" "sub 00000279", "quantity" 5, "startdate" "2025 02 01" }, { "changetype" "upgrade", "assetnumber" "sub 00000280", "targetpricebookentryid" "01uea000008icdgiac", "startdate" "2025 02 15" } ] } validation rules field validation asset numbers must exist and be active subscriptions dates must be valid iso 8601 dates, typically future dates quantities must be positive numbers for updatequantity terms must be positive integers (months) for updateterm and renew target products must be valid price book entries for upgrade/downgrade/swap business logic validation subscription status can only modify active subscriptions date logic start dates must be after subscription start date product compatibility target products must be compatible with current subscription quantity limits must not exceed maximum allowed quantities term restrictions cannot extend beyond maximum allowed term error handling common error codes error code description resolution invalid asset number subscription not found verify asset number exists invalid change type change type not supported use valid change type invalid target product target product not available check product catalog invalid date range date outside allowed range use valid future dates subscription not active cannot modify inactive subscription verify subscription status api endpoints change order management endpoint method purpose /change orders post create change order preview /orders/{changeorderid} post activate change order request options preview options option type default description previewinvoice boolean false generate invoice preview calculatetax boolean false calculate tax amounts activation options option type default description generateinvoice boolean true generate invoice on activation activateinvoice boolean false activate invoice immediately best practices change order planning preview first always create previews to see pricing impact validate assets confirm asset numbers before submission time changes plan start dates to align with billing cycles batch changes group related changes into single requests delta change calculations updatequantity calculate net change needed (target current) updateterm plan additional months needed test scenarios verify calculations in sandbox environment document changes keep audit trail of all modifications error prevention asset verification check subscription status before changes date validation ensure dates are in correct format and range product compatibility verify target products are valid rate limiting implement proper retry logic for api calls this comprehensive reference provides the foundation for implementing robust change order management with the nue self service api for implementation examples, see the getting started and advanced workflows guides