Preview a new order without persisting it (isCommit=false). Runs the full pricing engine — product resolution, bundle expansion, price tags, discounts — and returns the priced order, but does not write to the database.
Use this endpoint to validate payloads and inspect pricing before committing.
", "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" } ], "queryParameters": [], "bodyDataParameters": [ { "kind": "required", "name": "body", "type": "object", "example": "{\"customerId\":\"001xx000003GYn1AAG\",\"priceBookId\":\"01sxx000000ABCDEF\",\"subscriptionStartDate\":\"2026-01-01\",\"subscriptionTerm\":12,\"subscriptionTermDimension\":\"Month\",\"currencyIsoCode\":\"USD\",\"billingPeriod\":\"Month\",\"products\":[{\"productSku\":\"PLATFORM-BASE\",\"uom\":\"Each\",\"quantity\":1}]}", "examples": [ { "label": "Simple order with one product", "value": "{\"customerId\":\"001xx000003GYn1AAG\",\"priceBookId\":\"01sxx000000ABCDEF\",\"subscriptionStartDate\":\"2026-01-01\",\"subscriptionTerm\":12,\"subscriptionTermDimension\":\"Month\",\"currencyIsoCode\":\"USD\",\"billingPeriod\":\"Month\",\"products\":[{\"productSku\":\"PLATFORM-BASE\",\"uom\":\"Each\",\"quantity\":1}]}" } ], "description": "Order properties, products, and price tags
", "customType": "NewCreateOrderRequest", "schema": [ { "name": "customerId", "kind": "required", "type": "string", "description": "The customer (account) ID.
" }, { "name": "priceBookId", "kind": "optional", "type": "string", "description": "The price book ID used for this order. Optional — defaults to the org's active Standard Price Book.
" }, { "name": "billingAccountId", "kind": "optional", "type": "string", "description": "The billing account ID. Optional — defaults to the customer's billing account.
" }, { "name": "billingPeriod", "kind": "optional", "type": "stringBilling period at the order header. Accepts the values defined on Order.BillingPeriod__c: Month, Quarter, Semi-Annual, Annual. Note: at the header, pass the picklist value, not the label (Monthly is rejected — use Month). At the per-line level (products[].billingPeriod), both label and value are accepted.
ISO currency code for the order. In multi-currency orgs, defaults to the customer's Account.CurrencyIsoCode. In single-currency orgs the field is ignored.
Subscription end date. Optional — derived from subscriptionStartDate + subscriptionTerm if omitted. The API uses an inclusive end date convention.
Subscription term length. Optional — derived from start + end if subscriptionEndDate is provided, or falls back to the product's default subscription term.
Whether recurring items will auto-renew. Tenant-dependent — only accepted if Order.AutoRenew__c exists on the tenant's Order metadata.
Invoice payment schedule. Tenant-dependent — only accepted if Order.PaymentTerm__c exists on the tenant's Order metadata.
Salesforce Opportunity ID. When provided, the pricing engine uses Opportunity-derived pricing-attribute conditions to filter the candidate Price Book Entries.
" }, { "name": "name", "kind": "optional", "type": "string", "description": "Optional human-readable order name.
" }, { "name": "partnerPayoutPercentage", "kind": "optional", "type": "number", "description": "Partner payout as a percentage (0-100), shown as Partner Discount % in the Line Editor. Send this or partnerPayoutAmount, not both; Nue derives the other.
" }, { "name": "partnerPayoutAmount", "kind": "optional", "type": "number", "description": "Partner payout as a fixed amount. Send this or partnerPayoutPercentage, not both; Nue derives the percentage from the record's total price and stores the amount as sent.
" }, { "name": "products", "kind": "required", "type": "array", "description": "Products to add to the order. At least one product is 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.
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.
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.
Number of units. Required for top-level products. For add-ons, defaults to the bundle option's DefaultQuantity.
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.
Per-product start date override. Defaults to the quote header's start date.
", "example": "2025-01-01", "format": "date" }, { "name": "endDate", "kind": "optional", "type": "stringPer-product end date override. If subscriptionTerm is provided, the end date is calculated from startDate + subscriptionTerm.
Per-product subscription term override. Must be > 0. Defaults to the quote header's term.
", "example": 12, "minimum": 0 }, { "name": "subscriptionTermDimension", "kind": "optional", "type": "stringWhether 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.
Billing period override. Per-line, both label (Monthly) and API value (Month) are accepted. Top-level header billingPeriod requires the API value.
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.
Discretionary discount amount (currency). Ignored if discount is also provided.
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.
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.
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": "mapPer-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": "stringThe 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": "mapOrder-level price tags.
", "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" } ] } ], "modelRef": "#/components/schemas/NewCreateOrderRequest", "isExpanded": true } ], "formDataParameters": [], "oAuthParameters": [ { "id": "ApiKeyAuth", "name": "nue-api-key", "kind": "optional", "type": "apiKey", "in": "header" } ], "cookieParameters": [] }, "responses": [ { "statusCode": "200", "description": "Order preview calculated successfully (not persisted)
", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "Response from POST /cpq/orders containing the created order and its products.
", "customType": "CreateOrderCompositeResponse", "schema": [ { "name": "order", "kind": "optional", "type": "map", "description": "The created order record with all field values", "example": "", "customType": "mapError envelope returned by the CPQ REST endpoints, including Update Quote, Update Order, and PATCH /api/objects/{Quote,Order}/{id}. errorDetails is omitted when empty.
Human-readable message. For a single failure it matches the first errorDetails entry.
" }, { "name": "errorDetails", "kind": "optional", "type": "array", "description": "One entry per failure, each with a semantic errorCode.
", "modelRef": "#/components/schemas/ErrorDetail", "customType": "ErrorDetail[]", "schema": [ { "name": "errorCode", "kind": "optional", "type": "string", "description": "Semantic error code.", "example": "QUOTE_NOT_FOUND" }, { "name": "message", "kind": "optional", "type": "string", "description": "Human-readable error message.
" }, { "name": "path", "kind": "optional", "type": "string", "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.
", "example": "body.buckets[2].allocations[0]" } ] } ], "modelRef": "#/components/schemas/ApiErrorResponse", "isExpanded": true } ] }, { "statusCode": "401", "description": "Unauthorized", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "Error response", "customType": "ErrorResponse", "schema": [ { "name": "code", "kind": "optional", "type": "integer", "description": "HTTP status code", "example": 400 }, { "name": "message", "kind": "optional", "type": "string", "description": "Error message", "example": "Bad Request" }, { "name": "details", "kind": "optional", "type": "string", "description": "Detailed error information", "example": "Required field 'name' is missing" } ], "modelRef": "#/components/schemas/ErrorResponse", "isExpanded": true } ] } ], "hasXCodeSamples": false, "examples": { "languages": [ { "id": "example-0-curl", "language": "curl", "label": "cURL", "code": "curl --request POST \\\n --url https://api.nue.io/cpq/orders:preview \\\n --header 'accept: application/json' \\\n --header 'content-type: application/json' \\\n --data '{\n \"customerId\": \"\",\n \"products\": [\n {\n \"customPricingAttributes\": [\n {\n \"name\": \"Ruby__PricingAttribute_3__c\",\n \"value\": \"New Business\"\n }\n ]\n }\n ]\n }'" }, { "id": "example-1-javascript", "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 \"customerId\": \"\",\n \"products\": [\n {\n \"customPricingAttributes\": [\n {\n \"name\": \"Ruby__PricingAttribute_3__c\",\n \"value\": \"New Business\"\n }\n ]\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/orders:preview\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));" }, { "id": "example-2-ruby", "language": "ruby", "label": "Ruby", "code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://api.nue.io/cpq/orders:preview\")\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 \"customerId\": \"\",\n \"products\": [\n {\n \"customPricingAttributes\": [\n {\n \"name\": \"Ruby__PricingAttribute_3__c\",\n \"value\": \"New Business\"\n }\n ]\n }\n ]\n})\n\nresponse = https.request(request)\nputs response.read_body\n" }, { "id": "example-3-python", "language": "python", "label": "Python", "code": "import requests\nimport json\n\nurl = \"https://api.nue.io/cpq/orders:preview\"\n\npayload = json.dumps({\n \"customerId\": \"\",\n \"products\": [\n {\n \"customPricingAttributes\": [\n {\n \"name\": \"Ruby__PricingAttribute_3__c\",\n \"value\": \"New Business\"\n }\n ]\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": "example-0-curl" }, "results": { "languages": [ { "id": "response-0-200", "language": "200", "code": "// Order preview calculated successfully (not persisted)\n{\n \"order\": \"\",\n \"orderProducts\": [\n {}\n ]\n}" }, { "id": "response-1-400", "language": "400", "code": "// Invalid request\n{\n \"status\": 400,\n \"error\": \"Failed to update quote\",\n \"message\": \"\",\n \"errorDetails\": [\n {\n \"errorCode\": \"QUOTE_NOT_FOUND\",\n \"message\": \"\",\n \"path\": \"body.buckets[2].allocations[0]\"\n }\n ]\n}" }, { "id": "response-2-401", "language": "401", "code": "// Unauthorized\n{\n \"code\": 400,\n \"message\": \"Bad Request\",\n \"details\": \"Required field 'name' is missing\"\n}" } ], "selectedLanguageId": "response-0-200" } }, "children": [ { "text": "" } ] }