--- title: Create Change Order slug: create-change-order docTags: createdAt: 2026-08-25T19:28:59.170Z --- { "id": "H2iD_5zQ4_NapqJnugLTK", "type": "api-oas-v2", "data": { "method": "POST", "url": "https://api.nue.io/cpq/change-order", "servers": [ { "url": "https://api.nue.io/cpq/change-order", "description": "Nue Production API Endpoint" }, { "url": "https://api.sandbox.nue.io/cpq/change-order", "description": "Nue Sandbox API Endpoint" } ], "name": "Create Change Order", "description": "

Create a change order to modify existing subscriptions. Supports various change types including reconfigure, upgrade, downgrade, quantity updates, renewals, cancellations, and more. Operations are processed directly in Salesforce and can create orders or quotes based on your configuration.

", "contentType": "application/json", "request": { "pathParameters": [], "headerParameters": [ { "name": "accept", "type": "string", "kind": "optional", "description": "Generated from available response content types", "enum": [ "application/json" ], "default": "application/json" }, { "kind": "optional", "name": "Ruby-Version", "type": "string", "example": "2.0", "description": "API version header for backward compatibility" } ], "queryParameters": [], "bodyDataParameters": [ { "kind": "required", "name": "body", "type": "object", "description": "

Change order request supporting all change types including reconfigure, upgrade, downgrade, quantity updates, renewals, cancellations, and more

", "customType": "ChangeOrderRequest", "schema": [ { "name": "options", "kind": "required", "type": "object", "description": "", "example": "", "schema": [ { "name": "activateOrder", "kind": "optional", "type": "boolean", "description": "

Whether to activate the order/quote

" }, { "name": "proceedOption", "kind": "required", "type": "string", "description": "How to process the change", "enum": [ "UseExistingQuote", "UseExistingOrder", "CreateOrder", "CreateQuote" ] }, { "name": "opportunityId", "kind": "optional", "type": "string", "description": "

If CreateQuote or CreateOrder option is chosen, specify the opportunity ID to associate with the newly created quote or order

" }, { "name": "containedObjectId", "kind": "optional", "type": "string", "description": "

Existing quote/order ID to add changes to

" } ] }, { "name": "assetChanges", "kind": "required", "type": "array", "description": "List of changes to apply to assets", "modelRef": "#/components/schemas/AssetChangeRequest", "customType": "AssetChangeRequest[]", "schema": [ { "name": "changeType", "kind": "required", "type": "string", "description": "Type of change to apply to the asset", "enum": [ "Reconfigure", "UpdateQuantity", "Renew", "UpdateTerm", "CoTerm", "Cancel", "AdjustPrice", "ConvertFreeTrial", "Upgrade", "Downgrade", "Swap", "NewProduct", "UpdateField" ] }, { "name": "assetNumber", "kind": "optional", "type": "string", "description": "

Unique identifier for the asset (subscription name). Required for all change types.

" }, { "name": "quantity", "kind": "optional", "type": "number", "description": "

Quantity change (delta) for the subscription. Positive to add, negative to reduce. Required for UpdateQuantity. NOT allowed on Upgrade/Downgrade/Swap — sending it is rejected with PRODUCT_QUANTITY_NOT_ALLOWED (UDS quantities are derived; use a separate UpdateQuantity change on the same asset).

" }, { "name": "renewalTerm", "kind": "optional", "type": "number", "description": "Renewal term length in months. Required for Renew." }, { "name": "term", "kind": "optional", "type": "number", "description": "

New term length in months. Required for UpdateTerm, optional for ConvertFreeTrial.

" }, { "name": "coTermDate", "kind": "optional", "type": "string", "description": "

Co-termination date. Required for CoTerm.

", "format": "date" }, { "name": "cancellationDate", "kind": "optional", "type": "string", "description": "Date to cancel the subscription. Required for Cancel.", "format": "date" }, { "name": "startDate", "kind": "optional", "type": "string", "description": "

Start date for the change. Required for UpdateQuantity, ConvertFreeTrial, Upgrade, Downgrade, Swap. Optional for Reconfigure, AdjustPrice.

", "format": "date" }, { "name": "endDate", "kind": "optional", "type": "string", "description": "End date for the change. Optional for AdjustPrice.", "format": "date" }, { "name": "netSalesPrice", "kind": "optional", "type": "number", "description": "

New price amount. Optional for AdjustPrice (use either this or discount).

" }, { "name": "discount", "kind": "optional", "type": "object", "description": "

Discount configuration. Optional for AdjustPrice (use either this or netSalesPrice).

", "example": "", "schema": [ { "name": "discountPercentage", "kind": "optional", "type": "number", "description": "

Discount percentage (e.g., 20 for 20%)

" }, { "name": "applyToChildren", "kind": "optional", "type": "boolean", "description": "Whether to apply discount to child assets" } ] }, { "name": "targetPriceBookEntryId", "kind": "optional", "type": "string", "description": "

Price book entry ID for the target product. Required for Upgrade, Downgrade, Swap.

" }, { "name": "samePriceSwap", "kind": "optional", "type": "boolean", "description": "

Keep same price during product change. Optional for Upgrade, Downgrade, Swap.

" }, { "name": "priceTags", "kind": "optional", "type": "array", "description": "

Price tag CODES (array of strings) to apply. Optional for Upgrade, Downgrade, Swap.

", "example": "", "itemType": "string", "customType": "string[]", "itemExample": "", "itemDefault": "" }, { "name": "switchToEvergreen", "kind": "optional", "type": "boolean", "description": "

Switch to evergreen subscription. Optional for Renew, UpdateTerm, ConvertFreeTrial.

" }, { "name": "coTermToBundleSubscription", "kind": "optional", "type": "boolean", "description": "

Co-term to bundle subscription. Optional for ConvertFreeTrial.

" }, { "name": "overrideTrialEnd", "kind": "optional", "type": "boolean", "description": "Override trial end date. Optional for ConvertFreeTrial." }, { "name": "trueUpPrice", "kind": "optional", "type": "boolean", "description": "

When set on an AdjustPrice change, recomputes the price to the correct quantity tier for the current value of the subscription's quantity tier attribute. Applies to the targeted subscription only; to true up a bundle over REST, send a separate trueUpPrice AdjustPrice for the parent and each child subscription. Optional; only applies to AdjustPrice changes.

" }, { "name": "addOnChanges", "kind": "optional", "type": "array", "description": "

Add-on changes for reconfiguration. Required for Reconfigure.

", "example": "", "itemType": "object", "customType": "object[]", "schema": [ { "name": "changeType", "kind": "required", "type": "string", "description": "

Type of add-on change

", "enum": [ "NewProduct", "UpdateQuantity", "Cancel" ] }, { "name": "productOptionId", "kind": "optional", "type": "string", "description": "Product option ID. Required for NewProduct." }, { "name": "priceBookEntryId", "kind": "optional", "type": "string", "description": "Price book entry ID. Optional for NewProduct." }, { "name": "productOptionQuantity", "kind": "optional", "type": "number", "description": "

Add-on quantity. Required for NewProduct.

" }, { "name": "productOptionQuantityChange", "kind": "optional", "type": "number", "description": "

Quantity change amount. Required for UpdateQuantity add-ons.

" }, { "name": "startDate", "kind": "optional", "type": "string", "description": "

Effective date for the add-on change. Optional for all add-on changes.

", "format": "date" }, { "name": "term", "kind": "optional", "type": "number", "description": "

Term in months for the add-on. Optional for NewProduct.

" }, { "name": "cancellationDate", "kind": "optional", "type": "string", "description": "

Cancellation date. Required for Cancel add-ons.

", "format": "date" }, { "name": "assetNumber", "kind": "optional", "type": "string", "description": "

Asset number of the add-on to modify. Required for UpdateQuantity and Cancel add-ons.

" } ] }, { "name": "fieldsToUpdate", "kind": "optional", "type": "array", "description": "

Fields to update on the subscription. Required for UpdateField. Each entry sets one field by API name; values are strings and are coerced to the field's type on the Salesforce side.

", "example": "", "itemType": "object", "customType": "object[]", "schema": [ { "name": "fieldApiName", "kind": "optional", "type": "string", "description": "

The API name of the field to update (e.g. \"Description\").

" }, { "name": "newValue", "kind": "optional", "type": "string", "description": "

The new value to set, as a string.

" } ] }, { "name": "addOns", "kind": "optional", "type": "array", "description": "

Target bundle configuration for an Upgrade/Downgrade/Swap when the target product is a bundle. Required when the target bundle's feature/option constraints are not satisfiable by defaults (otherwise the request is rejected with FEATURE_OPTION_COUNT_OUT_OF_RANGE). Each entry identifies its product exactly one way (priceBookEntryId XOR productSku/productName) and uses productOptionId to target the bundle slot. quantity, discount, netSalesPrice, billingPeriod, billingTiming, endDate and coTermAsset are not allowed on a UDS add-on. Recursive for nested bundles. Omit to use the server default-config resolver.

", "modelRef": "#/components/schemas/AddQuoteProductRequest", "customType": "AddQuoteProductRequest[]", "schema": [ { "name": "productSku", "kind": "optional", "type": "string", "description": "

The product SKU (StockKeepingUnit). Exactly one of productSku or productName must be supplied — passing both, or neither, returns a PRODUCT_SKU_AND_NAME_EXCLUSIVE validation error.

", "example": "NUE_PLATFORM" }, { "name": "productName", "kind": "optional", "type": "string", "description": "

The product name. Alternative to productSku. The first matching active product is selected; if multiple products share the name an AMBIGUOUS_PRODUCT_NAME error is returned and you should use productSku instead.

", "example": "Nue Platform" }, { "name": "priceBookEntryId", "kind": "optional", "type": "string", "description": "

Specific Price Book Entry ID. Narrows the candidate-PBE list to this entry. The PBE must still satisfy the order's currency and pricing-attribute conditions — if it does not, the API returns PRICEBOOK_ENTRY_MISMATCH.

", "example": "01uxx000000ABCDEF" }, { "name": "quantity", "kind": "optional", "type": "number", "description": "

Number of units. Required for top-level products. For add-ons, defaults to the bundle option's DefaultQuantity.

", "example": 10, "minimum": 0 }, { "name": "uom", "kind": "optional", "type": "string", "description": "

Unit of Measure name (must match an existing UOM, e.g. User/Month, Hour, Each). For top-level products, supply at least one of priceBookEntryId, uom, or customPricingAttributes.

", "example": "User/Month" }, { "name": "startDate", "kind": "optional", "type": "string", "description": "

Per-product start date override. Defaults to the quote header's start date.

", "example": "2025-01-01", "format": "date" }, { "name": "endDate", "kind": "optional", "type": "string", "description": "

Per-product end date override. If subscriptionTerm is provided, the end date is calculated from startDate + subscriptionTerm.

", "example": "2026-01-01", "format": "date" }, { "name": "subscriptionTerm", "kind": "optional", "type": "number", "description": "

Per-product subscription term override. Must be > 0. Defaults to the quote header's term.

", "example": 12, "minimum": 0 }, { "name": "subscriptionTermDimension", "kind": "optional", "type": "string", "description": "Term dimension for the subscription term.", "example": "Month", "enum": [ "Month", "Year" ] }, { "name": "autoRenew", "kind": "optional", "type": "boolean", "description": "

Whether this product line auto-renews. Defaults to the quote-level or product-level setting.

", "example": true }, { "name": "evergreen", "kind": "optional", "type": "boolean", "description": "

Whether this is an evergreen subscription (no fixed term). Cannot be combined with subscriptionTerm or endDate.

", "example": false }, { "name": "billingPeriod", "kind": "optional", "type": "string", "description": "

Billing period override. Per-line, both label (Monthly) and API value (Month) are accepted. Top-level header billingPeriod requires the API value.

", "example": "Month" }, { "name": "billingTiming", "kind": "optional", "type": "string", "description": "

Billing timing override — whether billed before or after service delivery.

", "example": "In Advance", "enum": [ "In Advance", "In Arrears" ] }, { "name": "renewalTerm", "kind": "optional", "type": "number", "description": "

Renewal term in months. Must be > 0.

", "example": 12, "minimum": 0 }, { "name": "discount", "kind": "optional", "type": "number", "description": "

Discretionary discount percentage (0-100). Overrides header-level discount for this product. If both discount and discountAmount are set, discount takes precedence.

", "example": 15.5, "minimum": 0, "maximum": 100 }, { "name": "discountAmount", "kind": "optional", "type": "number", "description": "

Discretionary discount amount (currency). Ignored if discount is also provided.

", "example": 100, "minimum": 0 }, { "name": "priceTags", "kind": "optional", "type": "array", "description": "Price or discount tags to apply to this product.", "modelRef": "#/components/schemas/PriceTagInput", "customType": "PriceTagInput[]", "schema": [ { "name": "code", "kind": "optional", "type": "string", "description": "The price tag code.", "example": "REGR_DISC_QTY_TIERED" }, { "name": "id", "kind": "optional", "type": "string", "description": "The price tag ID.", "example": "a0dcU000005sZRrQAM" } ] }, { "name": "customPricingAttributes", "kind": "optional", "type": "array", "description": "

Custom Price Book Entry field values used to disambiguate multi-attribute pricing. Each entry's name must be the full Salesforce field API name including the namespace prefix and __c suffix (for example Ruby__PricingAttribute_3__c). Multiple attributes are AND'd together when filtering candidate PBEs.

", "modelRef": "#/components/schemas/CustomPricingAttribute", "customType": "CustomPricingAttribute[]", "schema": [ { "name": "name", "kind": "required", "type": "string", "description": "

Full Salesforce field API name on the PriceBookEntry, including the package namespace prefix and __c suffix. Examples: Ruby__PricingAttribute_3__c, Ruby__Segment__c. Bare names without namespace or __c are rejected with Invalid field <name> for PricebookEntry.

", "example": "Ruby__PricingAttribute_3__c" }, { "name": "value", "kind": "required", "type": "string", "description": "The value to match against the PriceBookEntry field. Compared as a string.", "example": "New Business" } ] }, { "name": "addOns", "kind": "optional", "type": "array", "description": "

Optional add-on products for bundles. Each add-on is itself a product request object.

", "modelRef": "#/components/schemas/AddQuoteProductRequest", "customType": "AddQuoteProductRequest[]", "schema": [ { "name": "", "description": "", "customType": "Circular-Reference" } ] }, { "name": "productOptionId", "kind": "optional", "type": "string", "description": "

For add-on lines, targets a specific bundle option slot (RIM-20981). When set, productSku/productName become optional.

" }, { "name": "netSalesPrice", "kind": "optional", "type": "number", "description": "

Explicit unit net sales price; back-calculates the discount. Mutually exclusive with discount and discountAmount.

" }, { "name": "paymentTerm", "kind": "optional", "type": "string", "description": "

Per-line payment term override, e.g. 'Net 30'.

" }, { "name": "coTermAsset", "kind": "optional", "type": "string", "description": "

Change-order only. Co-terminate this new line with the named Salesforce subscription number.

" }, { "name": "parentLineId", "kind": "optional", "type": "string", "description": "

Update API only. Adds this product as an option child under the existing bundle line with this id, resolved against that bundle's live option config. May target the root bundle line or a nested sub-bundle line. Omit for a top-level add.

", "example": "0QLRu00000AAvDcIAL" }, { "name": "customFields", "kind": "optional", "type": "map", "description": "

Line-level custom field name/value pairs applied directly onto the created line item. Keys are Salesforce API names on the line object (QuoteLineItem or OrderProduct); an unknown field name is rejected. Supported on /cpq/quotes, /cpq/orders, and the addLineItems action of the

endpoints.

", "example": "{\"CostCenter__c\":\"CC-1042\",\"Ruby__IncludedUnits__c\":25}", "customType": "map", "schema": [] }, { "name": "rampValues", "kind": "optional", "type": "array", "description": "

Per-ramp Line Attribute values for a ramped line. Each entry sets custom field values on one ramp line, addressed by rampLineIndex. Ramp lines not named inherit the line-level value, then the Pricebook Entry default. Supported on /cpq/quotes and /cpq/orders.

", "modelRef": "#/components/schemas/RampValueInput", "customType": "RampValueInput[]", "schema": [ { "name": "rampLineIndex", "kind": "optional", "type": "integer", "description": "

Which ramp line to apply the values to, 1-based in schedule order.

", "example": 1 }, { "name": "startDate", "kind": "optional", "type": "string", "description": "

The ramp line's start date, accepted as a readable alias for rampLineIndex. Ramp line dates are derived by the pricing engine, so this is not the addressing key; when both are given they must agree.

", "example": "2026-01-01", "format": "date" }, { "name": "fieldValues", "kind": "optional", "type": "map", "description": "

Field name/value pairs applied to this ramp line only, overriding what it would otherwise inherit from its parent line.

", "example": "{\"Overage_Rate__c\":3}", "customType": "map", "schema": [] } ] } ] }, { "name": "transformations", "kind": "optional", "type": "array", "description": "

Ambiguity pins for bundle Upgrade/Downgrade/Swap: when a source subscription (bundle child) maps to more than one candidate slot in the target, each pin resolves one source. Identify the candidate exactly one way: explicit (targetProductOptionId + targetPriceBookEntryId together) XOR by-values (uom / customPricingAttributes / billingTiming). Mixing the two is rejected with TRANSFORMATION_IDENTITY_CONFLICT.

", "modelRef": "#/components/schemas/Transformation", "customType": "Transformation[]", "schema": [ { "name": "sourceAssetNumber", "kind": "required", "type": "string", "description": "

The source subscription (SUB-xxxx) this pin resolves.

" }, { "name": "targetProductOptionId", "kind": "optional", "type": "string", "description": "

Explicit style: the target bundle option slot. Send together with targetPriceBookEntryId.

" }, { "name": "targetPriceBookEntryId", "kind": "optional", "type": "string", "description": "

Explicit style: target price book entry. XOR with the by-values fields.

" }, { "name": "uom", "kind": "optional", "type": "string", "description": "

By-values style: unit of measure of the target candidate.

" }, { "name": "customPricingAttributes", "kind": "optional", "type": "array", "description": "

By-values style: pricing attributes identifying the target candidate.

", "modelRef": "#/components/schemas/CustomPricingAttribute", "customType": "CustomPricingAttribute[]", "schema": [ { "name": "name", "kind": "required", "type": "string", "description": "

Full Salesforce field API name on the PriceBookEntry, including the package namespace prefix and __c suffix. Examples: Ruby__PricingAttribute_3__c, Ruby__Segment__c. Bare names without namespace or __c are rejected with Invalid field <name> for PricebookEntry.

", "example": "Ruby__PricingAttribute_3__c" }, { "name": "value", "kind": "required", "type": "string", "description": "The value to match against the PriceBookEntry field. Compared as a string.", "example": "New Business" } ] }, { "name": "billingTiming", "kind": "optional", "type": "string", "description": "

By-values style: billing timing of the target candidate.

" } ] } ] }, { "name": "products", "kind": "optional", "type": "array", "description": "

Optional list of brand-new products to add as part of this change order (added in RIM-20008). Uses the same product shape as CreateQuoteRequest.products and is priced through the same pricing pipeline. Additive to assetChanges, which remains required.

", "modelRef": "#/components/schemas/AddQuoteProductRequest", "customType": "AddQuoteProductRequest[]", "schema": [ { "name": "productSku", "kind": "optional", "type": "string", "description": "

The product SKU (StockKeepingUnit). Exactly one of productSku or productName must be supplied — passing both, or neither, returns a PRODUCT_SKU_AND_NAME_EXCLUSIVE validation error.

", "example": "NUE_PLATFORM" }, { "name": "productName", "kind": "optional", "type": "string", "description": "

The product name. Alternative to productSku. The first matching active product is selected; if multiple products share the name an AMBIGUOUS_PRODUCT_NAME error is returned and you should use productSku instead.

", "example": "Nue Platform" }, { "name": "priceBookEntryId", "kind": "optional", "type": "string", "description": "

Specific Price Book Entry ID. Narrows the candidate-PBE list to this entry. The PBE must still satisfy the order's currency and pricing-attribute conditions — if it does not, the API returns PRICEBOOK_ENTRY_MISMATCH.

", "example": "01uxx000000ABCDEF" }, { "name": "quantity", "kind": "optional", "type": "number", "description": "

Number of units. Required for top-level products. For add-ons, defaults to the bundle option's DefaultQuantity.

", "example": 10, "minimum": 0 }, { "name": "uom", "kind": "optional", "type": "string", "description": "

Unit of Measure name (must match an existing UOM, e.g. User/Month, Hour, Each). For top-level products, supply at least one of priceBookEntryId, uom, or customPricingAttributes.

", "example": "User/Month" }, { "name": "startDate", "kind": "optional", "type": "string", "description": "

Per-product start date override. Defaults to the quote header's start date.

", "example": "2025-01-01", "format": "date" }, { "name": "endDate", "kind": "optional", "type": "string", "description": "

Per-product end date override. If subscriptionTerm is provided, the end date is calculated from startDate + subscriptionTerm.

", "example": "2026-01-01", "format": "date" }, { "name": "subscriptionTerm", "kind": "optional", "type": "number", "description": "

Per-product subscription term override. Must be > 0. Defaults to the quote header's term.

", "example": 12, "minimum": 0 }, { "name": "subscriptionTermDimension", "kind": "optional", "type": "string", "description": "Term dimension for the subscription term.", "example": "Month", "enum": [ "Month", "Year" ] }, { "name": "autoRenew", "kind": "optional", "type": "boolean", "description": "

Whether this product line auto-renews. Defaults to the quote-level or product-level setting.

", "example": true }, { "name": "evergreen", "kind": "optional", "type": "boolean", "description": "

Whether this is an evergreen subscription (no fixed term). Cannot be combined with subscriptionTerm or endDate.

", "example": false }, { "name": "billingPeriod", "kind": "optional", "type": "string", "description": "

Billing period override. Per-line, both label (Monthly) and API value (Month) are accepted. Top-level header billingPeriod requires the API value.

", "example": "Month" }, { "name": "billingTiming", "kind": "optional", "type": "string", "description": "

Billing timing override — whether billed before or after service delivery.

", "example": "In Advance", "enum": [ "In Advance", "In Arrears" ] }, { "name": "renewalTerm", "kind": "optional", "type": "number", "description": "

Renewal term in months. Must be > 0.

", "example": 12, "minimum": 0 }, { "name": "discount", "kind": "optional", "type": "number", "description": "

Discretionary discount percentage (0-100). Overrides header-level discount for this product. If both discount and discountAmount are set, discount takes precedence.

", "example": 15.5, "minimum": 0, "maximum": 100 }, { "name": "discountAmount", "kind": "optional", "type": "number", "description": "

Discretionary discount amount (currency). Ignored if discount is also provided.

", "example": 100, "minimum": 0 }, { "name": "priceTags", "kind": "optional", "type": "array", "description": "Price or discount tags to apply to this product.", "modelRef": "#/components/schemas/PriceTagInput", "customType": "PriceTagInput[]", "schema": [ { "name": "code", "kind": "optional", "type": "string", "description": "The price tag code.", "example": "REGR_DISC_QTY_TIERED" }, { "name": "id", "kind": "optional", "type": "string", "description": "The price tag ID.", "example": "a0dcU000005sZRrQAM" } ] }, { "name": "customPricingAttributes", "kind": "optional", "type": "array", "description": "

Custom Price Book Entry field values used to disambiguate multi-attribute pricing. Each entry's name must be the full Salesforce field API name including the namespace prefix and __c suffix (for example Ruby__PricingAttribute_3__c). Multiple attributes are AND'd together when filtering candidate PBEs.

", "modelRef": "#/components/schemas/CustomPricingAttribute", "customType": "CustomPricingAttribute[]", "schema": [ { "name": "name", "kind": "required", "type": "string", "description": "

Full Salesforce field API name on the PriceBookEntry, including the package namespace prefix and __c suffix. Examples: Ruby__PricingAttribute_3__c, Ruby__Segment__c. Bare names without namespace or __c are rejected with Invalid field <name> for PricebookEntry.

", "example": "Ruby__PricingAttribute_3__c" }, { "name": "value", "kind": "required", "type": "string", "description": "The value to match against the PriceBookEntry field. Compared as a string.", "example": "New Business" } ] }, { "name": "addOns", "kind": "optional", "type": "array", "description": "

Optional add-on products for bundles. Each add-on is itself a product request object.

", "modelRef": "#/components/schemas/AddQuoteProductRequest", "customType": "AddQuoteProductRequest[]", "schema": [ { "name": "", "description": "", "customType": "Circular-Reference" } ] }, { "name": "productOptionId", "kind": "optional", "type": "string", "description": "

For add-on lines, targets a specific bundle option slot (RIM-20981). When set, productSku/productName become optional.

" }, { "name": "netSalesPrice", "kind": "optional", "type": "number", "description": "

Explicit unit net sales price; back-calculates the discount. Mutually exclusive with discount and discountAmount.

" }, { "name": "paymentTerm", "kind": "optional", "type": "string", "description": "

Per-line payment term override, e.g. 'Net 30'.

" }, { "name": "coTermAsset", "kind": "optional", "type": "string", "description": "

Change-order only. Co-terminate this new line with the named Salesforce subscription number.

" }, { "name": "parentLineId", "kind": "optional", "type": "string", "description": "

Update API only. Adds this product as an option child under the existing bundle line with this id, resolved against that bundle's live option config. May target the root bundle line or a nested sub-bundle line. Omit for a top-level add.

", "example": "0QLRu00000AAvDcIAL" }, { "name": "customFields", "kind": "optional", "type": "map", "description": "

Line-level custom field name/value pairs applied directly onto the created line item. Keys are Salesforce API names on the line object (QuoteLineItem or OrderProduct); an unknown field name is rejected. Supported on /cpq/quotes, /cpq/orders, and the addLineItems action of the

endpoints.

", "example": "{\"CostCenter__c\":\"CC-1042\",\"Ruby__IncludedUnits__c\":25}", "customType": "map", "schema": [] }, { "name": "rampValues", "kind": "optional", "type": "array", "description": "

Per-ramp Line Attribute values for a ramped line. Each entry sets custom field values on one ramp line, addressed by rampLineIndex. Ramp lines not named inherit the line-level value, then the Pricebook Entry default. Supported on /cpq/quotes and /cpq/orders.

", "modelRef": "#/components/schemas/RampValueInput", "customType": "RampValueInput[]", "schema": [ { "name": "rampLineIndex", "kind": "optional", "type": "integer", "description": "

Which ramp line to apply the values to, 1-based in schedule order.

", "example": 1 }, { "name": "startDate", "kind": "optional", "type": "string", "description": "

The ramp line's start date, accepted as a readable alias for rampLineIndex. Ramp line dates are derived by the pricing engine, so this is not the addressing key; when both are given they must agree.

", "example": "2026-01-01", "format": "date" }, { "name": "fieldValues", "kind": "optional", "type": "map", "description": "

Field name/value pairs applied to this ramp line only, overriding what it would otherwise inherit from its parent line.

", "example": "{\"Overage_Rate__c\":3}", "customType": "map", "schema": [] } ] } ] }, { "name": "taxRates", "kind": "optional", "type": "array", "description": "

Optional per-product tax-rate overrides applied while pricing the change (not merely accepted and ignored).

", "modelRef": "#/components/schemas/ProductTaxRate", "customType": "ProductTaxRate[]", "schema": [ { "name": "productSku", "kind": "required", "type": "string", "description": "

The product (StockKeepingUnit) to apply the rate to.

" }, { "name": "taxPercentage", "kind": "required", "type": "number", "description": "

Tax rate as a percentage, e.g. 8.25 for 8.25%.

", "example": 8.25 } ] } ], "modelRef": "#/components/schemas/ChangeOrderRequest", "isExpanded": true } ], "formDataParameters": [], "oAuthParameters": [ { "id": "ApiKeyAuth", "name": "nue-api-key", "kind": "optional", "type": "apiKey", "in": "header" } ], "cookieParameters": [] }, "responses": [ { "statusCode": "200", "description": "Change order created successfully", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "Response from change order execution containing all created and modified objects", "customType": "ChangeOrderResponse", "schema": [ { "name": "headerObjectIds", "kind": "required", "type": "array", "description": "

List of primary object IDs created or modified (orders, quotes, etc.)

", "example": "[\"801xx000003ABCD\",\"0Q04x000002DEF1\"]", "itemType": "string", "customType": "string[]", "itemExample": "", "itemDefault": "" }, { "name": "messages", "kind": "optional", "type": "array", "description": "

Processing messages, warnings, or notifications from the change order execution

", "example": "[\"Asset SUB-086067 quantity updated from 5 to 10\",\"Prorated charges calculated\"]", "itemType": "string", "customType": "string[]", "itemExample": "", "itemDefault": "" }, { "name": "order", "kind": "optional", "type": "map", "description": "

Order object created or modified by the change (if proceedOption was CreateOrder or UseExistingOrder)

", "example": "", "customType": "map", "schema": [] }, { "name": "orderProducts", "kind": "optional", "type": "array", "description": "

Order product records with hierarchical parent-child relationships

", "example": "", "itemType": "object", "customType": "object[]", "itemExample": "", "itemDefault": "" }, { "name": "subscriptions", "kind": "optional", "type": "array", "description": "Subscription records created or modified by the change order", "example": "", "itemType": "object", "customType": "object[]", "itemExample": "", "itemDefault": "" }, { "name": "assets", "kind": "optional", "type": "array", "description": "

Asset records representing the customer's updated subscription states with new quantities, prices, or configurations

", "example": "", "itemType": "object", "customType": "object[]", "itemExample": "", "itemDefault": "" }, { "name": "entitlements", "kind": "optional", "type": "array", "description": "Entitlement records updated to reflect new access rights and usage limits", "example": "", "itemType": "object", "customType": "object[]", "itemExample": "", "itemDefault": "" }, { "name": "invoices", "kind": "optional", "type": "array", "description": "

Salesforce invoice records if generateInvoice option was enabled (legacy versions only)

", "example": "", "itemType": "object", "customType": "object[]", "itemExample": "", "itemDefault": "" }, { "name": "quotes", "kind": "optional", "type": "array", "description": "Quote records created if proceedOption was CreateQuote or UseExistingQuote", "example": "", "itemType": "object", "customType": "object[]", "itemExample": "", "itemDefault": "" } ], "modelRef": "#/components/schemas/ChangeOrderResponse", "isExpanded": true } ] }, { "statusCode": "400", "description": "Bad Request", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "", "customType": "BadRequestError", "schema": [ { "name": "errorCode", "kind": "optional", "type": "string", "description": "

Machine-readable code for the failure.

" }, { "name": "message", "kind": "optional", "type": "string", "description": "

Human-readable description.

" }, { "name": "errors", "kind": "optional", "type": "array", "description": "

Present for field-level validation problems; one entry per offending field.

", "example": "", "itemType": "string", "customType": "string[]", "itemExample": "", "itemDefault": "" }, { "name": "path", "kind": "optional", "type": "string", "description": "

The input at fault, e.g. assetChanges[0].quantity.

" }, { "name": "relatedPaths", "kind": "optional", "type": "array", "description": "Any other inputs involved in the same problem.", "example": "", "itemType": "string", "customType": "string[]", "itemExample": "", "itemDefault": "" }, { "name": "error", "kind": "optional", "type": "string", "description": "

Legacy/alternate shape returned for some upstream failures — present but incomplete on its own.

" } ], "modelRef": "#/components/schemas/BadRequestError", "isExpanded": true } ] }, { "statusCode": "409", "description": "

Resolution required — a bundle Upgrade/Downgrade/Swap still has an unresolved one-to-many source→target tie. Resolve by adding transformations pins (see the

endpoint) and retry.

", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "example": "{\"errorCode\":\"RESOLUTION_REQUIRED\",\"message\":\"Several target options match these sources — choose one per source.\",\"path\":\"assetChanges[0].assetNumber[SUB-000868]\",\"ambiguities\":[{\"sourceAssetNumber\":\"SUB-000868\",\"sourceProductName\":\"Growth Bundle\",\"candidates\":[{\"targetProductOptionId\":\"a1B...\",\"targetPriceBookEntryId\":\"01u...\",\"targetProductName\":\"Scale Bundle\",\"changeType\":\"Upgrade\",\"recommended\":true,\"recommendationReason\":\"Closest tier match\"}]}]}", "description": "", "customType": "ResolutionRequiredError", "schema": [ { "name": "errorCode", "kind": "optional", "type": "string", "description": "", "example": "RESOLUTION_REQUIRED" }, { "name": "path", "kind": "optional", "type": "string", "description": "The unresolved source asset." }, { "name": "message", "kind": "optional", "type": "string", "description": "" }, { "name": "ambiguities", "kind": "optional", "type": "array", "description": "", "modelRef": "#/components/schemas/Ambiguity", "customType": "Ambiguity[]", "schema": [ { "name": "sourceAssetNumber", "kind": "optional", "type": "string", "description": "" }, { "name": "sourceProductName", "kind": "optional", "type": "string", "description": "" }, { "name": "candidates", "kind": "optional", "type": "array", "description": "", "modelRef": "#/components/schemas/Candidate", "customType": "Candidate[]", "schema": [ { "name": "targetProductOptionId", "kind": "optional", "type": "string", "description": "" }, { "name": "targetPriceBookEntryId", "kind": "optional", "type": "string", "description": "" }, { "name": "targetProductName", "kind": "optional", "type": "string", "description": "" }, { "name": "uom", "kind": "optional", "type": "string", "description": "" }, { "name": "customPricingAttributes", "kind": "optional", "type": "array", "description": "", "example": "", "itemType": "object", "customType": "object[]", "itemExample": "", "itemDefault": "" }, { "name": "listPrice", "kind": "optional", "type": "number", "description": "" }, { "name": "priceModel", "kind": "optional", "type": "string", "description": "" }, { "name": "currencyIsoCode", "kind": "optional", "type": "string", "description": "" }, { "name": "billingTiming", "kind": "optional", "type": "string", "description": "" }, { "name": "changeType", "kind": "optional", "type": "string", "description": "

Per-candidate transformation direction (distinct from the operation-level changeType).

", "enum": [ "Upgrade", "Downgrade", "Swap" ] }, { "name": "targetKind", "kind": "optional", "type": "string", "description": "", "enum": [ "BUNDLE", "PRODUCT" ] }, { "name": "recommended", "kind": "optional", "type": "boolean", "description": "" }, { "name": "recommendationReason", "kind": "optional", "type": "string", "description": "" } ] } ] }, { "name": "relatedPaths", "kind": "optional", "type": "array", "description": "Other changes involved in the same conflict.", "example": "", "itemType": "string", "customType": "string[]", "itemExample": "", "itemDefault": "" } ], "modelRef": "#/components/schemas/ResolutionRequiredError", "isExpanded": true } ] } ], "hasXCodeSamples": false, "examples": { "languages": [ { "id": "ezXS-ATAbYsi9ZfGScP_s", "language": "curl", "label": "cURL", "code": "curl --request POST \\\n --url https://api.nue.io/cpq/change-order \\\n --header 'accept: application/json' \\\n --header 'content-type: application/json' \\\n --data '{\n \"options\": {\n \"proceedOption\": \"\"\n },\n \"assetChanges\": [\n {\n \"changeType\": \"\",\n \"addOnChanges\": [\n {\n \"changeType\": \"\"\n }\n ],\n \"addOns\": [\n {\n \"customPricingAttributes\": [\n {\n \"name\": \"Ruby__PricingAttribute_3__c\",\n \"value\": \"New Business\"\n }\n ]\n }\n ],\n \"transformations\": [\n {\n \"sourceAssetNumber\": \"\",\n \"customPricingAttributes\": [\n {\n \"name\": \"Ruby__PricingAttribute_3__c\",\n \"value\": \"New Business\"\n }\n ]\n }\n ]\n }\n ],\n \"products\": [\n {\n \"customPricingAttributes\": [\n {\n \"name\": \"Ruby__PricingAttribute_3__c\",\n \"value\": \"New Business\"\n }\n ]\n }\n ],\n \"taxRates\": [\n {\n \"productSku\": \"\",\n \"taxPercentage\": 8.25\n }\n ]\n }'" }, { "id": "P0ApMWIxT-fjFyNBhHFum", "language": "javascript", "label": "javascript", "code": "var myHeaders = new Headers();\nmyHeaders.append(\"accept\", \"application/json\");\nmyHeaders.append(\"content-type\", \"application/json\");\n\nvar raw = JSON.stringify({\n \"options\": {\n \"proceedOption\": \"\"\n },\n \"assetChanges\": [\n {\n \"changeType\": \"\",\n \"addOnChanges\": [\n {\n \"changeType\": \"\"\n }\n ],\n \"addOns\": [\n {\n \"customPricingAttributes\": [\n {\n \"name\": \"Ruby__PricingAttribute_3__c\",\n \"value\": \"New Business\"\n }\n ]\n }\n ],\n \"transformations\": [\n {\n \"sourceAssetNumber\": \"\",\n \"customPricingAttributes\": [\n {\n \"name\": \"Ruby__PricingAttribute_3__c\",\n \"value\": \"New Business\"\n }\n ]\n }\n ]\n }\n ],\n \"products\": [\n {\n \"customPricingAttributes\": [\n {\n \"name\": \"Ruby__PricingAttribute_3__c\",\n \"value\": \"New Business\"\n }\n ]\n }\n ],\n \"taxRates\": [\n {\n \"productSku\": \"\",\n \"taxPercentage\": 8.25\n }\n ]\n});\n\nvar requestOptions = {\n method: 'POST',\n headers: myHeaders,\n body: raw,\n redirect: 'follow'\n};\n\nfetch(\"https://api.nue.io/cpq/change-order\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));" }, { "id": "kMCAKkr12gPqRRETabnXp", "language": "ruby", "label": "Ruby", "code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://api.nue.io/cpq/change-order\")\n\nhttps = Net::HTTP.new(url.host, url.port)\nhttps.use_ssl = true\n\nrequest = Net::HTTP::Post.new(url)\nrequest[\"accept\"] = \"application/json\"\nrequest[\"content-type\"] = \"application/json\"\nrequest.body = JSON.dump({\n \"options\": {\n \"proceedOption\": \"\"\n },\n \"assetChanges\": [\n {\n \"changeType\": \"\",\n \"addOnChanges\": [\n {\n \"changeType\": \"\"\n }\n ],\n \"addOns\": [\n {\n \"customPricingAttributes\": [\n {\n \"name\": \"Ruby__PricingAttribute_3__c\",\n \"value\": \"New Business\"\n }\n ]\n }\n ],\n \"transformations\": [\n {\n \"sourceAssetNumber\": \"\",\n \"customPricingAttributes\": [\n {\n \"name\": \"Ruby__PricingAttribute_3__c\",\n \"value\": \"New Business\"\n }\n ]\n }\n ]\n }\n ],\n \"products\": [\n {\n \"customPricingAttributes\": [\n {\n \"name\": \"Ruby__PricingAttribute_3__c\",\n \"value\": \"New Business\"\n }\n ]\n }\n ],\n \"taxRates\": [\n {\n \"productSku\": \"\",\n \"taxPercentage\": 8.25\n }\n ]\n})\n\nresponse = https.request(request)\nputs response.read_body\n" }, { "id": "vkzY5AnbvScIYdvjihum7", "language": "python", "label": "Python", "code": "import requests\nimport json\n\nurl = \"https://api.nue.io/cpq/change-order\"\n\npayload = json.dumps({\n \"options\": {\n \"proceedOption\": \"\"\n },\n \"assetChanges\": [\n {\n \"changeType\": \"\",\n \"addOnChanges\": [\n {\n \"changeType\": \"\"\n }\n ],\n \"addOns\": [\n {\n \"customPricingAttributes\": [\n {\n \"name\": \"Ruby__PricingAttribute_3__c\",\n \"value\": \"New Business\"\n }\n ]\n }\n ],\n \"transformations\": [\n {\n \"sourceAssetNumber\": \"\",\n \"customPricingAttributes\": [\n {\n \"name\": \"Ruby__PricingAttribute_3__c\",\n \"value\": \"New Business\"\n }\n ]\n }\n ]\n }\n ],\n \"products\": [\n {\n \"customPricingAttributes\": [\n {\n \"name\": \"Ruby__PricingAttribute_3__c\",\n \"value\": \"New Business\"\n }\n ]\n }\n ],\n \"taxRates\": [\n {\n \"productSku\": \"\",\n \"taxPercentage\": 8.25\n }\n ]\n})\nheaders = {\n 'accept': 'application/json',\n 'content-type': 'application/json'\n}\n\nresponse = requests.request(\"POST\", url, headers=headers, data=payload)\n\nprint(response.text)\n" } ], "selectedLanguageId": "ezXS-ATAbYsi9ZfGScP_s" }, "results": { "languages": [ { "id": "lgmpNE5jvVIEcimVJFaG9", "language": "200", "code": "// Change order created successfully\n{\n \"headerObjectIds\": [\n \"\"\n ],\n \"messages\": [\n \"\"\n ],\n \"order\": \"\",\n \"orderProducts\": [\n {}\n ],\n \"subscriptions\": [\n {}\n ],\n \"assets\": [\n {}\n ],\n \"entitlements\": [\n {}\n ],\n \"invoices\": [\n {}\n ],\n \"quotes\": [\n {}\n ]\n}" }, { "id": "CBDr4u2_728K34G-RYsMz", "language": "400", "code": "// Bad Request\n{\n \"errorCode\": \"\",\n \"message\": \"\",\n \"errors\": [\n \"\"\n ],\n \"path\": \"\",\n \"relatedPaths\": [\n \"\"\n ],\n \"error\": \"\"\n}" }, { "id": "mkQuHSgV_2N1Dn93zsVir", "language": "409", "code": "// Resolution required — a bundle Upgrade/Downgrade/Swap still has an unresolved one-to-many source→target tie. Resolve by adding transformations pins (see the endpoint) and retry.\n{\n \"errorCode\": \"RESOLUTION_REQUIRED\",\n \"path\": \"\",\n \"message\": \"\",\n \"ambiguities\": [\n {\n \"sourceAssetNumber\": \"\",\n \"sourceProductName\": \"\",\n \"candidates\": [\n {\n \"targetProductOptionId\": \"\",\n \"targetPriceBookEntryId\": \"\",\n \"targetProductName\": \"\",\n \"uom\": \"\",\n \"customPricingAttributes\": [\n {}\n ],\n \"listPrice\": 0,\n \"priceModel\": \"\",\n \"currencyIsoCode\": \"\",\n \"billingTiming\": \"\",\n \"changeType\": \"\",\n \"targetKind\": \"\",\n \"recommended\": false,\n \"recommendationReason\": \"\"\n }\n ]\n }\n ],\n \"relatedPaths\": [\n \"\"\n ]\n}" } ], "selectedLanguageId": "lgmpNE5jvVIEcimVJFaG9" } }, "children": [ { "text": "" } ] }