Update Order

1 min

POST

https://api.nue.io/cpq/orders/{orderId}:update

Applies one or more actions to an existing order, then re-runs the same pricing and tax cascade the Nue Line Editor runs internally.

Action-oriented, not payload-oriented. You do not send the order you want; you send an ordered list of actions naming what to do. Fields you omit are untouched, and lines you omit are untouched — a line is deleted only when you name it in a deleteLineItems action. This is what separates this endpoint from PATCH /api/objects/Order/{id}, which writes the field you send and recalculates nothing, with one exception: a body that carries partnerPayoutPercentage or partnerPayoutAmount is re-priced.

The six actions: updateHeaderFields, updateLineItems, deleteLineItems, addLineItems, replacePriceTags, removePriceTags.

Key behaviors:

Actions are re-ordered server-side into a canonical sequence of stages (header fields → deletes → price-tag actions → line updates → adds). The sort is stable within a stage, so same-stage actions keep your submitted order
removePriceTags and replacePriceTags share a stage and their target line ids are not covered by the conflict check, so two overlapping tag actions run in submitted order and the result depends on it — order them deliberately or split the request
updateHeaderFields may appear at most once, and each line may be targeted at most once — both violations return CONFLICTING_ACTIONS
partnerPayoutPercentage and partnerPayoutAmount in updateHeaderFields are mutually exclusive: send one and the other is derived (both returns PARTNER_PAYOUT_MUTUALLY_EXCLUSIVE). They always re-price, so recalc of TAX_ONLY or NONE returns RECALC_MODE_NOT_SUPPORTED, and an out-of-range value returns INVALID_PARTNER_PAYOUT_RANGE. On an order, sending a partner field together with a status change returns CONFLICTING_ACTIONS; update the payout first, then the status.
isCommit: false runs the full cascade in memory and returns the same shape without persisting anything
recalc selects which callouts run: AUTO (default), PRICING_ONLY, TAX_ONLY, NONE — case-sensitive
fieldValues keys are Nue field names (camelCase, e.g. quantity, subscriptionTerm, paymentTerm) validated against the Order / OrderProduct describe; custom fields use their Salesforce API name. Salesforce field API names such as SubscriptionTerm__c are for the Apex global method, not for REST
Engine-calculated fields (totals, tax, ACV/TCV, delta metrics, list and sales prices) are rejected with FIELD_NOT_UPDATABLE
Summary, split, ramp, and subscription-context lines are not editable; required and bundled bundle children cannot be removed on their own
The whole update is one transaction: a pricing failure rolls everything back
The order must be in Draft status — anything else returns ORDER_NOT_DRAFT

Activated orders and live subscriptions are out of scope — use the Change Order endpoint instead.

Path Parameters

orderIdstringrequired
Description
The id of the order to update.

Body Parameters

bodyUpdateOrderRequestrequired
Description
Action-oriented update request. You send an ordered list of actions describing what to do, not the desired order document. Fields and lines you do not name are left untouched.
- isCommitboolean
  Example
  true
  Description
  true (or omitted) persists the result. false runs the full pricing and tax cascade in memory and persists nothing. Must be a boolean.
  Default
  true
- recalcstring<AUTO | PRICING_ONLY | TAX_ONLY | NONE>
  Example
  AUTO
  Description
  Recalculation mode. Case-sensitive. AUTO derives what to recompute from which fields changed.
  Default
  AUTO
  Allowed
  AUTOPRICING_ONLYTAX_ONLYNONE
- expectedLastModifiedstring<date-time>
  Description
  Optimistic-concurrency guard. When set, the update fails with ORDER_MODIFIED unless it matches the record's current last-modified timestamp.
  Format
  date-time
- actionsUpdateAction[]required
  Description
  Ordered list of actions. The server re-orders them into canonical stages (header fields, deletes, price-tag actions, line updates, adds) before executing. The sort is stable within a stage, so same-stage actions keep your submitted order — which matters only for removePriceTags/replacePriceTags, the one pair that shares a stage and is not covered by the per-line conflict check.
  - actionstring<updateHeaderFields | updateLineItems | deleteLineItems | addLineItems | replacePriceTags | removePriceTags>required
    Description
    The operation to perform.
    Allowed
    updateHeaderFieldsupdateLineItemsdeleteLineItemsaddLineItemsreplacePriceTagsremovePriceTags
  - payloadmap<string, string>
    Description
    Action-specific payload.
    
    updateHeaderFields -> { fieldValues: { <nueFieldName>: value } }
    
    updateLineItems -> { lineItems: [ { lineItemId, fieldValues } ] }
    
    deleteLineItems -> { lineItemIds: [ id ] }
    
    addLineItems -> { products: [ AddQuoteProductRequest ] }
    
    replacePriceTags -> { priceTags: [ { <oldIdOrCode>: <newIdOrCode> } ], target?, includeChildren? }
    
    removePriceTags -> { priceTags: [ <idOrCode> ], target?, includeChildren? }

Responses

200

The order was updated (or, with isCommit=false, previewed) successfully.

UpdateOrderResponse
Description
The recalculated order after the update.
- ordermap<string, string>
  Description
  The order header with recalculated pricing, metrics, and tax.
- orderProductsobject[]
  Description
  Every order product after the update, with hierarchy.
- warningsMessage[]
  Description
  Non-blocking advisories returned alongside a successful update.
  - errorCodestring
    Description
    Severity level: Error, Warning, or FATAL.
  - errorTypestring
    Description
    Specific error or warning code (e.g., PRODUCT_SKU_OR_NAME_REQUIRED, DUPLICATE_PRICE_TAG).
  - messagestring
    Description
    Human-readable description.

400

Invalid request — unknown action, conflicting actions, invalid or non-updatable field, non-editable line, failed business rule, or a stale expectedLastModified.

ApiErrorResponse
Description
Error envelope returned by the CPQ REST endpoints, including Update Quote, Update Order, and PATCH /api/objects/{Quote,Order}/{id}. errorDetails is omitted when empty.
- statusinteger
  Example
  400
  Description
  HTTP status code.
- errorstring
  Example
  Failed to update quote
  Description
  Short error title.
- messagestring
  Description
  Human-readable message. For a single failure it matches the first errorDetails entry.
- errorDetailsErrorDetail[]
  Description
  One entry per failure, each with a semantic errorCode.
  - errorCodestring
    Example
    QUOTE_NOT_FOUND
    Description
    Semantic error code.
  - messagestring
    Description
    Human-readable error message.
  - pathstring
    Example
    body.buckets[2].allocations[0]
    Description
    Where in the request the error is about, when it is about one place, for example body.buckets[2]. Absent when the error is about the call as a whole.

500Internal server error. Nothing was committed.

ApiErrorResponse
Description
Error envelope returned by the CPQ REST endpoints, including Update Quote, Update Order, and PATCH /api/objects/{Quote,Order}/{id}. errorDetails is omitted when empty.
- statusinteger
  Example
  400
  Description
  HTTP status code.
- errorstring
  Example
  Failed to update quote
  Description
  Short error title.
- messagestring
  Description
  Human-readable message. For a single failure it matches the first errorDetails entry.
- errorDetailsErrorDetail[]
  Description
  One entry per failure, each with a semantic errorCode.
  - errorCodestring
    Example
    QUOTE_NOT_FOUND
    Description
    Semantic error code.
  - messagestring
    Description
    Human-readable error message.
  - pathstring
    Example
    body.buckets[2].allocations[0]
    Description
    Where in the request the error is about, when it is about one place, for example body.buckets[2]. Absent when the error is about the call as a whole.

curl

curl --request POST \
     --url https://api.nue.io/cpq/orders/{orderId}:update \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
     "isCommit": true,
     "recalc": "AUTO",
     "actions": [
     {
     "action": ""
     }
     ]
     }'

javascript

var myHeaders = new Headers();
myHeaders.append("accept", "application/json");
myHeaders.append("content-type", "application/json");

var raw = JSON.stringify({
   "isCommit": true,
   "recalc": "AUTO",
   "actions": [
      {
         "action": ""
      }
   ]
});

var requestOptions = {
   method: 'POST',
   headers: myHeaders,
   body: raw,
   redirect: 'follow'
};

fetch("https://api.nue.io/cpq/orders/{orderId}:update", requestOptions)
   .then(response => response.text())
   .then(result => console.log(result))
   .catch(error => console.log('error', error));

ruby

require "uri"
require "json"
require "net/http"

url = URI("https://api.nue.io/cpq/orders/{orderId}:update")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["accept"] = "application/json"
request["content-type"] = "application/json"
request.body = JSON.dump({
   "isCommit": true,
   "recalc": "AUTO",
   "actions": [
      {
         "action": ""
      }
   ]
})

response = https.request(request)
puts response.read_body

python

import requests
import json

url = "https://api.nue.io/cpq/orders/{orderId}:update"

payload = json.dumps({
   "isCommit": True,
   "recalc": "AUTO",
   "actions": [
      {
         "action": ""
      }
   ]
})
headers = {
   'accept': 'application/json',
   'content-type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

200

// The order was updated (or, with isCommit=false, previewed) successfully.
{
  "order": "",
  "orderProducts": [
    {}
  ],
  "warnings": [
    {
      "errorCode": "",
      "errorType": "",
      "message": ""
    }
  ]
}

400

// Invalid request — unknown action, conflicting actions, invalid or non-updatable field, non-editable line, failed business rule, or a stale expectedLastModified.
{
  "status": 400,
  "error": "Failed to update quote",
  "message": "",
  "errorDetails": [
    {
      "errorCode": "QUOTE_NOT_FOUND",
      "message": "",
      "path": "body.buckets[2].allocations[0]"
    }
  ]
}

500

// Internal server error. Nothing was committed.
{
  "status": 400,
  "error": "Failed to update quote",
  "message": "",
  "errorDetails": [
    {
      "errorCode": "QUOTE_NOT_FOUND",
      "message": "",
      "path": "body.buckets[2].allocations[0]"
    }
  ]
}