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) new product (cross sell) add completely new products via the products array alongside assetchanges 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" "01uql000009tsn1yac", "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" "01uql000009tsn2yac", "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" "01uql000009tsn3yac", "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 new product (cross sell) add new products behavior adds a completely new product to the account as part of a change order new products are specified in a separate products array alongside the assetchanges array, not as a change type within assetchanges use cases cross selling additional products to existing customers replacing a cancelled subscription with a different product adding complementary products during mid term changes { "assetchanges" \[ { "changetype" "cancel", "assetnumber" "sub 000192", "cancellationdate" "2025 02 15" } ], "products" \[ { "pricebookentryid" "01uql000009tsn7yac", "quantity" 3, "subscriptionstartdate" "2025 02 15", "subscriptionterm" 12 } ] } required fields pricebookentryid , quantity , subscriptionstartdate , and one of subscriptionterm or cotermasset optional fields autorenew , defaultrenewalterm , billingtiming , billingperiod , billcycleday , billcyclestartmonth , description , pricetagids , pricetagcodes , customfields , addons new product add on structure productoptionid (string, required) product option id for dynamic options, use the composite id {productoptionid} {pricebookentryid} productoptionquantity (number, required) quantity of the add on subscriptionterm (number, optional) term in months if different from parent cotermasset (string, optional) co term with an existing subscription subscriptionstartdate (string, optional) start date if different from parent billingtiming (string, optional) billing timing override billingperiod (string, optional) billing period override pricetagids (array, optional) price tag ids pricetagcodes (array, optional) price tag codes addons (array, optional) nested add ons (recursive) customfields (object, optional) custom field values important notes the products array must be accompanied by at least one entry in the assetchanges array subscriptionterm and cotermasset are mutually exclusive — use one or the other pricing fields ( netsalesprice , salesprice , subtotal , totalprice , etc ) are calculated automatically and cannot be set on the request dynamic add ons use a composite id format {productoptionid} {pricebookentryid} add ons support recursive nesting for multi level bundle hierarchies 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 new products (products array) field type required description example pricebookentryid string yes price book entry id identifying the product to add "01uql000009tsn7yac" quantity number yes quantity to add (must be positive) 3 subscriptionstartdate string yes effective start date for the new product "2025 02 15" subscriptionterm number one of term/cotermasset subscription term in months mutually exclusive with cotermasset 12 cotermasset string one of term/cotermasset existing subscription number to co term with mutually exclusive with subscriptionterm "sub 000200" autorenew boolean no whether the subscription should auto renew true defaultrenewalterm number no renewal term in months when auto renew is enabled 12 billingtiming string no billing timing "in advance" billingperiod string no billing frequency "month" billcycleday string no day of the billing cycle "1" billcyclestartmonth string no starting month for annual billing cycles "january" description string no custom description "cross sell product" pricetagids array no price tag ids to apply discounts \["tag 123"] pricetagcodes array no price tag codes (alternative to ids) \["disc20"] customfields object no custom field values to populate on the order product {"region c" "emea"} addons array no bundle add ons to include with the product see add on structure 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 new products new products use a separate products array alongside assetchanges , and must be accompanied by at least one asset change calculated fields pricing fields ( netsalesprice , salesprice , subtotal , totalprice , etc ) cannot be set on new product requests — they are calculated automatically by the pricing engine 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 } ] } ] } new product with bundle add ons { "options" { "previewinvoice" true, "calculatetax" true }, "assetchanges" \[ { "changetype" "cancel", "assetnumber" "sub 000192", "cancellationdate" "2025 02 15" } ], "products" \[ { "pricebookentryid" "01uql000009tsn7yac", "quantity" 3, "subscriptionstartdate" "2025 02 15", "subscriptionterm" 12, "addons" \[ { "productoptionid" "a0jql00000jxnavyaz", "productoptionquantity" 3 }, { "productoptionid" "a0jql00000jxnavyaz 01uql00000cxugcyap", "productoptionquantity" 10 } ] } ] } 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 delta value (positive to add, negative to reduce) 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