Order Data Reference

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 docid\ sxbgdc7ri3nx45oyj 1dq 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