---
title: Orders Overview
slug: orders-overview
createdAt: 2026-02-13T04:24:47.814Z
---

In the Nue Self-Service API, **Orders** represent purchase transactions between customers and your business. Orders are the foundation for creating subscriptions, managing product deliveries, and generating invoices throughout the customer lifecycle.

## Core Order Concepts

Orders in Nue handle the complete purchase process, from initial quoting through fulfillment and billing:

- **Draft Orders**: Preview orders that show pricing and details without financial impact
- **Activated Orders**: Finalized orders that create subscriptions, assets, and invoices
- **Change Orders**: Modifications to existing subscriptions (quantity changes, upgrades, renewals)
- **Order Products**: Individual line items within an order representing specific products and quantities

## Order Lifecycle Stages

Understanding the order lifecycle helps you implement the right workflows for your customers:

### 1. Order Creation and Preview

- Create draft orders to show customers pricing and configuration
- Include preview invoices to display future billing details
- Support complex product bundles with configurable add-ons
- Generate PDF quotes for sharing and approval workflows

### 2. Order Activation

- Transform draft orders into active transactions
- Create subscriptions, entitlements, and assets automatically
- Generate and optionally activate invoices
- Integrate with external payment system (Stripe)

### 3. Order Management

- Retrieve order history for customers
- Track order status and details
- Access related subscriptions, assets, entitlements, and invoices
- Generate change orders for modifications

## Order Types and Use Cases

### New Orders

New orders create fresh customer relationships and subscriptions:

- **Initial Purchases**: First-time customer orders
- **Expansion Orders**: Additional products for existing customers

### Change Orders

Change orders modify existing subscriptions without creating new ones:

- **Quantity Updates**: Increase or decrease user counts
- **Product Upgrades/Downgrades**: Move between service tiers
- **Term Changes**: Modify subscription length
- **Renewals**: Extend subscription terms
- **Cancellations**: End subscriptions on specific dates

## Key Order Components

### Order Products and Bundles

- **Simple Products**: Individual items with straightforward pricing
- **Bundle Products**: Parent products with configurable add-ons
- **Product Options**: Components within bundles (required, optional, recommended)
- **Nested Bundles**: Up to 3 levels of bundle hierarchy for complex offerings

### Pricing and Discounts

- **Price Book Entries**: Define product pricing and billing terms
- **Volume Discounts**: Automatic pricing tiers based on quantity
- **Price Tags**: Manual discount codes and promotional pricing
- **Tax Calculation**: Support for location-based tax rates based on the shipping address

### Billing Integration

- **Preview Invoices**: Show customers future billing before activation
- **Invoice Generation**: Create billing documents upon order activation
- **Payment Processing**: Integrate with Stripe and other payment systems
- **Billing Periods**: Support monthly, quarterly, annual, and custom billing cycles

## Order Data Architecture

### Core Relationships

Orders connect to several key objects in the Nue platform:

- **Customers**: Who is making the purchase
- **Products**: What is being purchased
- **Subscriptions**: Ongoing service agreements created from orders
- **Assets**: Physical or virtual items delivered
- **Invoices**: Billing documents for payment collection

### External System Integration

Orders can synchronize with external platforms:

- **CRM Systems**: Salesforce account integration
- **Payment Processors**: Stripe customer and payment method linking

## Order Status Management

Orders progress through several status states:

- **Draft**: Preview mode, no financial impact
- **Activated**: Finalized and creating downstream objects
- **Canceled**: Terminated before activation

Change orders follow a similar pattern but modify existing subscriptions rather than creating new ones.

## Example Order Management Workflow

Here's one common order lifecycle pattern:

1. **Create Draft Order** → 2. **Activate Order** → 3. **Retrieve Orders** → 4. **Create Change Order** → 5. **Generate Quote Link** → 6. **Activate Changes** → 7. **Sync to Salesforce**

### Flexible Workflow Options

You can use any combination of these capabilities based on your business needs:

- **Simple Purchase Flow**: Create Draft → Activate → Done
- **Approval-Based Flow**: Create Draft → Generate Quote Link → Review → Activate
- **Self-Service Changes**: Retrieve Orders → Create Change Order → Activate Changes
- **Quote-Heavy Process**: Create Draft → Generate Quote Link → Modify → Generate New Quote → Activate

### Key Requirements

- **Draft First**: All orders must start as drafts for preview and validation
- **Changes After Activation**: Only activated orders can be modified with change orders
- **Salesforce Sync**: Happens automatically throughout the process
- **Create Draft Order**: Preview pricing and configuration without financial impact
- **Activate Order**: Finalize the purchase and create subscriptions
- **Retrieve Orders**: View order history and current subscriptions
- **Create Change Order**: Modify existing subscriptions (quantity, upgrades, renewals)
- **Generate Quote Link**: Create shareable magic links that allow customers to view and download order quotes via secure URLs (no authentication required)
- **Activate Changes**: Implement subscription modifications
- **Sync to Salesforce**: Automatic synchronization of all order data to Salesforce throughout the process

Note: The "quote link" generates a magic link (secure URL) that customers can use to view their draft order details and download formatted quotes - this isn't a direct PDF file but rather a link to a web page that can display or generate PDFs.

## Getting Started with Orders

To begin working with orders in the Nue Self-Service API:

1. **Create Customers**: Establish customer records before creating orders
2. **Understand Products**: Familiarize yourself with your product catalog and pricing
3. **Follow the Complete Workflow**: Start with the Getting Started guide for the end-to-end process
4. **Test in Sandbox**: Practice the full lifecycle in a test environment
5. **Implement Advanced Scenarios**: Add complex bundles and approval workflows

## Next Steps

Explore the order management guides in sequence:

- **Getting Started with Order Management** - Learn the complete order lifecycle with practical examples
- **Advanced Order Workflows** - Implement complex scenarios like enterprise bundles and approval workflows
- **Order Data Reference** - Complete field documentation and validation rules

Each guide builds upon the previous one, providing a comprehensive foundation for implementing orders in your application.
