Order Data Reference

47 min

This comprehensive reference covers all order-related data structures, field definitions, validation rules, and relationships in the Nue Self-Service API.

Core Order Object

The Order object represents a purchase transaction and contains comprehensive information about customer purchases, pricing, billing, and subscription details.

Order Fields Reference

Required Fields

Field	Type	Description	Example
customer.id	String	Unique identifier for the customer	"d2e04653-ae90-49df-a986-134cf64f6d03"
effectiveDate	String (ISO 8601)	Date when the order becomes valid	"2025-01-01"
orderProducts	Array	List of products being ordered	See Order Products section

Core Order Fields

Field	Type	Description	Example
id	String (UUID)	Unique order identifier	"b636440c-b3dd-4a92-9187-199f110d5b24"
orderNumber	String	Human-readable order number	"O-00000300"
name	String	Order name/title	"Annual Platform License"
description	String	Order description	"Customer's annual subscription"
status	String	Order status	"Draft", "Activated", "Canceled"
customerId	String	Associated customer ID	"d2e04653-ae90-49df-a986-134cf64f6d03"

Financial Fields

Field	Type	Description	Example
totalAmount	Number	Total order value	5940.00
listTotal	Number	List price total before discounts	5940.00
orderACV	Number	Annual Contract Value	495.00
orderTCV	Number	Total Contract Value	5940.00
discount	Number	Discount percentage	10.0
discountAmount	Number	Absolute discount amount	594.00
systemDiscount	Number	System-applied discount percentage	5.0
systemDiscountAmount	Number	System discount amount	297.00
subtotal	Number	Subtotal before tax	5940.00
taxAmount	Number	Total tax amount	475.20

Date and Timing Fields

Field	Type	Description	Example
orderStartDate	String (ISO 8601)	Order effective start date	"2024-12-24"
orderPlacedDate	String (ISO 8601)	Date order was placed/activated	"2025-06-24"
subscriptionStartDate	String (ISO 8601)	When subscriptions begin	"2025-01-01"
subscriptionEndDate	String (ISO 8601)	When subscriptions end	"2036-12-31"
subscriptionTerm	Number	Subscription term in months	12.0
createdDate	String (ISO 8601)	Order creation timestamp	"2025-06-24T23:35:27.477Z"
lastModifiedDate	String (ISO 8601)	Last modification timestamp	"2025-06-24T23:36:13.665Z"

Billing and Payment Fields

Field	Type	Description	Example
billingPeriod	String	Billing frequency	"Annual", "Monthly", "Quarterly"
billCycleDay	String	Day of month for billing	"1st of Month"
billingAccountId	String	Billing account identifier	"ba-12345"
billToContactId	String	Contact for billing	"0Q0Oz000001ydCPKAY"
billingAddress	String (JSON)	Billing address object	"{\"country\":\"United States\",\"state\":\"CA\"}"
shippingAddress	String	Shipping address	"123 Main St, City, State 12345"
isShippingAddressSameAsBilling	Boolean	Address matching flag	false

Purchase Order Fields

Field	Type	Description	Example
poNumber	String	Purchase order number	"PO-2025-001"
poDate	String (ISO 8601)	Purchase order date	"2025-01-01"

Integration Fields

Field	Type	Description	Example
externalId	String	External system ID (Salesforce)	"801Ea0000118nqWIAQ"
transactionHub	Object	External system integration	See Transaction Hub section
orderPdf	String (URL)	Magic link to order PDF	"https://app.nue.io/view-order/[token]"

System Fields

Field	Type	Description	Example
activatedById	String	User who activated order	"74ef82c9-a9d7-4262-8331-ba7ac33d1f76"
activatedDate	String (ISO 8601)	Activation timestamp	"2025-06-24T23:36:13.665Z"
createdById	String	User who created order	"74ef82c9-a9d7-4262-8331-ba7ac33d1f76"
lastModifiedById	String	User who last modified	"74ef82c9-a9d7-4262-8331-ba7ac33d1f76"
ownerId	String	Order owner	"74ef82c9-a9d7-4262-8331-ba7ac33d1f76"
platformOrigin	String	System origin	"Ruby"
priceBookId	String	Associated price book	"01sEa000003IsppIAC"

Order Products Object

Order Products represent individual line items within an order, including product details, pricing, and subscription information.

Order Product Fields Reference

Core Product Fields

Field	Type	Description	Example
id	String (UUID)	Unique order product identifier	"d8291ee3-c39c-4165-851d-fa880584b6aa"
name	String	Order product name	"OP-0000000965"
productId	String	Product identifier	"01tEa00000E8IpUIAV"
productName	String	Product display name	"Nue Platform"
sku	String	Product SKU	"NUE_PLATFORM"
priceBookEntryId	String	Salesforce Price Book Entry ID	"01uEa000008IcdeIAC"

Quantity and Pricing

Field	Type	Description	Example
quantity	Number	Ordered quantity	5.0
actualQuantity	Number	Actual provisioned quantity	5.0
listPrice	Number	List price per unit	99.00
salesPrice	Number	Actual sales price per unit	99.00
netSalesPrice	Number	Net price after discounts	99.00
listTotalPrice	Number	Total list price	5940.00
totalPrice	Number	Total actual price	5940.00
totalAmount	Number	Final amount including tax	5940.00

Subscription Details

Field	Type	Description	Example
subscriptionStartDate	String (ISO 8601)	Subscription start	"2025-01-01"
subscriptionEndDate	String (ISO 8601)	Subscription end	"2036-12-31"
subscriptionTerm	Number	Term in months	12.0
actualSubscriptionTerm	Number	Actual term length	144.0
autoRenew	Boolean	Auto-renewal flag	true
evergreen	Boolean	Evergreen subscription flag	false

Financial Metrics

Field	Type	Description	Example
deltaACV	Number	ACV change from this product	495.00
deltaARR	Number	ARR change	495.00
deltaCMRR	Number	CMRR change	41.25
deltaTCV	Number	TCV change	5940.00

Integration and Custom Fields

Field	Type	Description	Example
revenueContractId	String	Revenue contract identifier for grouping in RightRev. Can be set during order activation via the orderProducts array.	"ORD-001234"
customFields	String (JSON) / Object	Salesforce custom fields on the order product. Set inline as properties during order creation, or via the orderProducts array during activation.	{"Custom_Field__c": "Value1"}

Billing Configuration

Field	Type	Description	Example
billingPeriod	String	Billing frequency	"Annual"
billingTiming	String	When billing occurs	"In Advance"
billCycleDay	String	Day of month for billing	"1st of Month"
billCycleStartMonth	String	Starting month	"01"

Tax and Compliance

Field	Type	Description	Example
taxAmount	Number	Tax amount for this product	0.00
taxCode	String	Tax classification code	"txcd_30070021"
taxMode	String	Tax calculation mode	"TaxExclusive"

Unit of Measure

Field	Type	Description	Example
uomId	String	Unit of measure identifier	"a0sEa000006DD2UIAW"
uom	String	Unit description	"User/Year"

Bundle and Add-on Configuration

Product Options (Add-ons)

When configuring bundles, add-ons are specified within the addOns array of order products.

Add-on Fields

Field	Type	Required	Description	Example
productOptionId	String	Yes	Salesforce Product Option ID	"01tXX0000004C1h"
productOptionQuantity	Number	No	Add-on quantity	5
subscriptionStartDate	String	No	Independent start date	"2025-02-01"
subscriptionTerm	Number	No	Independent term	6
priceTagCodes	Array	No	Discount codes	["VOLUME_DISCOUNT"]
addOns	Array	No	Nested add-ons (up to 3 levels)	See nested structure

Bundle Hierarchy Example

{
  "orderProducts": [
    {
      "priceBookEntryId": "01uQL000009Tsn4YAC",
      "quantity": 1,
      "addOns": [
        {
          "productOptionId": "po-analytics-module",
          "productOptionQuantity": 1,
          "addOns": [
            {
              "productOptionId": "po-advanced-reporting",
              "addOns": [
                {
                  "productOptionId": "po-custom-dashboards",
                  "productOptionQuantity": 5
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Change Orders

Change orders allow you to modify existing subscriptions (quantity changes, upgrades, renewals, cancellations, etc.) without creating new orders. They support various modification types with specific behaviors and requirements.

For comprehensive information about change orders, including all change types, field definitions, validation rules, and implementation examples, see the Change Order Data ReferenceChange Order Data Reference.

Common Change Order Types

UpdateQuantity: Add or subtract users/licenses (delta behavior)

Upgrade/Downgrade: Move between product tiers

Renew: Extend subscription terms

Cancel: End subscriptions on specific dates

CoTerm: Align subscription end dates

Quick Reference

{
  "assetChanges": [
    {
      "changeType": "UpdateQuantity",
      "assetNumber": "SUB-00000279",
      "quantity": 3,  // Delta: adds 3 to current
      "startDate": "2025-02-01"
    }
  ]
}

Note: All change orders start as draft previews before activation, allowing you to see pricing impact before committing changes.

Transaction Hub Integration

The Transaction Hub enables integration with external systems like Stripe and Salesforce.

Transaction Hub Fields

Field	Type	Description	Example
externalSystem	String	External system name	"Stripe", "Salesforce"
externalId	String	ID in external system	"cus_RsS1MZKCy2PmJ7"
transactionType	String	Type of transaction	"Customer", "PaymentMethod"

Example Transaction Hub Configuration

{
  "transactionHub": {
    "externalSystem": "Stripe",
    "externalId": "cus_customer123",
    "transactionType": "Customer"
  }
}

Order Options

Order options control preview generation, tax calculation, and invoice handling.

Options Fields

Field	Type	Default	Description
previewInvoice	Boolean	false	Generate invoice preview
calculateTax	Boolean	false	Calculate tax amounts
generateInvoice	Boolean	true	Generate invoice on activation
activateInvoice	Boolean	false	Activate invoice immediately

Example Options Configuration

{
  "options": {
    "previewInvoice": true,
    "calculateTax": true
  }
}

For activation:

{
  "options": {
    "generateInvoice": true,
    "activateInvoice": false
  }
}

Custom Fields

Both orders and order products support custom fields for business-specific data.

Order Custom Fields Example

{
  "customFields": "Department__c=Engineering;ProjectCode__c=PROJ-2025-001;BudgetCenter__c=R&D;ContractType__c=Enterprise"
}

Order Product Custom Fields Example

Custom fields on order products are added directly as properties in the order product object:

{
  "orderProducts": [
    {
      "priceBookEntryId": "01uEa000008IcdeIAC",
      "quantity": 5,
      "subscriptionStartDate": "2025-06-23",
      "subscriptionTerm": 12,
      "ContractValue__c": "High",
      "ServiceLevel__c": "Premium",
      "DataCenter__c": "US-West"
    }
  ]
}

Custom Fields Format:

Order-level custom fields: Passed as a semicolon-separated string in the format "FieldName__c=Value;AnotherField__c=AnotherValue"

Order Product-level custom fields: Added directly as properties in the order product object

Custom Field Inheritance

Custom fields on Order Products automatically transfer to created Subscriptions if:

The same custom field exists on the Subscription object

Field API names match exactly

Data types are compatible

Field security settings allow the transfer

Validation Rules

Order Validation

Required Field Validation

customer.id must be a valid customer UUID

effectiveDate must be a valid ISO 8601 date

orderProducts array must contain at least one item

Each order product must have a valid priceBookEntryId (Salesforce Price Book Entry ID)

Date Validation

effectiveDate cannot be more than 2 years in the past

subscriptionStartDate must be >= effectiveDate

subscriptionEndDate is calculated automatically based on term

Change order dates must be logical (e.g., cancellation date > start date)

Financial Validation

Quantities must be positive numbers

Prices cannot be negative

Discount percentages must be between 0 and 100

Tax calculations require valid shipping addresses

Bundle Validation

Add-on Hierarchy

Maximum 3 levels of nesting allowed

Each productOptionId must be a valid Salesforce Product Option ID for the parent product

Required add-ons are automatically included if not specified

Optional add-ons must be explicitly configured

Subscription Term Validation

Terms must be positive integers (months)

Add-on terms cannot exceed parent product terms unless explicitly allowed

Co-termination dates must align with business rules

Error Handling

Common Error Codes

Error Code	Description	Resolution
INVALID_CUSTOMER_ID	Customer not found	Verify customer exists
INVALID_PRICE_BOOK_ENTRY	Product not available	Check product catalog
INVALID_DATE_FORMAT	Date format incorrect	Use ISO 8601 format
BUNDLE_CONFIGURATION_ERROR	Add-on configuration invalid	Review bundle structure
INSUFFICIENT_PERMISSIONS	Access denied	Check API key permissions
RATE_LIMIT_EXCEEDED	Too many requests	Implement rate limiting
INVALID_ORDER_PRODUCT_ID	Order product ID in activation orderProducts array not found on this order	Verify IDs from the draft order
INVALID_ORDER_PRODUCT_FIELD	Field in activation orderProducts array is read-only or billing-managed	Use billing APIs for quantity/price fields

Error Response Format

{
  "status": "FAILURE",
  "errorType": "VALIDATION_ERROR",
  "errorCode": "INVALID_CUSTOMER_ID",
  "message": "Customer with ID 'invalid-id' not found",
  "details": {
    "field": "customer.id",
    "value": "invalid-id",
    "allowedValues": null
  }
}

Status Transitions

Order Status Flow

Draft → Activated → [Complete]
  ↓
Canceled

Valid Status Values

Draft: Order in preview mode, no financial impact

Activated: Order finalized, subscriptions created

Canceled: Order terminated before activation

Change Order Status Flow

Change orders follow the same status pattern but modify existing subscriptions rather than creating new ones.

API Endpoints Summary

Order Management Endpoints

Endpoint	Method	Purpose
/orders	POST	Create draft order
/orders	GET	Retrieve customer orders
/orders/{orderId}	POST	Activate draft order
/change-orders	POST	Create change order preview
/orders/magiclink/order/{orderId}	GET	Generate PDF link
/orders/magiclink/order/{orderId}/template/{templateId}	GET	Generate PDF with template

Query Parameters

GET /orders

Parameter	Type	Required	Description
customerIds	Array (JSON)	Yes	Customer IDs to fetch
includes	String	No	Related data: orderProducts, assets, invoices
status	String	No	Filter by status: activated, draft, canceled

Best Practices

Data Modeling

Use appropriate data types - Ensure numbers are numeric, dates are ISO 8601

Include custom fields - Capture business context for reporting

Validate bundles carefully - Test complex configurations in sandbox

Plan for scale - Consider pagination for large order histories

Performance Optimization

Use includes parameter - Fetch related data in single call

Implement caching - Cache frequently accessed order data

Batch operations - Group multiple operations where possible

Monitor API limits - Respect rate limiting guidelines

Integration Patterns

Handle Salesforce sync - Monitor externalId field for sync status

Implement webhooks - Use real-time notifications for status changes

Error handling - Implement retry logic with exponential backoff

Audit trails - Log all order operations for compliance

This comprehensive reference provides the foundation for implementing robust order management with the Nue Self-Service API. For specific implementation examples, see the Getting Started and Advanced Workflows guides.