--- title: Create Order slug: ymMG-create-order docTags: createdAt: 2026-03-17T21:13:53.778Z --- # 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 ```javascript 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:** ```json { "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:** ```bash 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:** ```javascript 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:** ```json { "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:** ```bash 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:** ```javascript 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:** ```json { "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:** ```bash 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:** ```javascript 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:** ```json { "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:** ```bash 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:** ```javascript 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:** ```bash 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:** ```javascript 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. ```bash 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. :::BlockQuote **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: ` | 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 [] in pricebook with filters: currency=…, uom=…, =…` | 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: `. 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 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 |