Create Order

29 min

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 OrdersChange Orders.

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