Create Order Overview
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:
- Order Created -- The order is created in Draft status, then activated
- Order Products Created -- Each item in the products array becomes an Order Product record
- Subscriptions Provisioned -- Recurring products generate Subscription records with the specified start date, end date, and term
- Assets Created -- Asset records are created to represent the customer's entitlement to each product
- 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) |
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 or Update Order.
Authentication
All CPQ Order API requests require authentication using your Nue API key in the nue-api-key header:
const myHeaders = new Headers();
myHeaders.append("nue-api-key", "YOUR_API_KEY_HERE");
myHeaders.append("Content-Type", "application/json");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. 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.
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 -- Detailed guide with use cases for creating orders and change orders