---
title: Create Order Overview
slug: create-order-overview
createdAt: 2026-03-17T21:13:53.446Z
---

# Create Order Overview

The Nue CPQ Order APIs provide REST endpoints for creating orders and change orders that directly provision subscriptions, assets, and entitlements. Unlike the Quote APIs, which are designed for pricing previews and approval workflows, the Order APIs are built for direct execution -- you submit an order, and the system creates the full downstream object graph in a single call.

There are two primary endpoints:

- **Create Order** (`POST /cpq/orders`) -- Creates a new order with one or more order products in `Draft` status. After activation, subscriptions, assets, and entitlements are provisioned.
- **Change Order** (`POST /cpq/change-order`) -- Modifies existing subscriptions by creating a change order. Supports renewals, quantity changes, cancellations, upgrades, downgrades, and more.

## Endpoints

| Endpoint              | Method | Description                                        |
| --------------------- | ------ | -------------------------------------------------- |
| `/cpq/orders`         | POST   | Create and activate an order (commit mode)         |
| `/cpq/orders:preview` | POST   | Preview an order without persisting (dry-run mode) |

## Create Order vs Create Quote

The Create Order and Create Quote APIs share the same product identification and pricing engine, but serve different purposes in the lifecycle.

| Feature                    | Create Quote (`/cpq/quotes`)                                          | Create Order (`/cpq/orders`)                                                  |
| -------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| **Product identification** | `productSku` + `uom` (or `productName` + `uom`)                       | `productSku` + `uom` (or `productName` + `uom`)                               |
| **Pricing resolution**     | Pricing engine resolves list price, discounts, price tags, and totals | Same pricing engine -- resolves list price, discounts, price tags, and totals |
| **Preview mode**           | Yes (`:preview` endpoint for dry-run)                                 | Yes (`:preview` endpoint for dry-run)                                         |
| **Required header fields** | `opportunityId`, `name`                                               | `customerId` (everything else falls back to tenant defaults)                  |
| **Output**                 | Quote + Quote Line Items                                              | Order + Order Products + Subscriptions + Assets + Entitlements                |
| **Activation**             | Separate activation step required                                     | Orders are created in Draft status; activation is a separate step             |
| **Change support**         | Create a new quote                                                    | Change Order endpoint for modifying existing subscriptions                    |
| **Bundle handling**        | Auto-expands bundles, optional add-ons via `addOns`                   | Auto-expands bundles, optional add-ons via `addOns`                           |

### When to Use Create Quote

- You need a pricing preview or what-if scenario before committing
- You are building a quoting workflow with approval steps
- You want to associate the quote with an Opportunity for Salesforce workflows

### When to Use Create Order

- You want to create an order directly without a quoting workflow
- You need the full provisioning result -- subscriptions, assets, and entitlements -- after activation
- You are making changes to existing subscriptions via the Change Order endpoint

## Order Lifecycle

When you create and then activate an order, the following sequence occurs:

1. **Order Created** -- The order is created in `Draft` status, then activated
2. **Order Products Created** -- Each item in the `products` array becomes an Order Product record
3. **Subscriptions Provisioned** -- Recurring products generate Subscription records with the specified start date, end date, and term
4. **Assets Created** -- Asset records are created to represent the customer's entitlement to each product
5. **Entitlements Created** -- Entitlement records are created to track what the customer has access to

Orders are created in `Draft` status. Subscriptions, assets, and entitlements are **not** provisioned until the order is activated separately.

## Change Order Types

Change orders modify existing subscriptions. Each change is identified by an `assetNumber` and a `changeType`. The following change types are supported:

| Change Type        | Description                                                                       |
| ------------------ | --------------------------------------------------------------------------------- |
| `Renew`            | Extend a subscription for a new term beyond its current end date                  |
| `UpdateQuantity`   | Increase or decrease the quantity on an existing subscription                     |
| `UpdateTerm`       | Modify the subscription term without changing other attributes                    |
| `CoTerm`           | Align a subscription's end date with another subscription (co-termination)        |
| `Cancel`           | Cancel an active subscription as of a specified effective date                    |
| `Reconfigure`      | Modify add-ons or components within a bundle subscription                         |
| `AdjustPrice`      | Change the pricing on an existing subscription without modifying quantity or term |
| `ConvertFreeTrial` | Convert a free trial subscription to a paid subscription                          |
| `Upgrade`          | Replace the current product with a higher-tier product                            |
| `Downgrade`        | Replace the current product with a lower-tier product                             |
| `Swap`             | Replace the current product with a different product (lateral move)               |

## Change Order Processing Options

The `proceedOption` field determines how a change order is processed:

| Proceed Option     | Description                                                                     |
| ------------------ | ------------------------------------------------------------------------------- |
| `CreateOrder`      | Create a new order for the changes and optionally activate it                   |
| `UseExistingOrder` | Add the changes to an existing draft order (requires `containedObjectId`)       |
| `CreateQuote`      | Create a quote for the changes, enabling an approval workflow before activation |
| `UseExistingQuote` | Add the changes to an existing draft quote (requires `containedObjectId`)       |

:::hint{type="info"}
**Partner payout is not set by these endpoints.** `POST /cpq/change-order` and `POST /cpq/change-order:preview` ignore a top-level `partnerPayoutPercentage` or `partnerPayoutAmount`: the request succeeds and nothing is written (the preview is unaffected). Create the change quote or order first, then set the payout with [Update Quote](docId\:J9W7UfHJvphiEJ93BX5y9) or [Update Order](docId\:Gm0OXVHu351idX6gf9oQa).
:::

## Authentication

All CPQ Order API requests require authentication using your Nue API key in the `nue-api-key` header:

```javascript
const myHeaders = new Headers();
myHeaders.append("nue-api-key", "YOUR_API_KEY_HERE");
myHeaders.append("Content-Type", "application/json");
```

```bash
curl -X POST 'https://api.nue.io/cpq/orders' \
  -H 'nue-api-key: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
```

### Partner payout inputs

Create Order accepts the same partner payout header fields as [Create Quote](docId\:BC-IdxYnwAUS7O9EFYCwq). Send `partnerPayoutPercentage` (shown as **Partner Discount %** in the Line Editor) **or** `partnerPayoutAmount` (**Partner Payout**) and Nue derives the other, so an order written through the API ends up with consistent values.

| You send                  | Nue derives                                                                                                      |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `partnerPayoutPercentage` | `partnerPayoutAmount` = percentage x the record's total price                                                    |
| `partnerPayoutAmount`     | `partnerPayoutPercentage` = amount / the record's total price x 100. The amount is stored exactly as you sent it |

Use the Nue field names above. The Salesforce names (`Ruby__PartnerPayoutPercentage__c`, `Ruby__PartnerPayoutAmount__c`) are rejected over REST with `400 Invalid field`.

:::hint{type="warning"}
**Send one, not both.** A request that carries both `partnerPayoutPercentage` and `partnerPayoutAmount` returns `400` (`PARTNER_DISCOUNT_AND_PAYOUT_MUTUALLY_EXCLUSIVE`).

| Condition                                                                                                         | Error                            |
| ----------------------------------------------------------------------------------------------------------------- | -------------------------------- |
| `partnerPayoutPercentage` below 0 or above 100                                                                    | `INVALID_PARTNER_DISCOUNT_RANGE` |
| `partnerPayoutAmount` below 0, greater than the total price, or greater than 0 on a record whose total price is 0 | `INVALID_PARTNER_PAYOUT_RANGE`   |

When you send a percentage and every product is usage-priced, the payout does not apply and the response carries a `PARTNER_DISCOUNT_NOT_APPLICABLE` warning instead of an error.
:::

## Create Order Response

When an order is created, the response includes:

- **`order`** -- The order header object with status, dates, and totals
- **`orderProducts`** -- Array of order products; bundle parents include nested children

## Change Order Response

When a change order is created and activated, the response includes:

- **`headerObjectIds`** -- The IDs of created orders or quotes
- **`messages`** -- Status messages for the operation
- **`subscriptions`** -- Updated subscription records
- **`assets`** -- Updated asset records
- **`entitlements`** -- Updated entitlement records
- **`invoices`** -- Invoice records generated for prorated charges (if billing is enabled)

## Next Steps

- [Create Order](docId\:ymMGzRHX6rmiK18clYKYl) -- Detailed guide with use cases for creating orders and change orders