Change Order Data Reference

33 min

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. Controls when the first billing period ends and subsequent cycles begin.	"1st of Month", "15th of Month"
billCycleStartMonth	String	No	Starting month for annual billing cycles (zero-padded month number). Required with billingPeriod: "Annual" to prorate the first invoice to the billing anchor date.	"01" (January), "04" (April)
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
processPayment	Boolean	false	Confirm payment synchronously before committing. When true, requires generateInvoice: true and activateInvoice: true. If the change order produces a negative invoice (e.g., cancellation, large quantity reduction), payment is automatically skipped and the credit memo is committed normally.
cancelOnPaymentFail	Boolean	false	Only valid with processPayment: true. If true, rolls back the entire activation on payment failure (HTTP 400, order stays Draft). If false, commits the change order despite payment failure and returns HTTP 207 with a warning.

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.