---
name: nue-rest-create-quote-order
description: Specialist in Nue REST API for creating quotes and orders (POST /cpq/quotes and POST /cpq/orders). Use when generating curl commands or REST payloads for creating new business quotes or orders with products, bundles, discounts, and subscription terms via the Nue Platform API.
user-invocable: false
---

# Create Quote & Create Order — REST API

Given a business scenario (products, discounts, terms, bundles), produce a complete REST API call (curl or JSON payload) that creates the quote or order via the Nue Platform API. Validate field names, enum values, and payload structure against the rules below.

> **Note**: This skill covers the **REST API** (`/cpq/quotes` and `/cpq/orders`). For the Apex global methods (`Ruby.GlobalQuoteServiceAPI.createQuote` and `Ruby.GlobalOrderServiceAPI.createOrder`), see the companion [Apex Skill](../nue-create-quote-order/SKILL.md).

> **Note**: This skill covers **new business** — initial quotes and orders. For modifications to existing subscriptions (renewals, expansions, cancellations, upgrades), see the [Change Order REST Skill](nue-rest-change-order.md).

> **Note**: To change a quote or Draft order that **already exists** — header fields, line edits, adding or removing lines, reconfiguring a bundle, price tags — see the [Update Quote & Order REST Skill](nue-rest-update-quote-order.md) (`POST /cpq/quotes/{quoteId}:update`). Do **not** re-create the record to change it.

---

## Endpoints

| Operation | Endpoint | Description |
|-----------|----------|-------------|
| Create Quote (commit) | `POST /cpq/quotes` | Persists quote + line items |
| Create Quote (preview) | `POST /cpq/quotes:preview` | Full pricing, no persistence. `quote.id` is `null` |
| Create Order (commit) | `POST /cpq/orders` | Persists order + order items. Created in Draft status |
| Create Order (preview) | `POST /cpq/orders:preview` | Full pricing, no persistence. `order.id` is `null` |

**Base URLs:**
- Production: `https://api.nue.io`
- QA3: `https://api.qa3.nue.io`
- Perftest: `https://api.perftest.nue.io`

**Authentication:**
```
nue-api-key: YOUR_API_KEY
Content-Type: application/json
```

---

## Request Fields — Create Quote

### Header Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Quote name/identifier |
| `opportunityId` | string | Yes | Associated Salesforce Opportunity ID |
| `priceBookId` | string | No | Price Book ID. Defaults to active Standard Price Book |
| `subscriptionStartDate` | date | No | YYYY-MM-DD. Defaults to today |
| `subscriptionEndDate` | date | No | Calculated from start + term if omitted |
| `subscriptionTerm` | number | No | Term length (e.g., 12) |
| `subscriptionTermDimension` | string | No | `"Month"` or `"Year"`. Defaults to `"Month"` |
| `discount` | number | No | Header-level discount % (0-100). Propagates to all undiscounted lines |
| `discountAmount` | number | No | Header-level discount in currency units |
| `currencyIsoCode` | string | No | ISO currency code for multi-currency orgs |
| `products` | array | Yes | List of product inputs |
| `priceTags` | array | No | Quote-level price/discount tags (`{code, id}`) |

### Header Fields — Create Order (Differences from Quote)

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `customerId` | string | Yes | Customer Account ID (replaces `opportunityId`) |
| `name` | string | No | Order name (optional for orders) |
| `opportunityId` | string | No | Optional for orders |
| `billingPeriod` | string | No | `"Month"`, `"Quarter"`, `"Semi-Annual"`, `"Annual"` |
| `billCycleDay` | string | No | Day of month billing cycle starts |
| `billingAccountId` | string | No | Billing account ID |
| `autoRenew` | boolean | No | Auto-renew for all products |
| `paymentTerm` | string | No | Invoice payment schedule |
| `description` | string | No | Order description |

### Product Input Fields (Both Quote and Order)

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `productSku` | string | Yes* | Product SKU. *Either SKU or name required; SKU takes precedence |
| `productName` | string | Yes* | Product name (alternative to SKU) |
| `uom` | string | Conditional | Unit of Measure. Required unless `priceBookEntryId` provided |
| `quantity` | number | No | Product quantity. Defaults vary by product |
| `priceBookEntryId` | string | No | Direct PBE reference; bypasses UOM resolution |
| `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 | Line-level discount % (0-100). Overrides header |
| `discountAmount` | number | No | Line-level discount amount |
| `billingPeriod` | string | No | `"Month"`, `"Quarter"`, `"Semi-Annual"`, `"Annual"` |
| `billingTiming` | string | No | `"In Advance"` or `"In Arrears"` |
| `autoRenew` | boolean | No | Per-product auto-renew |
| `evergreen` | boolean | No | Cannot combine with `subscriptionTerm` or `endDate` |
| `renewalTerm` | number | No | Renewal duration; must be > 0 |
| `priceTags` | array | No | Line-level price/discount tags |
| `addOns` | array | No | Optional bundle add-ons (recursive `ProductInput`) |
| `customPricingAttributes` | array | No | `[{name, value}]` for multi-attribute PBE resolution |
| `customFields` | object | No | Line-level custom fields written onto the created line item, keyed by Salesforce API name on `QuoteLineItem` / `OrderProduct` — e.g. `{"Ruby__CostCenter__c": "CC-1042"}`. Applies recursively through `addOns`. An unknown field name is rejected |
| `productOptionId` | string | No | Targets a specific bundle option slot (e.g. a dynamic option). When set, `productSku`/`productName` become optional |

---

## Core Behavior Rules

### Pricing Formula

```
Recurring:  ListPrice × Quantity × SubscriptionTerm = ListTotalPrice
OneTime:    ListPrice × Quantity = ListTotalPrice
```

### End Date Convention

> **IMPORTANT**: End dates are **inclusive** (start + term − 1 day).
> `start=2026-01-01`, `term=12 months` → `end=2026-12-31` (NOT `2027-01-01`).
> Setting `subscriptionEndDate` to `2027-01-01` creates a 12-month-and-1-day term, which may cause a 13-month charge.

### PriceBook Defaulting

If `priceBookId` is omitted, the API queries `Pricebook2 WHERE IsStandard = TRUE AND IsActive = TRUE`. If exactly one active standard pricebook exists, it is auto-assigned. Otherwise an error is returned.

### Discount Rules

1. **Header discount %** propagates to all lines without their own explicit discount
2. **Header discount amount** distributes across eligible lines proportionally
3. **Bundle discount** propagates to children without explicit discounts
4. **`discount: 0`** = "not discountable" — blocks inheritance. Different from omitting the field
5. **Percentage takes priority over amount** if both are set

### Bundle Expansion

- Bundled/required children are auto-expanded — do NOT list them in `addOns`
- Only **optional** items go in `addOns`
- Response nests children under `childrenLineItems` (quotes) or `childrenOrderProducts` (orders)

### Order Status

Orders are created in **Draft** status. Activation is a separate operation.

---

## Response Schema — Create Quote

```json
{
  "status": "SUCCEED",
  "quote": {
    "id": "0Q0...",
    "name": "...",
    "subscriptionStartDate": "2026-01-01",
    "subscriptionEndDate": "2026-12-31",
    "subscriptionTerm": 12,
    "listTotal": 1188,
    "subtotal": 1188,
    "totalPrice": 1188,
    "totalAmount": 1188
  },
  "quoteLineItems": [
    {
      "product": { "id": "...", "name": "...", "sku": "NUE_PLATFORM", "priceModel": "Recurring" },
      "uom": { "name": "User/Month", "quantityDimension": "User", "termDimension": "Month" },
      "quantity": 10,
      "actualQuantity": 10,
      "listPrice": 9.90,
      "totalPrice": 1188,
      "totalAmount": 1188,
      "childrenLineItems": []
    }
  ],
  "warnings": [],
  "errors": []
}
```

## Response Schema — Create Order

```json
{
  "order": {
    "id": "801...",
    "name": "...",
    "status": "Draft",
    "subscriptionStartDate": "2026-01-01",
    "subscriptionEndDate": "2026-12-31",
    "listTotal": 1188,
    "subtotal": 1188,
    "totalPrice": 1188,
    "totalAmount": 1188
  },
  "orderProducts": [
    {
      "product": { "id": "...", "name": "...", "sku": "NUE_PLATFORM", "priceModel": "Recurring" },
      "uom": { "name": "User/Month" },
      "quantity": 10,
      "actualQuantity": 10,
      "listPrice": 9.90,
      "totalPrice": 1188,
      "parentId": null,
      "childrenOrderProducts": []
    }
  ]
}
```

---

## Examples

### Example 1: Basic Order — Single Product

```bash
curl -X POST "https://api.nue.io/cpq/orders" \
  -H "nue-api-key: ${NUE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "001xx000003abc123",
    "subscriptionStartDate": "2026-01-01",
    "subscriptionEndDate": "2026-12-31",
    "subscriptionTerm": 12,
    "subscriptionTermDimension": "Month",
    "products": [
      { "productSku": "NUE_PLATFORM", "uom": "User/Month", "quantity": 10 }
    ]
  }'
```

### Example 2: Multiple Products (Recurring + OneTime)

```bash
curl -X POST "https://api.nue.io/cpq/orders" \
  -H "nue-api-key: ${NUE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "001xx000003abc123",
    "subscriptionStartDate": "2026-01-01",
    "subscriptionEndDate": "2026-12-31",
    "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 }
    ]
  }'
```

### Example 3: Bundle with Optional Add-On

```bash
curl -X POST "https://api.nue.io/cpq/orders" \
  -H "nue-api-key: ${NUE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "001xx000003abc123",
    "subscriptionStartDate": "2026-01-01",
    "subscriptionEndDate": "2026-12-31",
    "subscriptionTerm": 12,
    "subscriptionTermDimension": "Month",
    "products": [
      {
        "productSku": "NUE_GEM_EDITION",
        "uom": "User/Month",
        "quantity": 10,
        "addOns": [
          { "productSku": "IMPLEMENTATION_SERVICE", "uom": "Hour", "quantity": 20 }
        ]
      }
    ]
  }'
```

### Example 4: Billing Options

```bash
curl -X POST "https://api.nue.io/cpq/orders" \
  -H "nue-api-key: ${NUE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "001xx000003abc123",
    "subscriptionStartDate": "2026-01-01",
    "subscriptionEndDate": "2026-12-31",
    "subscriptionTerm": 12,
    "subscriptionTermDimension": "Month",
    "billingPeriod": "Month",
    "products": [
      {
        "productSku": "NUE_PLATFORM",
        "uom": "User/Month",
        "quantity": 25,
        "billingPeriod": "Month",
        "billingTiming": "In Advance"
      }
    ]
  }'
```

### Example 5: Preview Order (Dry Run)

```bash
curl -X POST "https://api.nue.io/cpq/orders:preview" \
  -H "nue-api-key: ${NUE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "001xx000003abc123",
    "subscriptionTerm": 12,
    "subscriptionTermDimension": "Month",
    "products": [
      { "productSku": "NUE_PLATFORM", "uom": "User/Month", "quantity": 10 }
    ]
  }'
```

### Example 6: Create Quote

```bash
curl -X POST "https://api.nue.io/cpq/quotes" \
  -H "nue-api-key: ${NUE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Enterprise Deal Q1",
    "opportunityId": "006xx000003abc123",
    "subscriptionStartDate": "2026-01-01",
    "subscriptionEndDate": "2026-12-31",
    "subscriptionTerm": 12,
    "subscriptionTermDimension": "Month",
    "products": [
      { "productSku": "NUE_PLATFORM", "uom": "User/Month", "quantity": 10 }
    ]
  }'
```

### Example 7: Quote with Bundle Discount + Protected Add-On

```bash
curl -X POST "https://api.nue.io/cpq/quotes:preview" \
  -H "nue-api-key: ${NUE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Gem Edition - 15% Bundle Discount",
    "opportunityId": "006xx000003abc123",
    "subscriptionTerm": 12,
    "subscriptionTermDimension": "Month",
    "products": [
      {
        "productSku": "NUE_GEM_EDITION",
        "uom": "User/Month",
        "quantity": 5,
        "discount": 15,
        "addOns": [
          { "productSku": "USB_SECURITY_KEY", "discount": 0 }
        ]
      }
    ]
  }'
```

### Example 8: Multi-Attribute Pricing

```bash
curl -X POST "https://api.nue.io/cpq/quotes:preview" \
  -H "nue-api-key: ${NUE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Tech Partner Quote",
    "opportunityId": "006xx000003abc123",
    "subscriptionTerm": 12,
    "products": [
      {
        "productSku": "NUE_PLATFORM",
        "uom": "User/Month",
        "quantity": 10,
        "customPricingAttributes": [
          { "name": "Ruby__PricingAttribute_1__c", "value": "Technology Partner" }
        ]
      }
    ]
  }'
```

---

## Env File Convention

Store API credentials in `.env.*` files at the repo root:

```bash
# .env.dev-qa3-ai
NUE_API_URL=https://api.qa3.nue.io
NUE_API_KEY=yGo1b6.07fe5ef1...
```

Load with: `source .env.dev-qa3-ai`

---

## Interaction Patterns

| User Says | API Construct |
|-----------|---------------|
| "create a quote" | `POST /cpq/quotes` with `name` + `opportunityId` |
| "create an order" | `POST /cpq/orders` with `customerId` |
| "preview / what-if / dry run" | Use `:preview` endpoint variant |
| "a bundle with add-ons" | `addOns` array on the bundle product |
| "10% off" | `discount: 10` on product or header |
| "full price on this item" | `discount: 0` on that product (blocks inheritance) |
| "monthly billing, pay in advance" | `billingPeriod: "Month"`, `billingTiming: "In Advance"` |

---

## Mistakes to Avoid

| Mistake | Why It Fails | Correct Approach |
|---------|-------------|-----------------|
| Using `effectiveDate` | Not a valid field | Use `subscriptionStartDate` + `subscriptionEndDate` |
| Using `billingPeriod: "Monthly"` | Invalid enum value | Use `"Month"`, `"Quarter"`, `"Semi-Annual"`, or `"Annual"` |
| Using `options: { activateOrder: false }` | `options` field doesn't exist on create | Orders default to Draft; activation is separate |
| Using `accountId` on create order | Invalid field name | Use `customerId` |
| Listing bundled/required items in `addOns` | They auto-expand; causes duplicates | Only list **optional** items in `addOns` |
| Omitting `uom` on a root product | Cannot resolve PricebookEntry | Always provide `uom` unless using `priceBookEntryId` |
| Using `opportunityId` as only identifier for orders | Orders require `customerId` | Always include `customerId` for orders |
| Setting `subscriptionEndDate` to start + term (e.g., `2027-01-01`) | End dates are **inclusive** — off-by-one creates extra month charge | Use start + term − 1 day (e.g., `2026-12-31` for 12 months from `2026-01-01`) |

---

## Reference Documentation

- [Create Quote Overview](https://api-docs.nue.io/create-quote-overview)
- [Create Order](https://api-docs.nue.io/create-order)
- [Preview vs Commit](https://api-docs.nue.io/preview-vs-commit)
- [Standalone Products](https://api-docs.nue.io/standalone-products)
- [Bundles](https://api-docs.nue.io/bundles)
- [Discounts](https://api-docs.nue.io/discounts)
- [Subscription Terms](https://api-docs.nue.io/subscription-terms)
- [Multi-Attribute Pricing](https://api-docs.nue.io/multi-attribute-pricing)
- [Multi-Currency](https://api-docs.nue.io/multi-currency)
- [Validation Errors](https://api-docs.nue.io/validation-errors)
- [Quote Data Reference](https://api-docs.nue.io/quote-data-reference)
- [Order Data Reference](https://api-docs.nue.io/order-data-reference)