Create Order

create order this guide covers creating orders using the nue cpq order api the create order endpoint ( post /cpq/orders ) creates an order in draft status after activation, subscriptions, assets, and entitlements are provisioned automatically products are identified by productsku + uom , and the pricing engine resolves list prices, discounts, and totals the same way create quote works for change orders that modify existing subscriptions, see change orders docid\ flrvjtt xsk2gyx2nx96a all examples below use the commit endpoint ( post /cpq/orders ) to preview an order without persisting, replace the url with https //api nue io/cpq/orders\ preview the request body is identical for both modes authentication const myheaders = new headers(); myheaders append("nue api key", "your api key here"); myheaders append("content type", "application/json"); example products the examples in this guide reference the following products from the nue test catalog product sku uom list price revenue model nue platform nue platform user/month $15 00 recurring nue on salesforce nue on salesforce user/month $29 90 recurring implementation service implementation service hour $250 00 one time bundles bundle sku uom list price description nue gem edition nue gem edition user/month $0 00 mid tier bundle with required + bundled options bundle components component sku uom list price option type nue platform nue platform user/month $15 00 bundled (auto included) nue on salesforce nue on salesforce user/month $29 90 bundled (auto included) cpq module cpq module user/month $10 00 required (auto included) billing module billing module user/month $12 00 required (auto included) implementation service implementation service hour $250 00 optional (specify in addons) nue platform nue platform user/month $15 00 optional (specify in addons) usb security key usb security key each $45 00 optional (specify in addons) key behaviors behavior details product identification products are identified by productsku + uom , the same as create quote the pricing engine resolves the price book entry and calculates pricing pricing formula (recurring) listprice x quantity x term = listtotal pricing formula (one time) listprice x quantity = listtotal order status orders are created in draft status activation is a separate operation end date convention the api uses inclusive end dates a 12 month term starting 2026 01 01 results in subscriptionenddate of 2026 12 31 , not 2027 01 01 preview mode use post /cpq/orders\ preview for a dry run that returns the priced order without persisting bundle handling bundles auto expand bundled and required items optional add ons are specified via the addons array, identical to create quote use case 1 basic order creation ( post /cpq/orders ) create an order with a single recurring product you must provide the customerid , subscriptionstartdate , and at least one product with its productsku and uom the pricebookid is optional if omitted, the org's active standard price book is used request body { "customerid" "001xx000003abc123", "pricebookid" "01sxx000001abc123", "subscriptionstartdate" "2026 01 01", "subscriptionenddate" "2027 01 01", "subscriptionterm" 12, "subscriptiontermdimension" "month", "products" \[ { "productsku" "nue platform", "uom" "user/month", "quantity" 10 } ] } curl curl x post 'https //api nue io/cpq/orders' \\ h 'nue api key your api key here' \\ h 'content type application/json' \\ d '{ "customerid" "001xx000003abc123", "pricebookid" "01sxx000001abc123", "subscriptionstartdate" "2026 01 01", "subscriptionenddate" "2027 01 01", "subscriptionterm" 12, "subscriptiontermdimension" "month", "products" \[ { "productsku" "nue platform", "uom" "user/month", "quantity" 10 } ] }' javascript fetch const myheaders = new headers(); myheaders append("nue api key", "your api key here"); myheaders append("content type", "application/json"); const orderdata = { customerid "001xx000003abc123", pricebookid "01sxx000001abc123", subscriptionstartdate "2026 01 01", subscriptionenddate "2027 01 01", subscriptionterm 12, subscriptiontermdimension "month", products \[ { productsku "nue platform", uom "user/month", quantity 10 } ] }; fetch('https //api nue io/cpq/orders', { method 'post', headers myheaders, body json stringify(orderdata) }) then(response => response json()) then(result => { console log(`order status ${result order status}`); console log(`order products ${result orderproducts length}`); }) catch(error => console log('error ', error)); the order is created in draft status the pricing engine resolves the list price from the price book entry matching nue platform + user/month after activation, subscriptions, assets, and entitlements are provisioned use case 2 multiple products add multiple products to the products array each product resolves independently against the price book recurring and one time products can be mixed in the same order request body { "customerid" "001xx000003abc123", "pricebookid" "01sxx000001abc123", "subscriptionstartdate" "2026 01 01", "subscriptionenddate" "2027 01 01", "subscriptionterm" 12, "subscriptiontermdimension" "month", "products" \[ { "productsku" "nue on salesforce", "uom" "user/month", "quantity" 10 }, { "productsku" "nue platform", "uom" "user/month", "quantity" 5 }, { "productsku" "implementation service", "uom" "hour", "quantity" 20 } ] } curl curl x post 'https //api nue io/cpq/orders' \\ h 'nue api key your api key here' \\ h 'content type application/json' \\ d '{ "customerid" "001xx000003abc123", "pricebookid" "01sxx000001abc123", "subscriptionstartdate" "2026 01 01", "subscriptionenddate" "2027 01 01", "subscriptionterm" 12, "subscriptiontermdimension" "month", "products" \[ { "productsku" "nue on salesforce", "uom" "user/month", "quantity" 10 }, { "productsku" "nue platform", "uom" "user/month", "quantity" 5 }, { "productsku" "implementation service", "uom" "hour", "quantity" 20 } ] }' javascript fetch const orderdata = { customerid "001xx000003abc123", pricebookid "01sxx000001abc123", subscriptionstartdate "2026 01 01", subscriptionenddate "2027 01 01", subscriptionterm 12, subscriptiontermdimension "month", products \[ { productsku "nue on salesforce", uom "user/month", quantity 10 }, { productsku "nue platform", uom "user/month", quantity 5 }, { productsku "implementation service", uom "hour", quantity 20 } ] }; fetch('https //api nue io/cpq/orders', { method 'post', headers myheaders, body json stringify(orderdata) }) then(response => response json()) then(result => { console log(`order products ${result orderproducts length}`); // 3 }) catch(error => console log('error ', error)); recurring products are priced at listprice x quantity x term one time products are priced at listprice x quantity (no term multiplier) use case 3 order with bundles bundle products are added the same way as in create quote the pricing engine auto expands bundled and required items optional add ons are specified via the addons array request body { "customerid" "001xx000003abc123", "pricebookid" "01sxx000001abc123", "subscriptionstartdate" "2026 01 01", "subscriptionenddate" "2027 01 01", "subscriptionterm" 12, "subscriptiontermdimension" "month", "products" \[ { "productsku" "nue gem edition", "uom" "user/month", "quantity" 10, "addons" \[ { "productsku" "implementation service", "uom" "hour", "quantity" 20 } ] } ] } curl curl x post 'https //api nue io/cpq/orders' \\ h 'nue api key your api key here' \\ h 'content type application/json' \\ d '{ "customerid" "001xx000003abc123", "pricebookid" "01sxx000001abc123", "subscriptionstartdate" "2026 01 01", "subscriptionenddate" "2027 01 01", "subscriptionterm" 12, "subscriptiontermdimension" "month", "products" \[ { "productsku" "nue gem edition", "uom" "user/month", "quantity" 10, "addons" \[ { "productsku" "implementation service", "uom" "hour", "quantity" 20 } ] } ] }' javascript fetch const orderdata = { customerid "001xx000003abc123", pricebookid "01sxx000001abc123", subscriptionstartdate "2026 01 01", subscriptionenddate "2027 01 01", subscriptionterm 12, subscriptiontermdimension "month", products \[ { productsku "nue gem edition", uom "user/month", quantity 10, addons \[ { productsku "implementation service", uom "hour", quantity 20 } ] } ] }; fetch('https //api nue io/cpq/orders', { method 'post', headers myheaders, body json stringify(orderdata) }) then(response => response json()) then(result => { console log(`order products ${result orderproducts length}`); }) catch(error => console log('error ', error)); the bundle auto expands its bundled items (nue platform, nue on salesforce) and required items (cpq module, billing module) the implementation service optional add on is included because it is specified in the addons array use case 4 order with billing options control billing behavior by specifying billingperiod at the order level or on individual products request body { "customerid" "001xx000003abc123", "pricebookid" "01sxx000001abc123", "subscriptionstartdate" "2026 01 01", "subscriptionenddate" "2027 01 01", "subscriptionterm" 12, "subscriptiontermdimension" "month", "billingperiod" "month", "products" \[ { "productsku" "nue platform", "uom" "user/month", "quantity" 25, "billingperiod" "month", "billingtiming" "in advance" } ] } curl curl x post 'https //api nue io/cpq/orders' \\ h 'nue api key your api key here' \\ h 'content type application/json' \\ d '{ "customerid" "001xx000003abc123", "pricebookid" "01sxx000001abc123", "subscriptionstartdate" "2026 01 01", "subscriptionenddate" "2027 01 01", "subscriptionterm" 12, "subscriptiontermdimension" "month", "billingperiod" "month", "products" \[ { "productsku" "nue platform", "uom" "user/month", "quantity" 25, "billingperiod" "month", "billingtiming" "in advance" } ] }' javascript fetch const orderdata = { customerid "001xx000003abc123", pricebookid "01sxx000001abc123", subscriptionstartdate "2026 01 01", subscriptionenddate "2027 01 01", subscriptionterm 12, subscriptiontermdimension "month", billingperiod "month", products \[ { productsku "nue platform", uom "user/month", quantity 25, billingperiod "month", billingtiming "in advance" } ] }; fetch('https //api nue io/cpq/orders', { method 'post', headers myheaders, body json stringify(orderdata) }) then(response => response json()) then(result => { console log(`order products ${result orderproducts length}`); }) catch(error => console log('error ', error)); use case 5 preview order ( post /cpq/orders\ preview ) use the preview endpoint to validate your payload and inspect pricing without creating the order the request body is identical to the commit endpoint curl curl x post 'https //api nue io/cpq/orders\ preview' \\ h 'nue api key your api key here' \\ h 'content type application/json' \\ d '{ "customerid" "001xx000003abc123", "pricebookid" "01sxx000001abc123", "subscriptionstartdate" "2026 01 01", "subscriptionenddate" "2027 01 01", "subscriptionterm" 12, "subscriptiontermdimension" "month", "products" \[ { "productsku" "nue platform", "uom" "user/month", "quantity" 10 } ] }' javascript fetch const orderdata = { customerid "001xx000003abc123", pricebookid "01sxx000001abc123", subscriptionstartdate "2026 01 01", subscriptionenddate "2027 01 01", subscriptionterm 12, subscriptiontermdimension "month", products \[ { productsku "nue platform", uom "user/month", quantity 10 } ] }; fetch('https //api nue io/cpq/orders\ preview', { method 'post', headers myheaders, body json stringify(orderdata) }) then(response => response json()) then(result => { console log('order preview ', result); }) catch(error => console log('error ', error)); preview mode runs the full pricing engine but writes nothing to the database use it for pricing previews, validation, and what if scenarios before committing the preview response is shaped identically to the commit response with one difference order id is null because nothing is persisted use case 6 activate a draft order orders are created in draft status to activate the order — provisioning subscriptions, assets, and entitlements — send a patch against the order object curl x patch "https //api nue io/api/objects/order/$order id" \\ h "nue api key your api key here" \\ h "content type application/json" \\ d '{"status" "activated"}' a successful activation returns 200 with an empty body the order's status becomes activated and activateddate is set to the activation timestamp permission required the activation endpoint requires the api key to have the manage salesforce orders permission without it, the call returns 403 insufficient permissions — required permission manage salesforce orders grant the permission in the nue admin under api keys common errors error message likely cause fix invalid field for order \<fieldname> top level field is not on your tenant's order metadata the endpoint validates every top level field against order describe() either remove the field, or add it as a custom field on order in salesforce run get /api/metadata/objects/order to see what your tenant accepts customerid is required missing customerid provide the customer (account) id missing field value products products array is missing or empty provide at least one product product at index n validation failed only one of \[productsku, productname] should be set both productsku and productname were set, or neither was set set exactly one product at index n validation failed only one of \[discount, discountamount] should be set both discount and discountamount were supplied on the same line pick one the pricebookentryid is required unless custom pricing attributes and uom are supplied a top level product line was sent with no pricebookentryid , no uom , and no custompricingattributes supply at least one of the three so the pricing engine can resolve a unique pbe no pricebook entry found for product \<sku>\[\<id>] in pricebook \<pb> with filters currency=…, uom=…, \<attr>=… the (pricebookid × currency × uom × pricing attributes) tuple resolved to zero pbes verify each filter dimension; check that the product has a pbe matching every dimension you supplied the specified pricebookentryid 'x' does not match the resolved pricing attribute conditions for product 'y' a specific pricebookentryid was set on a line (or on a bundle option), but that pbe is not in the candidate list resolved from the order's currency + pricing attribute conditions either change the order context (e g supply an opportunity that yields a matching pricing attribute), or set a different pricebookentryid that matches the order's resolved conditions, or omit pricebookentryid and let the engine pick by specificity invalid date value …, required format is yyyy mm dd date field was sent in the wrong format use iso yyyy mm dd 403 insufficient permissions (on activation patch) api key lacks manage salesforce orders grant the permission to the api key request reference order header fields field type required description customerid string yes the customer account id products array yes list of products to add to the order must contain at least one entry pricebookid string no the price book id to use for the order if omitted, defaults to the org's active standard price book recommended when using custom price books subscriptionstartdate date no subscription start date (yyyy mm dd) defaults to today subscriptionenddate date no subscription end date; calculated from start date + term if not provided the api uses an inclusive end date, so a 12 month term starting 2026 01 01 results in an end date of 2026 12 31 subscriptionterm number no subscription term length (e g , 12 for 12 months) derived from start + end if subscriptionenddate is provided subscriptiontermdimension string no month or year billingperiod string no billing period at the order header pass one of month , quarter , semi annual , annual (at the header these are picklist values; labels like monthly are rejected the per line products\[] billingperiod accepts both labels and values ) billcycleday string no day of the month the billing cycle starts (e g , 1st of month ) billingaccountid string no the billing account id currencyisocode string no iso currency code for multi currency orgs defaults to the customer's account currencyisocode ignored in single currency orgs opportunityid string no salesforce opportunity id when provided, the pricing engine uses opportunity derived pricing attribute conditions (e g opportunity type) to filter candidate price book entries name string no optional human readable order name description string no order description pricetags array no order level price/discount tags in addition to the fields above, the endpoint accepts any creatable field that exists on your order object metadata (custom fields and tenant specific standard fields) fields not present on the metadata are rejected with invalid field for order \<fieldname> use get /api/metadata/objects/order to list what your tenant exposes product input fields field type required description productsku string yes product sku exactly one of productsku or productname must be set productname string yes product name (alternative to sku) pricebookentryid string conditional specific pbe id disambiguates lookup when the product has multiple pbes uom string conditional unit of measure name (e g user/month ) custompricingattributes array conditional custom pbe field values for multi attribute pricing resolution quantity number yes (top level) product quantity required for top level products for bundle add ons, defaults to the bundle option's defaultquantity startdate date no per product start date override enddate date no per product end date override subscriptionterm number no per product term override subscriptiontermdimension string no month or year discount number no discretionary discount percentage (0 100) discountamount number no discretionary discount amount mutually exclusive with discount billingperiod string no per product billing period override per line, both label ( monthly ) and api value ( month ) are accepted billingtiming string no per product billing timing in advance or in arrears autorenew boolean no per product auto renew override evergreen boolean no whether the product is evergreen (no fixed term) renewalterm number no renewal term override pricetags array no line level price/discount tags addons array no optional add on products for bundles (recursive productinput) exactly one of productsku or productname is required passing both — or neither — returns product sku and name exclusive for top level products, supply at least one of pricebookentryid , uom , or custompricingattributes so the pricing engine can resolve a unique price book entry bundle add ons can omit all three — the bundle option's metadata supplies the defaults quantity is required for top level products for bundle add ons it defaults to the option's defaultquantity custompricingattributes — name format when supplying custompricingattributes , the name must be the full salesforce field api name on pricebookentry , including the package namespace prefix and c suffix bare names without the prefix return invalid field \<name> for pricebookentry examples of valid names ruby pricingattribute 3 c (one of the slot fields) ruby segment c (any custom picklist field on pbe that has been registered as a custom pricing attribute via the usecustomfieldsaspricingattributes system setting) response reference the response contains the created order and its order products response fields field type description order object the order header record order id string the order id ( null in preview mode) order status string order status ( draft for committed orders, null for previews) order totalamount number total order amount calculated by the pricing engine order subscriptionstartdate date subscription start date order subscriptionenddate date subscription end date (inclusive see end date convention above) orderproducts array array of order product records orderproducts\[] productname string resolved product name orderproducts\[] quantity number product quantity orderproducts\[] listprice number unit list price resolved from the price book entry orderproducts\[] totalprice number total price for this line orderproducts\[] childrenorderproducts array child order products for bundle items summary use case products key concept 1 basic order nue platform x 10 sku + uom identification, pricing engine resolution 2 multiple products recurring + one time multiple products in one order 3 bundles nue gem edition + implementation service add on auto expansion, addons for optional items 4 billing options nue platform with billing overrides per product billing period and timing 5 preview nue platform via \ preview dry run pricing without persisting 6 activate draft order patch /api/objects/order/{id} promotes draft → activated, provisions subscriptions/assets/entitlements