Nue Knowledge Center

Nue Docs navigation

Get Started

Configure Products and Prices Create Quotes and Orders Upsell and Renew Subscriptions Understanding Price Calculations Understanding Subscription Term Basis and Proration Ask Nue!

Use Cases

Authenticate API Users Refresh the Salesforce Sandbox

Price Builder

Products Price Book Unit of Measure (UOM)Price and Discount Tags Product Bundle Product Group Product Relationships Percent of Total Multi-attribute Pricing Multiple Currencies Manage Custom Attributes in Price Book Entries Quantity Tier Attributes for Price Tags

Object Model

Nue Object Model Overview Nue Object Model - Price Builder Nue Object Model - Lifecycle Manager Nue Object Model - Billing and Usage Accelerator Understanding Line Types Nue Object Model - Revenue Lifecycle Intelligence

Tutorial

Price Builder Quote Builder Lifecycle Manager Collections Everything Billing Usage Accelerator Lifecycle Intelligence The Nue Platform Integrations Frequently Asked Questions

Lifecycle Manager

Configure Renewal Opportunity Process Configure Create Opportunity Popup Import Subscriptions into Nue Nue Sales Console

Quote Builder

Quote Builder Overview Quote and Order Split Quote Approval Sync Primary Quote to Opportunity Template Quote Manage Filters

Lifecycle Manager

Lifecycle Manager Overview Upsell and Downsell Renew Subscriptions Co-Term Subscriptions Cross-Sell Reconfigure Bundle Subscriptions Adjust Prices Evergreen Subscriptions Cancel Subscriptions Cancel Orders Preview Invoices Manage Service Milestones and Milestone-based Billing

Nue Platform

Manage Custom Fields Product Search Plugin Lookup Filter Plugin Default Value Plugin Invoice Preview Plugin Query Nue Objects using GraphQL Price Tag Search Plugin

Use Cases

Subscription Ramp Pricing Configure Pricing for Different Billing Periods Billing Account Search Setting a Price Floor Revenue Sharing with Partners Custom Payment Terms Update Order Information Customize Auto-numbering Schemes

Everything Billing

Billing Accelerator Overview Billing Parameters Billing Schedules Invoice Status Explained Credit Memos Late Fees - a Debit Memo Use Case Catch-up Bill Run Billing Account Hierarchy Scheduled Sync Jobs Billing Groups Multiple Entities

Collections

Collections Overview Collections Scenarios - Invoicing Collections Scenarios - Credit Memos and Debit Memos Collections Scenarios - Payments Collections Scenarios - Refunds and Reversals Collections Scenarios - Write Off Payment Rules

How-to Guide

Lifecycle Manager Nue Platform

Usage Accelerator

Usage Accelerator Overview The Credit Burndown Usage Model Multiple Credit Pools Credit Proration One-time Credits Integrate with Existing Usage Systems

Developer Resources

Use Cases Object Model API Reference Apex Global Services Self-Service Reference Guide Client Side Pricing Engine

Lifecycle Intelligence

Revenue Lifecycle Intelligence Subscription and Order Metrics ARR Momentum Booking Dashboard Pipeline Dashboard Billing and Collections Dashboard

Support

Submit a support ticket

The Nue Platform

System Settings Platform Settings Lifecycle Manager Settings Price Builder Settings Billing and Usage Settings Nue Security API Keys Roles and Permissions Export and Import Understanding Data Storage and Synchronization

Integrations

Nue on Salesforce Nue on Salesforce Permission Sets Stripe Integration DocuSign Integration QuickBooks Integration NetSuite Integration - ARM Connector Recognize Revenue via RightRev Calculate Taxes via Avalara Integration Calculate Taxes via Stripe Tax Webhooks Update Nue Integration User for Salesforce Integration Nue on Salesforce Layout Configurations NetSuite Integration v2023 NetSuite Integration Setup NetSuite Connector - Fields Mapping Streamlined E-Invoicing with Avalara ELR

Home

Tutorial

The Nue Platform

Export and Import

In this tutorial, we will walk you through the steps to export and import business objects in Nue. This process is essential for backing up your data, migrating data between environments, or sharing configurations across different instances. By the end of this tutorial, you will be able to seamlessly export business objects from a Nue environment, and import business objects into a Nue environment.

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.

NOTE

The examples in this document uses API Key for authentication into Nue. See the Authentication section of the API documentation for more information.

Understanding Data Storage

Nue operates as a dual-platform system, meaning that core business objects are housed either on the Salesforce Platform or within Nue Core Services and are mirrored in the other service. Please check out this article for detailed information about the data storage and mirroring.

Nue offers a set of Export and Import APIs to work with business objects, regardless of where they are stored.

Export and Import Product Catalog

Users can use Nue API to seamless export and import the entire product catalog, including all products and their pricing details.

The product catalog consists of the following object types:

OBJECT TYPE	NAME
uom	Unit of Measure
credit-type	Credit Type
credit-pool	Credit Pool
credit-conversion	Credit Conversion
price-book	Price Book
price-tag	Price Tag
product-group	Product Group
product	Product
bundle	Product
bundle-suite	Bundle Suite
custom-setting	Custom Setting

For the most current list of supported object types, please refer to the API Docs.

Export Product Catalog

Data exports are performed asynchronously. Please follow the 3-step process below:

Create the data export job;
Get the data export job status
Retrieving export results

Create Data Export Job

Users have two options for creating a data export job:

1. Export all object types used in the product catalog, with products filtered through GraphQL.
2. Export all records for a selected list of business objects.

Export all object types through GraphQL

Endpoint

POST https://api.nue.io/async/graphql/exports

Example

The following is a CURL example that exports Nue products and bundles and their related objects through a GraphQL query:

curl --location 'https://api.nue.io/cpq/async/exports' \
--header 'Content-Type: application/json' \
--header 'nue-api-key: {{nue-api-key}}' \
--data '{"query":"query {\n  Product(where: {sku: {_is_null: false}}) {\n    autoRenew\n    bundleTemplate\n    configurable\n    createdById\n    createdDate\n    defaultRenewalTerm\n    defaultSubscriptionTerm\n    defaultUomId\n    description\n    endDate\n    freeTrialType\n    freeTrialUnit\n    id\n    imageUrl\n    lastModifiedById\n    lastModifiedDate\n    longDescription\n    name\n    priceBookId\n    priceModel\n    productCategory\n    recordType\n    referenceProductId\n    showIncludedProductOptions\n    sku\n    soldIndependently\n    startDate\n    status\n  }\n}\n","variables":{}}'

After the API is executed, a Job ID will be returned, which can be used to retrieve the asychrounous export job status. For example:

{
    "jobId": "f7531328-90d9-4b60-8ac1-85387b052f07"
}

Export all records for a selected list of business objects

Endpoint

POST https://api.nue.io/api/cpq/async/exports

Example

Here is an example using CURL to export all records from a selected list of business objects in Nue:

curl --location 'https://api.nue.io/api/cpq/async/exports' \
--header 'Content-Type: application/json' \
--data '{
  "format": "JSON",
  "objectNames": ["UOM", "PriceBook", "CreditType", "CreditPool", "CreditConversion", "PriceTag", "ProductGroup", "Product", "Bundle", "BundleSuite", "CustomSetting"]
}'

After the API is executed, a Job ID will be returned, which can be used to retrieve the asychronous export job status.

Get Export Job Status

Endpoint

The endpoint requires a request parameter called exportJobId, which corresponds to the Job ID provided by the preceding API.

GET https://api.nue.io/cpq/async/exports/:exportJobId

Example

Here is an example curl command that uses the API to get the status of the job returned:

curl --location 'https://api.nue.io/cpq/async/exports/f7531328-90d9-4b60-8ac1-85387b052f07' \
--header 'nue-api-key: {{nue-api-key}}'

Here is an example response before the job finished (truncated for brevity):

{
    "status": "Processing",
    "format": "JSON",
    "objects": [
        {
            "name": "UOM",
            "status": "Completed",
            "totalSize": 8,
            "fileUrls": [
"https://cpq-export-job.s3.amazonaws.com/7f9e1463-7c23-4c5f-bc08-acace0115616/f6eea805-4a3e-4bd8-8408-ba9260572fec/uom.jsonl?X-Amz-Security-Token=[Redacted]&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20240729T232358Z&X-Amz-SignedHeaders=host&X-Amz-Expires=7200&X-Amz-Credential=[Redacted]&X-Amz-Signature=[Redacted]"
            ]
        },
        ...,
        {
            "name": "PriceTag",
            "status": "Processing",
            "totalSize": 0
        }
    ]
}

An incomplete but still processing job will have the status Processing as shown above. Each completed object will provide the object name, status, the size of the output measured in rows of data, and one or more fileUrls. The fileUrls can be used as a parameter in curl to retrieve the export results for that object, which is demonstrated in the next and final example of the export process.

Incomplete object exports may be listed as Processing indicating that they are in the process of being exported, as in the example above for the PriceTag objects; or incomplete object exports may not yet be listed at all if the process of exporting that object has yet to begin. In the full (non-truncated) results for the example above, the following objects were returned with status Completed: UOM, CreditType, CreditPool, CreditConversion, and PriceBook. PriceTag is returned with the status Processing. Finally, ProductGroup, Product, Bundle, BundleSuite, and CustomSetting were not returned at all because they had not yet begun to be exported.

Retrieving Export Results

After you have used the Get Data Export Job Status API, as demonstrated in the previous section, you can use curl to retrieve the data for each object one-by-one. Here is an example curl command to retrieve the UOM objects from the previous example:

curl --location 'https://cpq-export-job.s3.amazonaws.com/7f9e1463-7c23-4c5f-bc08-acace0115616/f6eea805-4a3e-4bd8-8408-ba9260572fec/uom.jsonl?X-Amz-Security-Token=[Redacted]&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20240729T232358Z&X-Amz-SignedHeaders=host&X-Amz-Expires=7200&X-Amz-Credential=[Redacted]&X-Amz-Signature=[Redacted]'

Note that the fileUrls returned by the Get Data Export Job Status API include all necessary authentication credentials, which have been redacted for these examples. You do not need to provide any extra credentials for these queries.

Here is an example response (truncated for brevity):

{"meta_objectName":"UOM"}
{"roundingMode":"Up","termDimension":"Quarter","decimalScale":0,"name":"User/Quarter","active":true,"id":"User/Quarter","quantityDimension":"User"}
{"roundingMode":"Up","decimalScale":0,"name":"Each","active":true,"id":"Each","quantityDimension":"Each"}

Note that although we specified JSON format, the output is technically in JSONL format. This means that line breaks are meaningful. Do not try to edit the JSON, because it can result in errors when importing.

The first line of the output is used for validation when importing, to double-check that we are importing the correct objects.

{"meta_objectName":"UOM"}

The remaining lines are rows of objects exported from the tenant.

In order to import these objects into another tenant, save the entire results to a file such as uom.jsonl and remember the path to this file, as it will be used when importing data.

Import Product Catalog

Similar to exporting data, import data jobs are performed asynchronously, meaning the API doesn’t wait for the job to finish before returning the response. This means that importing data is a 2-step process:

Import products and pricing data, and
Get Import Job Status.

Import Products and Pricing Data

Endpoint

POST https://api.nue.io/cpq/async/imports/revenue-builder-data?import-operation=upsert

Example

Here is an example curl command that imports all importable objects using the Import products and pricing data API:

curl --location 'https://api.nue.io/cpq/async/imports/revenue-builder-data?import-operation=upsert' \
--form 'uom=@"uom.jsonl"' \
--form 'credit-type=@"credittype.jsonl"' \
--form 'credit-pool=@"creditpool.jsonl"' \
--form 'credit-conversion=@"creditconversion.jsonl"' \
--form 'price-book=@"pricebook.jsonl"' \
--form 'price-tag=@"pricetag.jsonl"' \
--form 'product-group=@"productgroup.jsonl"' \
--form 'product=@"product.jsonl"' \
--form 'bundle=@"bundle.jsonl"' \
--form 'bundle-suite=@"bundlesuite.jsonl"' \
--form 'custom-setting=@"customsetting.jsonl"'

Here is a breakdown of the parameters provided to the API in this example:

PARAMETER	EXAMPLE	DESCRIPTION
import-operation	upsert	This parameter relates to some special behavior of PriceBookEntry objects. If you know that you are not importing any new PriceBookEntry objects, you can safely omit this parameter such that the location becomes https://api.nue.io/cpq/async/imports/revenue-builder-data otherwise, if you are re-importing any existing PriceBookEntry objects, or if you are not sure, please include this parameter.
uom	@"uom.jsonl"	This tells curl to use the file uom.jsonl in the same directory as the import file to import UOM objects. If you are not importing UOM objects, feel free to omit this parameter.
credit-type	@"credittype.jsonl"	Similarly for CreditType objects.
credit-pool	@"creditpool.jsonl"	Similarly for CreditPool objects.
credit-conversion	@"creditconversion.jsonl"	Similarly for CreditConversion objects.
price-book	@"pricebook.jsonl"	Similarly for PriceBook objects.
price-tag	@"pricetag.jsonl"	Similarly for PriceTag objects.
product-group	@"productgroup.jsonl"	Similarly for ProductGroup objects.
product	@"product.jsonl"	Similarly for Product objects.
bundle	@"bundle.jsonl"	Similarly for Bundle objects.
bundle-suite	@"bundlesuite.jsonl"	Similarly for BundleSuite objects.
custom-setting	@"customsetting.jsonl"	Similarly for CustomSetting objects.

The following is an example response of the API:

{
    "jobId": "a06d0e8f-9046-439d-b336-d24d55d2d7fa"
}

Import jobs are performed asynchronously, meaning the API doesn’t wait for the job to finish before returning the response. Instead, the API returns a jobId that the user can provide as the parameter to a Get Import Job Status API call in order to check the status of the given job.

Get Import Job Status

Endpoint

GET https://api.perftest.nue.io/cpq/async/imports/revenue-builder-data/{{importJobId}}

Example

Here is an example curl command that gets the status of an import job using the Get Import Job Status API, using the jobId returned in the previous example:

curl --location 'https://api.perftest.nue.io/cpq/async/imports/revenue-builder-data/a06d0e8f-9046-439d-b336-d24d55d2d7fa'

In this API, the only parameter aside from authentication is the jobId that was the output of the Import products and pricing data API call in the previous step.

Example results from the above query (truncated for brevity):

{
    "jobId": "a06d0e8f-9046-439d-b336-d24d55d2d7fa",
    "status": "Completed",
    "integrationType": "Salesforce",
    "format": "JSON",
    "startTime": "2024-07-26T00:05:28Z",
    "endTime": "2024-07-26T00:05:40Z",
    "importJobs": [
        ...,
        {
            "objectName": "CreditType",
            "status": "Completed",
            "integrationType": "Salesforce",
            "format": "JSON",
            "startOn": "2024-07-26T00:05:28Z",
            "endOn": "2024-07-26T00:05:40Z"
        },
        ...
    ]
}

Note that the above results have been truncated so that they only include the results for CreditType. Complete results will include similar result JSON objects for each object type (e.g., UOM, CreditType, etc.) being exported. If the process is not yet complete, these results will show the object currently being imported with status Processing as in the export example, and objects that have not started being imported will not be listed. Any errors will be returned in the result JSON object along with details that explain what went wrong.

Import Orders and Subscriptions

Users can import subscriptions into Nue via API by following these steps:

1. Prepare the Subscription Import CSV file.
2. Execute the Import API to upload the subscription CSV file.

After the import, one active order is created for each subscription in the import file. The orders and subscriptions can be viewed in Salesforce.

Create Import Job

Endpoint

POST https://api.nue.io/cpq/async/imports

Example

The following example creates a subscription import job that accepts a Subscription CSV file:

curl --location 'https://api.nue.io/cpq/async/imports' \
--header 'Content-Type: application/json' \
--header 'nue-api-key: {{nue-api-key}}' \
--data '{
    "format": "CSV",
    "objectName": "Subscription"
}'

This API returns a status code of 201 and includes a Job ID in the response payload, representing the ID of the asynchronous job created for the import.

Upload Subscription CSV File

Endpoint

PATCH https://api.nue.io/cpq/async/imports/{{importJobId}}/content

Example

The following example demonstrates how to upload a Subscription CSV file to an import job specified by the importJobId.

curl --location --request PATCH 'https://api.nue.io/cpq/async/imports/{{importJobId}}/content' \
--header 'nue-api-key: {{nue-api-key}}' \
--form 'data=@"3SmRwtS_Y/subscriptionUploadFile.csv"'

Get Subscription Import Result

Endpoint

GET https://api.nue.io/cpq/async/imports/{{importJobId}}

Example

The following example retrieves the subscription import result of an import job specified by the importJobId.

curl --location 'https://api.nue.io/cpq/async/imports/{{importJobId}}' \
--header 'nue-api-key: {{nue-api-key}}'

Export Transaction Data

Export via API

Users can utilize the Export API to export up to 10,000 records of the following transactions into CSV files:

Orders and Order Products
Invoice, Invoice Items, and Invoice Item Details
Credit Memo, Credit Memo Items, and Credit Memo Item Details
Usage
Tax Codes
Transaction Hub

Create Export Job

Endpoint

POST https://api.nue.io/cpq/async/exports

Example

This example demonstrates how to export the results of a GraphQL query on Usage records into a CSV file.

curl --location 'https://api.nue.io/cpq/async/exports' \
--header 'nue-api-key: {{nue-api-key}}' \
--data '{
  "format": "CSV",
  "objectNames": [
    "Usage"
  ],
  "query": "query { Usage( where: { _and:[{  _and : [ { startTime: {  _lte  : \"2024-07-31T23:59:59-07:00\" } } { startTime: {  _gte  : \"2024-07-01T00:00:00-07:00\" } } ] } { _and :[ {  _and : [ { startTime: {  _lte  : \"2024-07-31T23:59:59-07:00\" } } { startTime: {  _gte  : \"2024-07-01T00:00:00-07:00\" } } ] }{ customer : { id : {  _eq  : \"001RR00000JcgiCYAR\" } } }] } { isCash: {  _eq  : true } } { currencyIsoCode: {  _eq  : \"USD\" } } ] }  orderBy: {  startTime: desc  } ){ customer { name} id name subscriptionNumber product { name, sku} status startTime endTime quantity termedTotalQuantity ratedAmount termStartDate termEndDate orderNumber orderProductNumber createdDate lastModifiedDate subscriptionId zoneId windowSize ratableTime ratedTime orderProductId properties errorCode errorMessage invoiceId invoiceItemId invoiceItemNumber invoiceNumber creditsApplied invoiceItemDetailId invoiceItemDetailNumber isCash salesAccount { name}  }}"
}'

Upon successful execution of the API, an export Job ID will be created.

Get Export Job Result

Endpoint

POST https://api.nue.io/cpq/async/exports/{{exportJobId}}

This endpoint retrieves the status and details of a specific export job.

Export via UI

Users can click the 'Download' action icon above the list for the following objects in Nue to export transactions into CSV files: Order, Invoice, Credit Memo, Usage.

Users can choose to export either the currently selected fields or all fields. Additionally, users can use the search box and filters to refine the list of objects and their related records for export. When users export a set of records, their related child records will be exported as a separate CSV file.

For example, when users click the 'Download' action on the Invoice List, a popup will appear, allowing them to select the types of records to export. Options include invoices, invoice items, and invoice item details.