Query Nue Objects using GraphQL

14 min

Introduction

Nue offers a dual-platform, which means Nue’s platform stores and manages data from 2 different SaaS Platforms - Salesforce & Nue’s Cloud Services.

If your Nue instance is connected to a Salesforce org, all the objects that support products and pricing have Salesforce as the only data source.

You can use Nue’s graphQL service to access the data of any objects in Nue. The object can be queried from either Salesforce or from Nue's AWS Services, depending on the data source.

You can login to Nue and navigate to Settings > Business Objects, and see a list of objects in Nue. For any object in the list, if Salesforce API Name is not empty, the object also has Salesforce as the data source.

GraphQL Endpoints

Nue exposes two GraphQL endpoints. Each query is sent to the endpoint that owns the object you are querying:

Service	Endpoint	Data source	Use it for
CPQ	POST https://api.nue.io/async/graphql	Connected Salesforce org	Product catalog, pricing, quotes, orders, and pipeline objects
Order	POST https://api.nue.io/orders/async/graphql	Nue cloud services (AWS)	Customers, subscriptions, billing, and post-sale objects

Both endpoints accept the same request shape — a JSON body with a query string (and optional variables) — and the same nue-api-key authentication. See API Keys for how to authenticate.

Supported Objects

You can query the following objects. CPQ objects are served from the connected Salesforce org; Order objects are served from Nue's cloud services on AWS, which offer significantly improved performance.

CPQ objects — https://api.nue.io/async/graphql

Product, ProductOption, ProductFeature, Feature, BundleSuite, ProductRelationship, PriceBook, UOM, PriceDimension, PriceTier, Quote, QuoteLineItem, Order, OrderProduct, Opportunity, PricingPlugin

Order objects — https://api.nue.io/orders/async/graphql

Customer, Contact, RelatedCustomer, Entity, UserProfile, Subscription, Asset, AssetOrderProduct, Entitlement, Invoice, InvoiceItem, InvoiceItemDetail, CreditMemo, CreditMemoItem, DebitMemo, PaymentApplication, PaymentMethod

Order line items are queried as OrderProduct (not OrderItem). To discover the exact fields, filters, and picklist values available on any object, use Schema Introspection (described later on this page).

Generate graphQL Query

Login to Nue, and navigate to the Settings, and search with keyword ‘graph’ and select the result ‘GraphQL Generator’. The GraphQL Generator will be automatically launched.

In the GraphQL generator, you can select a number of fields, and create filters if necessary. The fields and filtering conditions will be automatically generated as part of the GraphQL query. Once you are ready, you can click ‘Copy to Clipboard’.

For example, the following GraphQL query is generated to find all active, non-bundle, standalone products.

query {
 Product(where: {_and: [{configurable: {_eq: false}}, {status: {_eq: "Active"}}]}) {
   autoRenew
   Ruby__ProductCost__c
   billingPeriod
   billingTiming
   bundleTemplate
   configurable
   createdById
   createdDate
   defaultRenewalTerm
   defaultSubscriptionTerm
   defaultUomId
   description
   endDate
   freeTrialType
   freeTrialUnit
   id
   imageUrl
   lastModifiedById
   lastModifiedDate
   longDescription
   name
   priceBookId
   priceModel
   productCategory
   recordType
   referenceProductId
   showIncludedProductOptions
   sku
   soldIndependently
   startDate
   status
 }
}

Run GraphQL Query for Objects in Nue on Salesforce

Almost all objects should be accessible by querying Salesforce. The below example shows how to query Products.

Query Products

Query Product Details

POST

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

query {
  Product(where: {
    _and: [
      { configurable: { _eq: false } },
      { status: { _eq: "Active" } }
    ]
  }) {
    autoRenew
    billingPeriod
    billingTiming
    bundleTemplate
    configurable
    createdById
    createdDate
    defaultRenewalTerm
    defaultSubscriptionTerm
    defaultUomId
    description
    endDate
    freeTrialType
    freeTrialUnit
    id
    imageUrl
    lastModifiedById
    lastModifiedDate
    longDescription
    name
    priceBookId
    priceModel
    productCategory
    recordType
    referenceProductId
    showIncludedProductOptions
    sku
    soldIndependently
    startDate
    status
  }
}

curl --location --request POST 'https://api.nue.io/async/graphql' \
--header 'apiAccessKey: {{apiAccessKey}}' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"query {\n  Product(where: {_and: [{configurable: {_eq: false}}, {status: {_eq: \"Active\"}}]}) {\n    autoRenew\n    Ruby__ProductCost__c\n    billingPeriod\n    billingTiming\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":{}}'

Run GraphQL Query for Objects in Nue on AWS

Order objects — such as Customers, Contacts, Subscriptions, Invoices, Credit Memos, Assets, and Entitlements — are queried from Nue's cloud services on AWS using the https://api.nue.io/orders/async/graphql endpoint, which offers significantly improved performance and speeds. The example below shows how to query Subscriptions.

Query Subscriptions

Query Subscription Details

POST

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

query {
  Product(where: {
    _and: [
      { configurable: { _eq: false } },
      { status: { _eq: "Active" } }
    ]
  }) {
    autoRenew
    billingPeriod
    billingTiming
    bundleTemplate
    configurable
    createdById
    createdDate
    defaultRenewalTerm
    defaultSubscriptionTerm
    defaultUomId
    description
    endDate
    freeTrialType
    freeTrialUnit
    id
    imageUrl
    lastModifiedById
    lastModifiedDate
    longDescription
    name
    priceBookId
    priceModel
    productCategory
    recordType
    referenceProductId
    showIncludedProductOptions
    sku
    soldIndependently
    startDate
    status
  }
}

curl --location --request POST 'https://api.nue.io/orders/async/graphql' \
--header 'apiAccessKey: {{apiAccessKey}}' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"query Subscription {\n  Subscription {\n    actualSubscriptionTerm\n    autoRenew\n    billCycleDay\n    billCycleStartMonth\n    billingAccountId\n    billingPeriod\n    billingTiming\n    bundled\n    cancellationDate\n    createdById\n    createdDate\n    customerId\n    defaultPaymentMethodId\n    description\n    entityId\n    evergreen\n    externalId\n    externalName\n    firstFullCreditPeriodStartDate\n    freeTrialConversionDate\n    id\n    includedUnits\n    lastModifiedById\n    lastModifiedDate\n    lastVersionedSubscriptionId\n    listPrice\n    name\n    orderOnDate\n    orderProductId\n    originalSubscriptionId\n    originalSubscriptionNumber\n    parentId\n    parentObjectType\n    priceBookEntryId\n    priceBookId\n    productId\n    quantity\n    reconfigureEffectiveDate\n    renewalTerm\n    rootId\n    salesPrice\n    status\n    subscriptionCompositeId\n    subscriptionEndDate\n    subscriptionLevel\n    subscriptionStartDate\n    subscriptionTerm\n    subscriptionVersion\n    taxAmount\n    tcv\n    todayARR\n    todayCMRR\n    todaysQuantity\n    totalACV\n    totalAmount\n    totalPrice\n    totalTCV\n    uomId\n  }\n}"}'

Filtering Results

Every object collection accepts a where argument. Combine conditions with the boolean operators _and and _or, and match individual fields with operators such as _eq, _neq, _like, _in, _gt, _gte, _lt, and _lte.

_like performs a case-insensitive substring (contains) match — pass the term you want to find, such as { _like: "Acme" }. Do not wrap the term in % wildcards; a % is matched literally, so { _like: "%Acme%" } looks for values that contain the literal characters %Acme% and returns nothing.

query {
  Customer(
    where: {
      _and: [
        { status: { _eq: "Active" } },
        { name: { _like: "Acme" } }
      ]
    }
  ) {
    id
    name
    status
  }
}

GraphQL automatically restricts filtering and sorting to fields that are marked as filterable and sortable for each object — no extra configuration is required.

Pagination and Record Limits

Use the page argument to control how many records are returned and where the result set starts:

query {
  Invoice(
    where: { status: { _eq: "Posted" } }
    page: { cursor: 0, limit: 50 }
  ) {
    id
    status
    amount
  }
}

A single query returns a maximum of 100 records. If you request limit greater than 100, it is clamped to 100.

To page through a larger result set, increase cursor (for example cursor: 0, then cursor: 100, and so on) while keeping the same where filter.

When a result is capped at 100 records, the response includes a truncation signal so you know more records may exist:

{
  "status": "SUCCESS",
  "data": {
    "result": {
      "Invoice": [ "... 100 records ..." ]
    },
    "truncated": true,
    "truncationMessage": "Returned 100 records. More matching records may exist. Please refine your search criteria."
  }
}

If you see truncated: true, add or tighten your where filter (or page through with cursor) to retrieve the remaining records.

Filtering High-Volume Objects

Customer and Contact can hold very large numbers of records. Always include a where filter when querying them so results stay fast and within the 100-record cap:

query {
  Customer(
    where: { name: { _like: "Acme" } }
    page: { cursor: 0, limit: 25 }
  ) {
    id
    name
  }
}

A broad, unfiltered query against a high-volume object can return a very large or truncated result set. Adding at least one filter (such as name, status, or createdDate) keeps the query efficient and the answer complete.

Schema Introspection

The GraphQL endpoints support standard introspection, so you can discover the available objects, fields, relationships, and enum values directly from the API instead of relying on hardcoded assumptions.

List every available type:

query {
  __schema {
    types {
      name
      kind
    }
  }
}

Inspect the fields of a specific object (here, Customer):

query {
  __type(name: "Customer") {
    fields {
      name
      type {
        name
        kind
      }
    }
  }
}

Send introspection queries to the endpoint that owns the object — /async/graphql for CPQ objects and /orders/async/graphql for Order objects.

GraphQL Relationship Traversal — query nested and reverse relationships in a single round trip.

GraphQL Aggregations — count, sum, avg, min, max, and groupBy rollups.

Querying Nue with Natural Language — let an AI agent build and run these queries for you across services.