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.

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.

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: Products and bundles with included product options are supported. Configurable add-ons will be available in a future release.

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