Self-Service APIs

In this helpful guide, we'll walk you through the process of using our user-friendly Restful APIs to set up orders, subscriptions, assets, and entitlements. What's more, we're here to assist you in making any adjustments you'd like – whether it's adding or decreasing quantities, adjusting subscription terms, handling renewals, or managing cancellations. Let's get started!

 

Postman Collection

Users can access the API documentation and the Postman Collection here. By clicking 'Run in Postman,' you can import the entire collection, enabling you to quickly begin testing these APIs.

 

---

 

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.

 

Self-service Use Cases

Nue's Self-Service APIs are a set of Restful APIs that can be used to implement the following self-service scenarios for the web-based B2B commerce: 

 

ADD TO CART Add products - which can be bundles, subscriptions, physical goods, and services - into shopping cards, and preview invoices

 

PLACE ORDER Checkout products in a shopping cart into an order and pay the first invoice.  The products and services in the order will be created as subscriptions, physical assets and entitlement that the user 

 

MAKE CHANGES Add changes of existing subscriptions, physical goods, or services, e.g., updating quantities, renewals, cancellations, into a shopping cart

 

CHECKOUT CHANGES Checkout changes to existing subscirptions, physical goods, or services into an order and pay the invoice containing additional amounts

 

Add to Cart

SELF-SERVICE SCENARIO   While a self-service user browses the product catalog, she is interested in subscribing to a bundle product, or a simple product or service.  She then clicks on the Subscribe or Add to Cart button to add the product or service into the shopping cart.   In the shopping cart, the user can preview the first invoice.

 

In this case, when the user adds the subscription into the cart, you can call the following API to create a Draft Order. 

API Endpoint

The API docs reference can be found here. 

POST https://api.nue.io/orders

 

Example

The following is a payload example: 

curl --location 'https://api.nue.io/orders' \
--header 'apiAccessKey: {{apiAccessKey}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: {{bearer-token}}' \
--data-raw '{
	"options": {
		"activateOrder": false, 
                 "previewInvoice": true
	},
	"customer": {
		"name": "Unknown",
                 "email": "unknown@unknown.com"
	},
	"effectiveDate": "{{orderStartForSelfService}}",
	"priceBookId": "{{priceBookIdForSelfService}}",
	"billingCycle": "Month",
	"name": "Shopping Cart",
	"lines": [{
		"lineType": "LineItem",
		"productId": "{{productId}}",
		"quantity": 10,
		"subscriptionTerm": 12,
		"subscriptionStartDate": "{{today}}",
		"priceBookEntryId": "{{priceBookEntryId}}",
		"refId": {{refId}}
	}]
}'

 

Place New Order

SELF-SERVICE SCENARIO   When the self-service user is prepared to proceed with checking out the items or services in their cart and converting them into an order, they follow the sequential flow on the page. This involves entering their personal information, contact details, billing address, and shipping address. Subsequently, they input their payment details using the integrated hosted payment page provided by Stripe.     Once all the details are in order, they simply click on the 'Place Order' button to conclude the ordering process. Once the order has been successfully placed, a confirmation page will appear, displaying comprehensive information about the order. As per the specific product details outlined in the order, subscriptions, physical assets, or entitlements will be provisioned accordingly.

API Endpoint

The API docs reference can be found here. 

POST https://api.nue.io/orders

Example

The following is a payload example.  After this API is called, the following actions occur: 

• A new customer (company) is created, unless an existing company ID is supplied instead
• A new contact (the current user) is created, which is also associated to the customer.
• A new order containing order products is created, and activated.
• Upon activation, subscriptions, physical assets, and service entitlements are created and provisioned.
• The first invoice is created and activated.  
• If Stripe is integrated, the active invoice will be sent to Stripe for payments.  
• If the payment is successful, the entire transaction is committed.  Otherwise, the entire transaction will be canceled.  Optionally, you can ask the transaction not to be canceled, so that a sales rep can follow up with the customer for payments offline.  

curl --location 'https://api.nue.io/orders' \
--header 'apiAccessKey: {{apiAccessKey}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: {{token}}' \
--data-raw '{
	"options": {
		"activateInvoice": true,
		"cancelOnPaymentFail": true
	},
	"customer": {
		"name": "Nue IO, Inc.", 
                 "email": "william.chase@nue.io"
	},
	"billToContact": {
		"phone": "1-555-111-2222",
		"billingCity": "San Jose",
		"billingCountry": "United States",
		"billingState": "California",
		"billingStreet": "1000 English Street",
		"billingZipCode": "95129",
		"birthday": "1988-03-07",
		"email": "william.chase@nue.io",
		"firstName": "William",
		"id": "af07313b-28b1-471b-a4f7-c9ec5483b31a",
		"lastName": "Chase",
		"middleName": null,
		"mobilePhone": "1-555-111-2222",
		"name": "Chase Kung",
		"shippingCity": "San Jose",
		"shippingCountry": "United States",
		"shippingState": "California",
		"shippingStreet": "1000 English Street",
		"shippingZipCode": "95129",
		"suffix": null
	},
	"effectiveDate": "{{orderStartForSelfService}}",
	"priceBookId": "{{priceBookIdForSelfService}}",
	"billingCycle": "Month",
	"name": "MY ORDER",
	"lines": [{
		"lineType": "LineItem",
		"productId": "{{productId}}",
		"quantity": 10,
		"subscriptionTerm": 12,
		"subscriptionStartDate": "{{orderStartForSelfService}}",
		"priceBookEntryId": "{{priceBookEntryId}}",
		"refId": "2e0e6eae-70fc-4013-b739-3c9045853c9a"
	}]
}'

Query Customer, Contacts, Orders and Subscriptions

SELF-SERVICE SCENARIO   Once the user has made their initial order and set up subscriptions, assets, or entitlements as a self-service user, they can log into the Web Portal. There, the user can easily check out company info, user details, and their order history.

 

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
  }
}

Make Changes to Subscriptions, Physical Goods and Service Entitlements 

SELF-SERVICE SCENARIO   After the user logs in to the self-service portal, they can view their subscriptions, physical assets and entitlements purchased before, and they can make changes to them, for example, update quantities, update subscription terms, renew, cancel, etc.   Users can add these changes to the shopping cart, and preview the invoices that contain the additional charges as results of these changes.

API Endpoint

POST https://api.nue.io/change-orders

Please find the API docs here. 

Update Quantity

Example

In this example, the user wants to add 10 licenses effective August 24th, 2023.  She adds the change request into the cart.  

 

API Body (in JSON): 

{
	"options": {
		"activateOrder": false,
		"previewInvoice": true
	},
	"assetChanges": [{
		"assetNumber": "SUB-0000001",
		"changeType": "UpdateQuantity",
		"quantity": 10,
		"startDate": "2023-08-24"
	}]
}

 

Please note that in Nue, subscriptions, physical assets and entitlements are considered as assets in general.  So using this API, you can make quantity changes to subscriptions, physical assets, and entitlements in a unified way.  

 

You may also specify a negative quantity (e.g., -5) if you want to reduce the number of user licenses.  

Update Subscription Term

Example

In this example, the user wants to add 6 months to an existing subscription.  

{
    "options": {
        "activateOrder": false,
        "previewInvoice": true
    },
    "assetChanges": [
        {
            "assetNumber": "SUB-000001",
            "changeType": "UpdateTerm",
            "term": 6
        }
    ]
}

Please note that the actual length of the added term is determined by the term dimension of the subscription UOM.  For example, in this use case, if the subscription UOM of SUB-000001 is Month, then 6 months will be added.  If the subscription UOM of SUB-000001 is Year, then 6 years will be added. 

 

You may also specify a negative term (e.g., -6) if you want to reduce the subscription term.  This is very rare in the self-serivce use cases.

Renew Subscription

Example

In this example, the user wants to renew one or more existing subscriptions and preview invoices: 

{
    "options": {
        "activateOrder": false,
        "previewInvoice": true,
    },
    "assetChanges": [
        {
            "assetNumber": "SUB-000001",
            "changeType": "Renew",
            "renewalTerm": 12
        }
        {
            "assetNumber": "SUB-000002",
            "changeType": "Renew",
            "renewalTerm": 1
        }
    ]
}

Please note that the actual length of the added term is determined by the term dimension of the subscription UOM.  For example, in this use case, if the subscription UOM of SUB-000001 is Month, then 12 months will be renewed.  If the subscription UOM of SUB-000002 is Year, then 1 year will be renewed. 

Cancel Subscription

Example

In this example, the user wants to cancel one or more subscriptions on a specific day: 

{
    "options": {
        "activateOrder": false,
        "previewInvoice": true,
    },
    "assetChanges": [
        {
            "assetNumber": "SUB-0000001",
            "changeType": "Cancel",
            "cancellationDate": "2023-09-30"
        }
    ]
}

Please note that you can also cancel physical assets and entitlements using the same API.

 

NOTE   All these changes are stackable.  For example, a self-service user can renew one or more subscriptions, while adding 10 licenses to selected subscriptions.

 

Checkout Changes and Pay Invoices

SELF-SERVICE SCENARIO   After the user makes changes to subscriptions, assets, and entitlements and review the changes and first invoices in the shopping cart, she can check out the shopping cart into a new order.  We call this order a Change Order. The user can then place the order, and pay for the first invoice via Stripe.

API Endpoint

POST https://api.nue.io/change-orders

Please find the API docs here. 

 

For all the use cases mentioned above, including Update Quantity, Update Subscription Term, Renewal and Cancellation, the payload is very much the same.  Developers just need to replace the options Json object with the following options: 

 

    "options" : {
        "activateInvoice" : true, 
        "cancelOnPaymentFail": true
    }

 

After this API is called, the following actions occur: 

 

• A new order containing all the changes is created, and activated.
• Upon activation, subscriptions, physical assets, and service entitlements are updated and new versions provisioned.
• The first invoice containing the additional charges (which could be negative) is created and activated.  
• If Stripe is integrated, the active invoice will be sent to Stripe for payments.  
• If the payment is successful, the entire transaction is committed.  Otherwise, the entire transaction will be canceled.  Optionally, you can ask the transaction not to be canceled, so that a sales rep can follow up with the customer for payments offline.  

Put it All Together

In summary, Nue eliminates the need for developers to create yet another set of products and pricing for self-service use.  After Rev Ops use Nue's price builder UI to build products and pricing, product managers can publish the selected products and prices for self-service access.  

 

Developers can use Nue's easy-to-use self-service APIs to perform all actions available for direct sales, including: 

• Add one or more products or services - including subscriptions, physical goods and services - into the shopping cart, and preview the first invoice. 
• Create an initial order, and the customer (company) ad user (contact) at the same time. The order is provisioned into subscriptions, physical assets and subscriptions available for the self-service user to view and manage.  At the same time, generate the first invoice and get it paid via Stripe.
• Query the customer, user, order history, subscriptions, physical assets, and service entitlements via Nue graphQL to display these objects to the end users in the self-service portal.  
• Make changes to existing subscriptions, physical assets and service entitlements, add to shopping cart, and preview the additional invoice amount. 
• Create a change order, which will update the existing subscriptions, physical assets and service entitlement.  At the same time, generate the prorated, additional invoice amount, and get it paid via Stripe.
  
  • Changes are stackable - for example, the self-service user can renew more than one subscriptions, and add more user licenses at the same time.  

The self-service APIs also leverage the power of Nue pricing engine and billing engine.  Once products and changes are added to the shopping cart, the system instantly calculates the prices and provides a preview of invoices. This creates a top-notch user experience for the end users.