Self-Service Reference Guide

The Nue.io Self-Service API provides a comprehensive suite of tools designed to streamline your revenue lifecycle processes and give you actionable insights into your financial data. With the Nue Self-Service API, you can:

• Manage accounts and contacts
• Retrieve product information and pricing details
• Create new orders
• Update existing asset data for subscriptions, physical assets, and entitlements
• Automatically sync all data bidirectionally with Salesforce — ensuring that any updates to accounts, contacts, orders, or subscriptions are automatically reflected in both Nue.io and Salesforce, enabling seamless collaboration across teams.

Built with RESTful principles, the API follows predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes and verbs.

In addition to the API, Nue.io also offers UI components that can be seamlessly integrated with these APIs to simplify your build process and accelerate development. These pre-built UI components allow you to quickly implement customer-facing interfaces, reducing the need for complex front-end development.

 

Getting Started

To get started with the Nue.io Self-Service API and UI components, refer to the following links:

• Postman Collection: A comprehensive collection that includes detailed documentation and examples for each API endpoint, allowing you to easily test and interact with the API.
• API Documentation (Swagger): Offers a complete schema and detailed response structures for each endpoint, including the required payloads, helping you integrate the API smoothly.
• UI Component Storybook: A visual reference for the available UI components, showcasing interactive examples and usage details for seamless integration into your self-service portal.

These resources will guide you through the process of integrating the APIs and UI components into your application.

To begin using the Nue Self-Service API's, follow these steps:

1. Obtain an API Key:
   You must use a valid API Key to send requests to the API endpoints. This can be acquired from your Nue.io account settings.

2. Understand Rate Limits:
   Be aware of the rate and usage limits associated with your API key to ensure smooth operation.

3. Use HTTPS:
   The API only responds to HTTPS-secured communications. Requests sent via HTTP will be redirected to their corresponding HTTPS resources.

4. Format of Responses:
   The API returns responses in JSON format. If an error occurs, it will be provided in the JSON response under an "error" key.

Important Notes on API Key Usage

• Authentication:
  The API key is required in the request header for authentication. It is strongly recommended to use these APIs server-side rather than client-side to prevent exposing your API key in frontend code, reducing the risk of unauthorized access and security vulnerabilities.

• Authentication Error Responses:
  If your API key is missing, malformed, or invalid, you will receive an HTTP 401 Unauthorized response code.

Publish Products and Pricing for Self-Service

With Nue, Nue eliminates the need for developers to duplicate products and price information exclusively for the consumption of self-service APIs. 

 

Rev Ops users use Nue's Price Builder easy-to-use UI to build products and pricing, which can be of any product types, including subscriptions, physical goods, and services, and any pricing models, including Recurring Services, One-time, Overage Usage, Pay As You Go and Credit Burndown.  These products and pricing will be available instantly for direct sales team to build quotes, orders, which are provisioned into subscriptions, assets, and service entitlements. 

 

Often times, the products and pricing available for self-service website of a company are only a subset of that available for direct sales.  Thereforce, Nue provides a convenient way for product managers of the self-service website to publish a subset of products and pricing just for self-service APIs to consume.  Once this subset is published, the products and corresponding prices are shapshotted and cached within the system, ensuring access with high performance. While ongoing updates by Rev Ops users may occur, these revisions do not impact the published version until they are explicitly republished for self-service access.

Enable a Price Book for Self-service Access

Please follow the steps below to enable a specific price book for self-service access. 

• Login to Nue App
• Navigate to Price Builder → Price Books 
• Select the price book to enable, and click 'Edit' icon
• Click 'Enable for Self Service' button.

Publish a Product for Self-service Access

Please follow the steps below to enable a specific price book for self-service access. 

• Login to Nue App
• Navigate to Price Builder → Product Catalog 
• Select the product to publish, and click 'Edit' icon
• Click 'Publish' to publish the product for self-service access.

Once a product is published for self-service access, the product and its price book entries in the price book enabled for self-service access will be accessible by the self-service APIs.

 

GraphQL for Additional Data

SELF-SERVICE SCENARIO   If the curated GET API's from the Postman Collection don't provide all relevant details, the Nue GraphQL model can be traversed for further information.

 

In Nue, you can use Nue GraphQL to query any business objects.  You can use Nue GraphQL to query the customer, contact, order, and invoice created.  

GraphQL Endpoint

https://api.nue.io/orders/async/graphql

Query Customers

The following is an example: 

query {
  Customer(where: {id: {_eq: "02e24cf3-40d6-43b2-a47b-53904ab3776c"}}) {
    createdById
    createdDate
    id
    lastModifiedById
    lastModifiedDate
    name
    phone
  }
}

Query Contacts

The following is an example: 

query {
  Contact {
    billingCity
    billingCountry
    billingState
    billingStreet
    billingZipCode
    birthday
    createdById
    createdDate
    customerId
    email
    firstName
    id
    lastModifiedById
    lastModifiedDate
    lastName
    middleName
    mobilePhone
    name
    shippingCity
    shippingCountry
    shippingState
    shippingStreet
    shippingZipCode
    suffix
  }
}

Query Order History

The following is an example to query all active orders sorted by order activation dates and total amounts: 

query {
  Order(
    where: {status: {_eq: "Activated"}}
    orderBy: {activatedDate: asc, totalAmount: asc}
  ) {
        customer {
            id
            name
            totalTCV
            todayARR
            todayCMRR
        }
    activatedById
    activatedDate
    billCycleDay
    billToContactId
    billingAccountId
    billingAddress
    billingPeriod
    companyAuthorizedById
    companyAuthorizedDate
    createdById
    createdDate
    customerAuthorizedById
    customerAuthorizedDate
    customerId
    description
    discount
    discountAmount
    endDate
    id
    lastModifiedById
    lastModifiedDate
    listTotal
    name
    nextInvoiceDate
    opportunityId
    orderACV
    orderNumber
    orderPlacedDate
    orderReferenceNumber
    orderStartDate
    orderTCV
    orderType
    originalOrderId
    ownerId
    poDate
    poNumber
    priceBookId
    shipToContactId
    shippingAddress
    shippingAndHandling
    status
    subscriptionStartDate
    subscriptionTerm
    subtotal
    systemDiscount
    systemDiscountAmount
    tax
    todayARR
    todayCMRR
    totalAmount
    totalPrice
  }
}

Query Subscriptions

The following is an example to query all active subscriptions sorted by products and subscription start dates: 

query {
  Subscription(
    where: {_and: [{status: {_eq: "Active"}}, {customer: {id: {_eq: "{{customerId}}"}}}]}
    orderBy: {productId: asc, subscriptionStartDate: asc}
  ) {
    actualSubscriptionTerm
    autoRenew
    billingPeriod
    billingTiming
    bundled
    cancellationDate
    createdById
    createdDate
    customerId
    id
    includedUnits
    lastModifiedById
    lastModifiedDate
    lastVersionedSubscriptionId
    latestVersionedSubscriptionId
    listPrice
    name
    orderOnDate
    orderProductId
    originalSubscriptionId
    priceBookEntryId
    priceBookId
    productId
    quantity
    reconfigureEffectiveDate
    renewalTerm
    rootId
    salesPrice
    status
    subscriptionEndDate
    subscriptionLevel
    subscriptionStartDate
    subscriptionTerm
    subscriptionVersion
    taxAmount
    tcv
    todayARR
    todayCMRR
    todaysQuantity
    totalACV
    totalAmount
    totalPrice
    totalTCV
    uomId
  }
}