---
title: Price Tags
slug: price-tags
docTags: 
createdAt: 2026-03-17T21:13:54.077Z
---

# Price Tags

Price tags modify pricing through volume, tiered, or ramp calculations. They allow you to define dynamic pricing rules that are evaluated at quote time, giving you flexible pricing beyond simple per-unit rates.

Use this guide when you need to apply catalog-defined pricing dimensions or discount dimensions to quote line items -- whether by referencing tags explicitly in the request or relying on auto-attached tags from product configuration.

## Price Tag Types

| Type                                 | Description                                   | Effect                                                  |
| ------------------------------------ | --------------------------------------------- | ------------------------------------------------------- |
| **PriceDimension** (price tag)       | Overrides or sets the unit price              | Replaces the base unit price from the Price Book Entry  |
| **DiscountDimension** (discount tag) | Applies a percentage or fixed amount discount | Reduces the price after the base unit price is resolved |

## Tag Evaluation Modes

| Mode       | Description                                                                            | Example                                                                 |
| ---------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| **Volume** | A single tier is selected based on the total quantity; all units use that tier's price | 0-100 units = $10, 100-500 units = $8, 500+ units = $6                  |
| **Tiered** | Units are distributed across tiers; each tier prices only the units within its range   | First 100 units at $10, the next 400 at $8, the remainder at $6         |
| **Ramp**   | Different rates apply across time periods within the subscription term                 | Months 1-3 at 50% off, months 4-6 at 25% off, months 7-12 at full price |

## Tier Ranges

A tier matches when `startUnit < quantity <= endUnit`: the lower bound is exclusive and the upper bound is inclusive. Consecutive tiers share a boundary, so each tier's `startUnit` is the previous tier's `endUnit`, and the first tier starts at `0` so that a quantity of 1 is covered:

| Tier | `startUnit` | `endUnit` | Covers  |
| ---- | ----------- | --------- | ------- |
| 1    | `0`         | `100`     | 1-100   |
| 2    | `100`       | `200`     | 101-200 |
| 3    | `200`       | `300`     | 201-300 |

A quantity outside every tier -- above the last `endUnit`, or in a gap left by non-adjacent tiers -- receives no adjustment from the tag. The request still succeeds and no error is returned, so verify the pricing fields on the line item to confirm a tier was applied.

## How Tags Are Applied

Price tags reach a line item through two mechanisms:

- **Auto-attached:** Configured directly on the product in the catalog. These tags are applied automatically whenever the product appears on a quote. No action is required in the API request.
- **Request-applied:** Specified explicitly in the `priceTags` array on the product input. These are evaluated in addition to any auto-attached tags.

## PriceTagInput Structure

Tags can be referenced by code or by ID. You must provide one or the other -- not both.

```json
"priceTags": [
  { "code": "VOLUME_TIER_ENTERPRISE" },
  { "id": "a1B2c3D4e5F6g7H8" }
]
```

| Field  | Type   | Required       | Description                               |
| ------ | ------ | -------------- | ----------------------------------------- |
| `code` | string | One of code/id | The price tag code defined in the catalog |
| `id`   | string | One of code/id | The price tag record ID                   |

:::hint{type="info"}
**Important:**
&#x20;Provide either `code` or `id` on a tag entry, not both. Sending both returns `400` -- `priceTags[0]: Only one of [code, id] should be set`. Referencing a tag by code and by id are otherwise equivalent.A tag code that does not resolve is **silently ignored**: the request returns `200`, the line is priced with no discount, and the tag is absent from the response `priceTags` array. Check `priceTags` in the response to confirm a tag was actually attached.
:::

## Response: priceTags

Each response line item carries a `priceTags` array listing the tags that were attached to that line. Every entry is the tag **definition**, including its full tier table:

```json
"priceTags": [
  {
    "name": "Volume Tier Enterprise",
    "id": "a0iHE000001WRqvYAG",
    "recordType": "DiscountDimension",
    "priceDimensionType": "Quantity",
    "priceType": "Volume",
    "active": true,
    "startTime": null,
    "endTime": null,
    "priceTiers": [
      {
        "tierNumber": 1,
        "startUnit": 0.00,
        "startUnitDimension": null,
        "endUnit": 100.00,
        "endUnitDimension": null,
        "chargeModel": "PerUnit",
        "amount": null,
        "discountPercentage": 0.00
      },
      {
        "tierNumber": 2,
        "startUnit": 100.00,
        "startUnitDimension": null,
        "endUnit": null,
        "endUnitDimension": null,
        "chargeModel": "PerUnit",
        "amount": null,
        "discountPercentage": 20.00
      }
    ]
  }
]
```

:::hint{type="info"}
`priceTags`**&#x20;does not report the resolved outcome**

The array tells you which tags were attached and what their tiers are -- it does not say which tier matched or what was applied. Read the pricing fields on the line item itself to see the result:

- A price tag resolves the unit price, so compare `listPrice` and `listTotalPrice`.
- A discount tag lands in `systemDiscount` (percentage) and `systemDiscountAmount` (currency), then `subtotal` = `listTotalPrice` - `systemDiscountAmount`.
- Tag discounts do **not** populate `discount` or `discountAmount`; those hold discretionary discounts you pass in the request and stay `0` when only a tag applied.

For example, a 500-unit line at $2.00 with the tag above returns `listTotalPrice: 12000`, `systemDiscount: 20`, `systemDiscountAmount: 2400` and `totalPrice: 9600`, while `discount` and `discountAmount` remain `0`.
:::

## Authentication Setup

All examples below use the following headers:

```javascript
const myHeaders = new Headers();
myHeaders.append("nue-api-key", "YOUR_API_KEY_HERE");
myHeaders.append("Content-Type", "application/json");
```

***

## Use Case 1: Apply a Discount Tag by ID

Reference a discount tag using its record ID. The tag's discount logic (percentage, amount, tiered, etc.) is evaluated by the pricing engine.

```javascript
const quoteData = {
  opportunityId: "006xx000001abc123",
  name: "Discount Tag by ID",
  subscriptionStartDate: "2025-01-01",
  subscriptionEndDate: "2026-01-01",
  subscriptionTermDimension: "Month",
  subscriptionTerm: 12,
  products: [
    {
      productSku: "PLATFORM_BASE",
      uom: "User/Month",
      quantity: 100,
      priceTags: [{ id: "a1B2c3D4e5F6g7H8" }]
    }
  ]
};

fetch('https://api.nue.io/cpq/quotes:preview', {
  method: 'POST',
  headers: myHeaders,
  body: JSON.stringify(quoteData)
})
.then(response => response.json())
.then(result => {
  const line = result.quoteLineItems[0];
  console.log(`List price: $${line.listTotalPrice}`);
  console.log(`After tag: $${line.totalPrice}`);
})
.catch(error => console.log('Error:', error));
```

```bash
curl -X POST 'https://api.nue.io/cpq/quotes:preview' \
  -H 'nue-api-key: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "opportunityId": "006xx000001abc123",
    "name": "Discount Tag by ID",
    "subscriptionStartDate": "2025-01-01",
    "subscriptionEndDate": "2026-01-01",
    "subscriptionTermDimension": "Month",
    "subscriptionTerm": 12,
    "products": [
      {
        "productSku": "PLATFORM_BASE",
        "uom": "User/Month",
        "quantity": 100,
        "priceTags": [{ "id": "a1B2c3D4e5F6g7H8" }]
      }
    ]
  }'
```

The pricing engine looks up the tag by its record ID, resolves the discount logic, and applies it to the line. The `priceTags` array in the response confirms which tag was attached; read `systemDiscount` and `systemDiscountAmount` on the line to see what it applied.

***

## Use Case 2: Apply a Discount Tag by Code

Reference a discount tag using its code. This is often more readable and portable across environments than using IDs.

```javascript
const quoteData = {
  opportunityId: "006xx000001abc123",
  name: "Discount Tag by Code",
  subscriptionStartDate: "2025-01-01",
  subscriptionEndDate: "2026-01-01",
  subscriptionTermDimension: "Month",
  subscriptionTerm: 12,
  products: [
    {
      productSku: "PLATFORM_BASE",
      uom: "User/Month",
      quantity: 100,
      priceTags: [{ code: "REGR_DISC_QTY_TIERED" }]
    }
  ]
};

fetch('https://api.nue.io/cpq/quotes:preview', {
  method: 'POST',
  headers: myHeaders,
  body: JSON.stringify(quoteData)
})
.then(response => response.json())
.then(result => {
  const line = result.quoteLineItems[0];
  console.log(`List price: $${line.listTotalPrice}`);
  console.log(`Discounted price: $${line.totalPrice}`);
})
.catch(error => console.log('Error:', error));
```

```bash
curl -X POST 'https://api.nue.io/cpq/quotes:preview' \
  -H 'nue-api-key: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "opportunityId": "006xx000001abc123",
    "name": "Discount Tag by Code",
    "subscriptionStartDate": "2025-01-01",
    "subscriptionEndDate": "2026-01-01",
    "subscriptionTermDimension": "Month",
    "subscriptionTerm": 12,
    "products": [
      {
        "productSku": "PLATFORM_BASE",
        "uom": "User/Month",
        "quantity": 100,
        "priceTags": [{ "code": "REGR_DISC_QTY_TIERED" }]
      }
    ]
  }'
```

The `REGR_DISC_QTY_TIERED` tag evaluates the quantity (100) against its tiered discount schedule and applies the appropriate discount.

***

## Use Case 3: Apply a Price Tag by Code (Unit Price Override)

A PriceDimension tag overrides the unit price from the Price Book Entry. This is used for volume pricing, tiered pricing, or any scenario where the per-unit rate depends on quantity or other factors.

```javascript
const quoteData = {
  opportunityId: "006xx000001abc123",
  name: "Price Tag Override",
  subscriptionStartDate: "2025-01-01",
  subscriptionEndDate: "2026-01-01",
  subscriptionTermDimension: "Month",
  subscriptionTerm: 12,
  products: [
    {
      productSku: "PLATFORM_BASE",
      uom: "User/Month",
      quantity: 500,
      priceTags: [{ code: "VOLUME_TIER_ENTERPRISE" }]
    }
  ]
};

fetch('https://api.nue.io/cpq/quotes:preview', {
  method: 'POST',
  headers: myHeaders,
  body: JSON.stringify(quoteData)
})
.then(response => response.json())
.then(result => {
  const line = result.quoteLineItems[0];
  console.log(`Unit price (after tag): $${line.listUnitPrice}`);
  console.log(`Total: $${line.totalPrice}`);
})
.catch(error => console.log('Error:', error));
```

```bash
curl -X POST 'https://api.nue.io/cpq/quotes:preview' \
  -H 'nue-api-key: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "opportunityId": "006xx000001abc123",
    "name": "Price Tag Override",
    "subscriptionStartDate": "2025-01-01",
    "subscriptionEndDate": "2026-01-01",
    "subscriptionTermDimension": "Month",
    "subscriptionTerm": 12,
    "products": [
      {
        "productSku": "PLATFORM_BASE",
        "uom": "User/Month",
        "quantity": 500,
        "priceTags": [{ "code": "VOLUME_TIER_ENTERPRISE" }]
      }
    ]
  }'
```

The `VOLUME_TIER_ENTERPRISE` tag evaluates the quantity (500) against its tier table and sets the appropriate unit price. The resolved price shows up in the line's `listPrice` and `listTotalPrice`; `priceTags` echoes the tag definition and its tiers.

***

## Use Case 4: Price Tag and Discount Tag on the Same Line

You can apply both a price tag and a discount tag to the same product. The price tag resolves the unit price first, then the discount tag reduces the result.

```javascript
const quoteData = {
  opportunityId: "006xx000001abc123",
  name: "Price + Discount Tags Combined",
  subscriptionStartDate: "2025-01-01",
  subscriptionEndDate: "2026-01-01",
  subscriptionTermDimension: "Month",
  subscriptionTerm: 12,
  products: [
    {
      productSku: "PLATFORM_BASE",
      uom: "User/Month",
      quantity: 500,
      priceTags: [
        { code: "VOLUME_TIER_ENTERPRISE" },
        { code: "LOYALTY_DISCOUNT_10PCT" }
      ]
    }
  ]
};

fetch('https://api.nue.io/cpq/quotes:preview', {
  method: 'POST',
  headers: myHeaders,
  body: JSON.stringify(quoteData)
})
.then(response => response.json())
.then(result => {
  const line = result.quoteLineItems[0];
  console.log(`List unit price (from price tag): $${line.listUnitPrice}`);
  console.log(`Total after discount tag: $${line.totalPrice}`);
  console.log('Attached tags:', line.priceTags);
})
.catch(error => console.log('Error:', error));
```

```bash
curl -X POST 'https://api.nue.io/cpq/quotes:preview' \
  -H 'nue-api-key: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "opportunityId": "006xx000001abc123",
    "name": "Price + Discount Tags Combined",
    "subscriptionStartDate": "2025-01-01",
    "subscriptionEndDate": "2026-01-01",
    "subscriptionTermDimension": "Month",
    "subscriptionTerm": 12,
    "products": [
      {
        "productSku": "PLATFORM_BASE",
        "uom": "User/Month",
        "quantity": 500,
        "priceTags": [
          { "code": "VOLUME_TIER_ENTERPRISE" },
          { "code": "LOYALTY_DISCOUNT_10PCT" }
        ]
      }
    ]
  }'
```

**Execution order:** The volume price tag sets the unit price based on the 500-unit tier, then the loyalty discount tag reduces the total by 10%. Both tags appear in the line's `priceTags` array, and the combined effect is visible in `systemDiscount` and `systemDiscountAmount`.

***

## Use Case 5: Auto-Attached Tags (No Request Input Needed)

If a product has auto-attached tags configured in the catalog, they are applied automatically. You do not need to include a `priceTags` array in the request. The response still shows the applied tags.

```javascript
const quoteData = {
  opportunityId: "006xx000001abc123",
  name: "Auto-Attached Tags Only",
  subscriptionStartDate: "2025-01-01",
  subscriptionEndDate: "2026-01-01",
  subscriptionTermDimension: "Month",
  subscriptionTerm: 12,
  products: [
    {
      productSku: "PLATFORM_BASE",   // Has auto-attached VOLUME_TIER tag in catalog
      uom: "User/Month",
      quantity: 200
      // No priceTags array -- auto-attached tags are applied automatically
    }
  ]
};

fetch('https://api.nue.io/cpq/quotes:preview', {
  method: 'POST',
  headers: myHeaders,
  body: JSON.stringify(quoteData)
})
.then(response => response.json())
.then(result => {
  const line = result.quoteLineItems[0];
  console.log(`Unit price (from auto-attached tag): $${line.listUnitPrice}`);
  console.log(`Total: $${line.totalPrice}`);
  console.log('Attached tags:', line.priceTags);
  // priceTags shows the auto-attached tag even though none were in the request
})
.catch(error => console.log('Error:', error));
```

```bash
curl -X POST 'https://api.nue.io/cpq/quotes:preview' \
  -H 'nue-api-key: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "opportunityId": "006xx000001abc123",
    "name": "Auto-Attached Tags Only",
    "subscriptionStartDate": "2025-01-01",
    "subscriptionEndDate": "2026-01-01",
    "subscriptionTermDimension": "Month",
    "subscriptionTerm": 12,
    "products": [
      {
        "productSku": "PLATFORM_BASE",
        "uom": "User/Month",
        "quantity": 200
      }
    ]
  }'
```

The pricing engine automatically evaluates the product's catalog-configured tags. If you also specify request-applied tags in `priceTags`, both auto-attached and request-applied tags are evaluated together.

***

## Use Case 6: Different Tags on Different Lines

Each product in the `products` array can have its own `priceTags`, allowing different pricing strategies per line.

```javascript
const quoteData = {
  opportunityId: "006xx000001abc123",
  name: "Per-Line Tag Assignment",
  subscriptionStartDate: "2025-01-01",
  subscriptionEndDate: "2026-01-01",
  subscriptionTermDimension: "Month",
  subscriptionTerm: 12,
  products: [
    {
      productSku: "PLATFORM_BASE",
      uom: "User/Month",
      quantity: 500,
      priceTags: [{ code: "VOLUME_TIER_ENTERPRISE" }]
    },
    {
      productSku: "ANALYTICS_ADDON",
      uom: "User/Month",
      quantity: 100,
      priceTags: [{ code: "REGR_DISC_QTY_TIERED" }]
    },
    {
      productSku: "DATA_EXPORT",
      uom: "User/Month",
      quantity: 50
      // No priceTags -- uses base Price Book Entry price (or auto-attached tags)
    }
  ]
};

fetch('https://api.nue.io/cpq/quotes:preview', {
  method: 'POST',
  headers: myHeaders,
  body: JSON.stringify(quoteData)
})
.then(response => response.json())
.then(result => {
  result.quoteLineItems.forEach(item => {
    const tags = item.priceTags || [];
    console.log(`${item.product.sku}: $${item.listUnitPrice}/unit → $${item.totalPrice} total (${tags.length} tags applied)`);
  });
})
.catch(error => console.log('Error:', error));
```

```bash
curl -X POST 'https://api.nue.io/cpq/quotes:preview' \
  -H 'nue-api-key: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "opportunityId": "006xx000001abc123",
    "name": "Per-Line Tag Assignment",
    "subscriptionStartDate": "2025-01-01",
    "subscriptionEndDate": "2026-01-01",
    "subscriptionTermDimension": "Month",
    "subscriptionTerm": 12,
    "products": [
      {
        "productSku": "PLATFORM_BASE",
        "uom": "User/Month",
        "quantity": 500,
        "priceTags": [{ "code": "VOLUME_TIER_ENTERPRISE" }]
      },
      {
        "productSku": "ANALYTICS_ADDON",
        "uom": "User/Month",
        "quantity": 100,
        "priceTags": [{ "code": "REGR_DISC_QTY_TIERED" }]
      },
      {
        "productSku": "DATA_EXPORT",
        "uom": "User/Month",
        "quantity": 50
      }
    ]
  }'
```

Each product is priced independently. `PLATFORM_BASE` uses a volume tier tag, `ANALYTICS_ADDON` uses a quantity-tiered discount tag, and `DATA_EXPORT` uses its base price (or auto-attached tags from the catalog).

***

## Use Case 7: Ramp Discount Tags (Multi-Period)

Ramp discount tags apply different discount rates over different time periods within the subscription term. For example, a tag might give 50% off for the first 3 months, then 25% off for months 4-6, and full price thereafter. Ramp tags are configured in the catalog with time-based tiers. You apply them the same way as any other tag.

```javascript
const quoteData = {
  opportunityId: "006xx000001abc123",
  name: "Ramp Discount Schedule",
  subscriptionStartDate: "2025-01-01",
  subscriptionEndDate: "2026-01-01",
  subscriptionTermDimension: "Month",
  subscriptionTerm: 12,
  products: [
    {
      productSku: "PLATFORM_BASE",
      uom: "User/Month",
      quantity: 50,
      priceTags: [{ code: "RAMP_ONBOARDING_DISCOUNT" }]
    }
  ]
};

fetch('https://api.nue.io/cpq/quotes:preview', {
  method: 'POST',
  headers: myHeaders,
  body: JSON.stringify(quoteData)
})
.then(response => response.json())
.then(result => {
  const line = result.quoteLineItems[0];
  console.log(`Total (with ramp): $${line.totalPrice}`);
  console.log('Attached tags:', line.priceTags);
  // The total reflects the blended price across all ramp periods
})
.catch(error => console.log('Error:', error));
```

```bash
curl -X POST 'https://api.nue.io/cpq/quotes:preview' \
  -H 'nue-api-key: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "opportunityId": "006xx000001abc123",
    "name": "Ramp Discount Schedule",
    "subscriptionStartDate": "2025-01-01",
    "subscriptionEndDate": "2026-01-01",
    "subscriptionTermDimension": "Month",
    "subscriptionTerm": 12,
    "products": [
      {
        "productSku": "PLATFORM_BASE",
        "uom": "User/Month",
        "quantity": 50,
        "priceTags": [{ "code": "RAMP_ONBOARDING_DISCOUNT" }]
      }
    ]
  }'
```

The pricing engine evaluates the ramp schedule against the subscription dates and calculates a blended total across all ramp periods. The line's `priceTags` echoes the ramp tag with its tier table; the blended result is in `systemDiscountAmount` and `totalPrice`.

## Tag Application Summary

| Scenario                        | Request Input                          | What Happens                                                   |
| ------------------------------- | -------------------------------------- | -------------------------------------------------------------- |
| Auto-attached tag only          | No `priceTags` array needed            | Catalog-configured tags are applied automatically              |
| Request-applied tag by code     | `priceTags: [{ code: "..." }]`         | Tag looked up by code and evaluated                            |
| Request-applied tag by ID       | `priceTags: [{ id: "..." }]`           | Tag looked up by record ID and evaluated                       |
| Auto-attached + request-applied | `priceTags` array with additional tags | Both are evaluated; combined result                            |
| Price + discount tags together  | Multiple entries in `priceTags`        | Price tag resolves unit price first, then discount tag reduces |
| Different tags per line         | Each product has its own `priceTags`   | Tags evaluated independently per line                          |
| Ramp tag                        | `priceTags: [{ code: "RAMP_..." }]`    | Time-based tiers evaluated against subscription dates          |

## Price Tag Field Reference

| Field              | Type   | Location           | Description                                                                                                                                             |
| ------------------ | ------ | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `priceTags`        | array  | Product input      | Array of PriceTagInput objects                                                                                                                          |
| `priceTags[].code` | string | PriceTagInput      | Tag code from the catalog (use code OR id)                                                                                                              |
| `priceTags[].id`   | string | PriceTagInput      | Tag record ID (use code OR id)                                                                                                                          |
| `priceTags`        | array  | Response line item | Tag definitions attached to this line, each with its `priceTiers`. Does not report which tier resolved -- see `systemDiscount` / `systemDiscountAmount` |

## Next Steps

- [Discounts](docId\:Y9AwhgT5IYIBlYMwVE6nX) -- Apply header, parent, and line-level discretionary discounts
- [Subscription Terms](docId\:Wwo0BZASGS6MDCUE_G_Kl) -- Configure term lengths, billing periods, and renewal settings
- [Bundles](docId\:fri8QGGG2M1jVPi-Qlnvi) -- Work with bundle products and add-ons
- [Create Quote Overview](docId\:BC-IdxYnwAUS7O9EFYCwq) -- Return to the full API reference