Subscription Data Reference

this comprehensive reference covers all subscription related data structures, field definitions, query parameters, and api capabilities in the nue self service api core subscription object the subscription object represents an ongoing contractual relationship between a customer and your business, created from activated orders and managed throughout the entire service lifecycle subscription fields reference identification fields field type description example id string unique subscription identifier "f594fd3a 3659 4039 ae5c b2c6863d98a5" name string subscription name "sub 00000309" subscriptioncompositeid string composite identifier with version "sub 00000309 1" subscriptionversion number version number for subscription changes 1 subscriptionlevel number level in subscription hierarchy 2 customer and product relationships field type description example customerid string associated customer identifier "81dd1eb9 7a2c 4486 be76 b1ac2f88bbb1" billingaccountid string billing account identifier "81dd1eb9 7a2c 4486 be76 b1ac2f88bbb1" productid string product identifier "01t7z00000dxt09aad" pricebookentryid string price book entry identifier "01u7z000005ynbaaa4" pricebookid string price book identifier "01s7z000006dt4raac" orderproductid string order product that created this subscription "03139976 1cc2 4430 8f61 996e641c8745" uomid string unit of measure identifier "a0s7z00000hyfptaa5" subscription terms and dates field type description example subscriptionstartdate string (date) when subscription service begins "2025 07 01" subscriptionenddate string (date) when subscription service ends "2026 06 30" subscriptionterm number subscription term in months 12 actualsubscriptionterm number actual term length including modifications 12 renewalterm number default renewal term in months 12 orderondate string (date) date order was placed "2025 07 02" nextbillingdate string (date) next billing date "2025 07 01" quantity and pricing field type description example quantity number number of units/seats/licenses 2 listprice number list price per unit 19 9 salesprice number actual sales price per unit 19 9 totalprice number total subscription price 0 totalamount number total amount including adjustments 0 taxamount number tax amount for subscription 0 financial metrics field type description example tcv number total contract value 0 totaltcv number total tcv including modifications 0 totalacv number total annual contract value 0 status and configuration field type description example status string subscription status "active" , "expired" , "canceled" autorenew boolean automatic renewal setting true evergreen boolean evergreen subscription flag false bundled boolean part of a bundle true hierarchy and structure field type description example subscriptionlevel number level in subscription hierarchy 2 subscriptionversion number version number for changes 1 parentid string parent subscription (for bundles) "3b573778 89c0 491d a972 bd3073d9add4" parentobjecttype string type of parent object "subscription" rootid string root subscription identifier "3b573778 89c0 491d a972 bd3073d9add4" system fields field type description example createddate string (iso 8601) when subscription was created "2025 07 02t23 12 30 582z" lastmodifieddate string (iso 8601) last modification timestamp "2025 07 02t23 12 30 621z" createdbyid string user who created subscription "74ef82c9 a9d7 4262 8331 ba7ac33d1f76" lastmodifiedbyid string user who last modified "74ef82c9 a9d7 4262 8331 ba7ac33d1f76" billing configuration field type description example billingperiod string billing frequency "annual" billingtiming string when billing occurs "in advance" , "in arrears" billcycleday string day of month for billing "7th of month" billcyclestartmonth string starting month for billing cycle "03" custom fields your organization may have custom fields that appear in subscription responses these fields follow the pattern customfieldname c and can be various data types depending on your configuration snapshot subscription object when using the snapshotdate parameter, subscriptions return a specialized format optimized for point in time analysis snapshot specific fields field type description example snapshotdate string (date) date of the snapshot "2025 01 15" parentid string parent subscription id "parent sub id" uom object unit of measure details see uom section below unit of measure (uom) object field type description example termdimension string time dimension for terms "month" quantitydimension string quantity dimension "user" name string uom display name "user/month" roundingmode string how to round calculations "half up" decimalscale number decimal places for calculations 2 upcoming changes array when includes=upcomingchanges is used with snapshots field type description example changetype string type of upcoming change "updatequantity" , "renew" , "cancel" startdate string (date) when change takes effect "2025 02 01" changeinquantity number quantity change amount 5 updatedterm number new subscription term 24 updatedenddate string (date) new end date "2027 01 31" changeinproduct string product change details "upgrade to premium" pricing engine input object the pricing engine endpoint returns specialized data for client side pricing calculations pricing engine response structure { "status" "success", "data" { "\[customerid]" { "changes" \[/ change objects /], "orderproduct" {/ order product data /} } }, "warnings" \[] } change objects array field type description example totalprice number total price for change 495 00 totalamount number total amount including adjustments 495 00 term number term length for change 12 subtotal number subtotal before tax 495 00 startdate string when change starts "2025 02 01" quantity number quantity for change 5 netsalesprice number net price after discounts 99 00 listtotal number list total before discounts 550 00 linetype string type of pricing line "product" , "discount" enddate string when change ends "2026 01 31" changetype string type of change "updatequantity" order product object field type description example id string order product identifier "op 12345" subscriptionterm number current subscription term 12 subscriptionstartdate string current start date "2025 01 01" subscriptionenddate string current end date "2025 12 31" quantity number current quantity 5 listprice number current list price 99 00 product object product details see product section uom object unit of measure see uom section api endpoints reference subscription retrieval endpoint method purpose /subscriptions get fetch customer subscriptions /subscriptions/pricing engine input get get pricing data for client side calculations subscription management endpoint method purpose /subscriptions/{subscriptionid} patch update subscription settings query parameters get /subscriptions parameter type required description constraints customerids array no json encoded array of customer ids cannot use with name name string no specific subscription name cannot use with customerids snapshotdate string no point in time snapshot (yyyy mm dd) cannot use with history , status , version history boolean no include subscription change history only with name parameter includes string no related data to include product , pricetags , upcomingchanges status string no filter by subscription status active , expired , canceled version string no version filter latest , snapshot get /subscriptions/pricing engine input parameter type required description customerids array yes json encoded array of customer ids update operations patch /subscriptions/ { subscriptionid } updatable fields field type description example autorenew boolean automatic renewal setting true ruby custom field c string custom field values "premium support" request example { "autorenew" true, "ruby custom field c" "updated value", "servicetier c" "premium" } subscription status values standard status values status description billing active can modify active subscription is currently providing service ✅ ✅ expired subscription has reached its end date ❌ limited canceled subscription was terminated early ❌ ❌ data view types current contract view (default) characteristics shows complete subscription timeline includes all historical and future changes displays current active configuration used for ongoing subscription management best for customer service dashboards subscription modification planning complete contract analysis renewal management snapshot view (with snapshotdate) characteristics shows subscription state at specific date includes upcoming changes from that date optimized for historical analysis different response schema best for historical reporting audit and compliance change impact analysis point in time billing analysis validation rules query parameter validation customerids and name are mutually exclusive snapshotdate cannot be used with history , status , or version history requires the name parameter upcomingchanges include only works with snapshotdate data format requirements snapshotdate must be yyyy mm dd format customerids must be valid json array of strings date fields iso 8601 format for regular responses, date format for snapshots update constraints only specific fields can be updated via patch subscriptionid must be valid and accessible custom field names must follow salesforce conventions error handling common error scenarios error type description resolution subscription not found subscription id not found verify subscription exists invalid customer id customer id not valid check customer id format invalid date format date format incorrect use yyyy mm dd format parameter conflict conflicting query parameters review parameter constraints unauthorized access no access to subscription check api key permissions error response format { "status" "failure", "errortype" "validation error", "errorcode" "subscription not found", "message" "subscription with id 'invalid id' not found", "details" { "field" "subscriptionid", "value" "invalid id" } } best practices data retrieval use appropriate view types current contract for management, snapshots for analysis include related data efficiently use includes parameter to reduce api calls filter by status reduce payload size by filtering to relevant subscriptions cache appropriately subscription data changes infrequently update operations validate before updating check subscription status and permissions use minimal payloads only include fields being changed handle errors gracefully implement retry logic for temporary failures audit changes log all subscription modifications for compliance performance optimization batch customer queries request multiple customers in single call use pagination for customers with many subscriptions implement caching cache frequently accessed subscription data monitor api limits respect rate limiting guidelines this comprehensive reference provides the foundation for implementing robust subscription management with the nue self service api for implementation examples, see the getting started guide and advanced workflows documentation