GuideReference

New Orders

In the Nue Self-Service API, creating a new order allows customers to purchase products or subscriptions.

How to Create a New Order Copied!

Required Information

To create a new order, you need:

  • Customer ID: The unique identifier for the customer making the purchase

  • Effective Date: When the order becomes valid

  • Price Book Entry IDs: The unique identifiers for the products being purchased

  • Quantity: The number of units for each product

  • Subscription Information: Start date and term length for subscription products

  • Add ons: Any add ons that need to be configured if the product is a bundle

The Price Book Entry ID

The priceBookEntryId is the critical identifier that connects your order to:

  • A specific product (e.g., "Professional Plan")

  • Its price (e.g., $50/user/month)

  • The unit of measure (e.g., User/Month)

  • The price book it belongs to (e.g., "Standard Price Book")

Each published product in your catalog has one or more price book entries, and you must specify the correct one when creating an order.

Configuring Bundles

When working with bundles in the Nue Self-Service API, you can customize your order by configuring add-ons within bundles. Here's how to effectively configure bundles in your API requests:

  • Product options (or add ons) are the building blocks of bundle configuration. They represent components that can be included with or added to a bundle:

    • Bundles consist of a parent product with associated add ons that can be bundled, required, or optional. These add ons are identified by the productOptionId.

    • Bundled add ons will be automatically added without any action needed as $0 items

    • Required add ons

      • If required add ons are not explicitly configured, it will automatically be included in the created order at the default quantity. The order products have the same startDate and subscriptionTerm as the parent bundle.

      • If defined, the quantity, subscriptionTerm, and/or subscriptionStartDate will respect what is in the payload.

    • Recommended and optional add ons can be defined in the request payload

  • To configure a bundle, add the addOns array within your order product object to specify which product options to include.

  • For add ons with editable quantities, specify productOptionQuantity.

  • Add-ons can have independent subscription schedules

    • subscriptionStartDate can be defined for each add on. It not defined, it will automatically inherit subscriptionStartDate from the bundle.

    • subscriptionTerm can be defined for each add on. If not defined, it will automatically coterm the add on’s subscription with the bundle.

Creating a Draft Order

The first step is to create a draft or preview order using the /orders endpoint. This creates a draft order that shows pricing and details without financial impact.

Example payload:

{
  "customer": {
    "id": "{{customerId}}"
  },
  "options": {
    "previewInvoice": true,
    "calculateTax": false
  },
  "effectiveDate": "2024-09-18",
  "billingPeriod": "Annual",
  "orderProducts": [
    {
      "priceBookEntryId": "pbe-bundle-12345",
      "quantity": 10,
      "subscriptionStartDate": "2024-10-01",
      "subscriptionTerm": 12,
      "addOns": [
        {
          "productOptionId": "po-required-addon",
          "productOptionQuantity": 5,
          "priceTagCodes": ["ENTERPRISE_DISCOUNT"]
        },
        {
          "productOptionId": "po-fixed-quantity-addon"
          // No quantity specified for non-editable quantity
        },
        {
          "productOptionId": "po-custom-term-addon",
          "productOptionQuantity": 2,
          "subscriptionStartDate": "2024-11-01",
          "subscriptionTerm": 6
        }
      ]
    },
    {
      "priceBookEntryId": "pbe-standard-product",
      "quantity": 5,
      "subscriptionStartDate": "2024-10-01",
      "subscriptionTerm": 12
    }
  ],
  "billToContactId": "0Q0Oz000001ydCPKAY",
  "billingAccountId": "ba-12345",
  "name": "Enterprise Bundle Order",
  "description": "Annual enterprise license with add-ons",
  "poNumber": "PO-2024-9876"
}

Order Preview

The preview response includes:

  • Order details (total price, discounts, etc.)

  • Order products (individual line items)

  • Preview invoices (if requested)

  • Calculate tax (if requested)

  • Subscription information

At this stage, the order has a status of "Draft" and can be modified or canceled.

Adding Custom Fields to Order Products

When creating new orders through the Nue Self-Service API, you can include custom fields on Order Products that will transfer to related objects.

Specifically, any custom field added to an Order Product in the order payload will automatically be inherited by the resulting Subscription object, provided that the same custom field (with matching API name and compatible data type) exists on the Subscription object.

Calculating Tax

When requesting tax calculation during order preview, the system requires a shipping address to determine applicable tax rates. You can provide this address in one of two ways: either by explicitly including the shipping address in the order request body, or by omitting it and allowing the system to automatically fall back to using the shipping address already associated with the customer record.

Preview Invoice

When creating a new order with previewInvoice: true in the options, the Nue Self-Service API returns a detailed preview of the next invoice that will be generated upon order activation. This preview includes comprehensive information about each invoice, including the account details, invoice date, due date, line items for each product, transaction quantities, pricing details, and tax status. Each line item contains information about the associated product, asset, unit of measure, and transaction details, along with a breakdown of the charges in the "details" section. This preview allows you to give customers complete visibility into their future billing before finalizing the purchase, allowing them to verify dates, amounts, and billing details.

Activating the Order

Once you're satisfied with the preview, you can activate the order, which transforms the draft order into an active order, creating order products, subscriptions, assets, entitlements, and invoices.

Current LimitationsCopied!

  • Product Configuration: We support products and bundles with add-ons, but not configuring bundled products yet. You can use bundles as add-ons if they have other bundled items, but those items can't have configuration choices. In a future release, you'll be able to configure options within bundles.

  • Entitlements and Assets: Only Subscriptions are currently supported in new order creation. Entitlements and asset support will be available in a future release.

© 2025 Nue.io