---
title: Price Tag Data Reference
slug: price-tag-data-reference
createdAt: 2026-02-13T04:24:49.103Z
---

This comprehensive reference covers all price tag-related data structures, field definitions, pricing behaviors, and validation rules in the Nue Self-Service API.

## Core Price Tag Object

The Price Tag object represents a pricing rule that can modify base product prices through discounts, volume pricing, or promotional campaigns.

## Price Tag Fields Reference

### Identification Fields

| Field         | Type   | Description                                                       | Example                                   |
| ------------- | ------ | ----------------------------------------------------------------- | ----------------------------------------- |
| `id`          | String | Unique price tag identifier (Salesforce Price Tag ID)             | `"a0X7z000007CCkXEAW"`                    |
| `name`        | String | Display name for the price tag                                    | `"Enterprise Volume Discount"`            |
| `code`        | String | Unique code for API references and fetching individual price tags | `"ENTERPRISE_VOLUME"`                     |
| `description` | String | Detailed explanation of the pricing rule                          | `"30% discount for enterprise customers"` |

### Status and Publication

| Field               | Type              | Description                               | Example                  |
| ------------------- | ----------------- | ----------------------------------------- | ------------------------ |
| `active`            | Boolean           | Whether the price tag is currently active | `true`                   |
| `lastPublishedById` | String            | ID of user who last published             | `"005xx000001Sv6YAAS"`   |
| `lastPublishedDate` | String (ISO 8601) | Date of last publication                  | `"2025-01-15T10:30:00Z"` |

### Pricing Configuration

| Field          | Type   | Description               | Example                          |
| -------------- | ------ | ------------------------- | -------------------------------- |
| `priceTagType` | String | Type of pricing rule      | `"Quantity"`, `"Term"`           |
| `priceType`    | String | Pricing model             | `"Volume"`, `"Tiered"`, `"Ramp"` |
| `uomDimension` | String | Unit of measure dimension | `"User"`, `"License"`, `"GB"`    |
| `recordType`   | String | Type of record            | `"DiscountDimension"`            |

### Time-Based Controls

| Field       | Type              | Description                     | Example                  |
| ----------- | ----------------- | ------------------------------- | ------------------------ |
| `startTime` | String (ISO 8601) | When pricing becomes effective  | `"2025-01-01T00:00:00Z"` |
| `endTime`   | String (ISO 8601) | When pricing expires (optional) | `"2025-12-31T23:59:59Z"` |

## Price Tiers Object

Price tiers define the specific pricing rules within a price tag, including quantity ranges, discount percentages, and charge models.

## Price Tier Fields Reference

### Core Tier Fields

| Field         | Type   | Description                | Example                  |
| ------------- | ------ | -------------------------- | ------------------------ |
| `id`          | String | Unique tier identifier     | `"a0Yxx000001TdGrEAK"`   |
| `name`        | String | Tier name                  | `"Tier 1: 1-10 Users"`   |
| `tierNumber`  | Number | Order of the tier          | `1`                      |
| `chargeModel` | String | How charges are calculated | `"PerUnit"`, `"FlatFee"` |

### Quantity Range

| Field                | Type   | Description                                  | Example  |
| -------------------- | ------ | -------------------------------------------- | -------- |
| `startUnit`          | Number | Lower bound of the tier range, **exclusive** | `0`      |
| `startUnitDimension` | String | Unit type for start range                    | `"User"` |
| `endUnit`            | Number | Upper bound of the tier range, **inclusive** | `10`     |
| `endUnitDimension`   | String | Unit type for end range                      | `"User"` |

A tier matches when `startUnit < quantity <= endUnit`. Consecutive tiers therefore share a boundary: set each tier's `startUnit` to the previous tier's `endUnit`, and start the first tier at `0` so that a quantity of 1 is covered. A quantity that falls outside every tier receives no adjustment from the tag, and no error is returned.

### Pricing Values

| Field                | Type   | Description                         | Example |
| -------------------- | ------ | ----------------------------------- | ------- |
| `discountPercentage` | Number | Percentage discount applied         | `15.0`  |
| `amount`             | Number | Fixed price amount (for price tags) | `85.00` |

## Price Tag Types and Behaviors

## Quantity-Based Price Tags

**Behavior**: Apply discounts or pricing based on the quantity of units purchased.

**Common Use Cases**:

- Volume discounts (buy more, save more)
- Bulk pricing tiers
- Enterprise quantity thresholds

**Example Structure**:

```json
{
  "id": "a0X7z000007CCkXEAW",
  "name": "Volume Discount - Platform Licenses",
  "code": "VOLUME_PLATFORM",
  "priceTagType": "Quantity",
  "priceType": "Volume",
  "uomDimension": "User",
  "active": true,
  "publishStatus": "Published",
  "priceTiers": [
    {
      "tierNumber": 1,
      "startUnit": 0,
      "endUnit": 10,
      "discountPercentage": 0.0,
      "chargeModel": "PerUnit"
    },
    {
      "tierNumber": 2,
      "startUnit": 10,
      "endUnit": 50,
      "discountPercentage": 10.0,
      "chargeModel": "PerUnit"
    },
    {
      "tierNumber": 3,
      "startUnit": 50,
      "endUnit": 1000,
      "discountPercentage": 20.0,
      "chargeModel": "PerUnit"
    }
  ]
}
```

## Term-Based Price Tags

**Behavior**: Apply discounts based on subscription term length.

**Common Use Cases**:

- Annual billing discounts
- Multi-year commitment rewards
- Subscription length incentives

**Example Structure**:

```json
{
  "id": "a0X7z000007DDlXEAW",
  "name": "Annual Subscription Discount",
  "code": "ANNUAL_DISCOUNT",
  "priceTagType": "Term",
  "priceType": "Volume",
  "uomDimension": "Month",
  "active": true,
  "publishStatus": "Published",
  "priceTiers": [
    {
      "tierNumber": 1,
      "startUnit": 1,
      "endUnit": 11,
      "discountPercentage": 0.0,
      "chargeModel": "PerUnit"
    },
    {
      "tierNumber": 2,
      "startUnit": 12,
      "endUnit": 23,
      "discountPercentage": 15.0,
      "chargeModel": "PerUnit"
    },
    {
      "tierNumber": 3,
      "startUnit": 24,
      "endUnit": 999,
      "discountPercentage": 25.0,
      "chargeModel": "PerUnit"
    }
  ]
}
```

## Pricing Models

## Volume Pricing

**Behavior**: All units in the order receive the same discount based on total quantity.

- Order 25 units, all 25 get the 10% discount
- Simple to understand and calculate
- Best for straightforward volume discounts

## Tiered Pricing

**Behavior**: Different portions of the order receive different pricing.

- First 10 units at full price
- Next 15 units at 10% discount
- Remaining units at 20% discount
- More complex but can provide better granular control

## Ramp Pricing

**Behavior**: Pricing changes over time within the subscription.

- Year 1: Full price
- Year 2: 10% discount
- Year 3+: 20% discount
- Useful for long-term commitment incentives

## Price Tag Application

### Automatic Application

Price tags are automatically applied when:

1. **Order meets quantity criteria** defined in the price tag tiers
2. **Subscription term matches** term-based price tag requirements
3. **Price tag is active and published**
4. **Current date falls within** the price tag's effective period
5. **No conflicting exclusions** are in place

### Manual Application

Price tags can be manually applied using:

**In Order Requests**:

```json
{
  "orderProducts": [
    {
      "priceBookEntryId": "01uEa000008IcdeIAC",
      "quantity": 25,
      "priceTagCodes": ["VOLUME_PLATFORM", "ANNUAL_DISCOUNT"]
    }
  ]
}
```

**In Change Orders**:

Price tags are not supported on change orders. `assetChanges` entries do not accept `priceTagIds` or `priceTagCodes`.

## Validation Rules

## Price Tag Validation

### Status Requirements

- `active` must be `true`
- `publishStatus` must be `"Published"`
- Current date must be within `startTime` and `endTime` range

### Tier Validation

- Tiers must have non-overlapping ranges
- `startUnit` must be less than or equal to `endUnit`
- Tier numbers should be sequential
- All tiers must have consistent `uomDimension`

### Pricing Validation

- `discountPercentage` must be between 0 and 100
- Either `discountPercentage` or `amount` should be specified, not both
- `chargeModel` must be valid ("PerUnit", "FlatFee")

## Integration Validation

### Order Integration

- Price tags must be compatible with product price book entries
- Quantity must fall within defined tier ranges
- Terms must match term-based price tag requirements

### Change Order Integration

- Price tags are not supported on change order asset changes (`assetChanges`)

## Error Handling

### Common Error Scenarios

| Error Type                 | Description                        | Resolution                                  |
| -------------------------- | ---------------------------------- | ------------------------------------------- |
| `PRICE_TAG_NOT_FOUND`      | Price tag ID or code not found     | Verify price tag exists and is published    |
| `PRICE_TAG_INACTIVE`       | Price tag is not active            | Check price tag status                      |
| `PRICE_TAG_EXPIRED`        | Price tag outside valid date range | Check startTime and endTime                 |
| `TIER_NOT_APPLICABLE`      | Quantity doesn't match any tier    | Verify quantity falls within defined ranges |
| `INCOMPATIBLE_COMBINATION` | Conflicting price tags applied     | Review price tag compatibility rules        |

### Error Response Format

```json
{
  "status": "FAILURE",
  "errorType": "VALIDATION_ERROR",
  "errorCode": "PRICE_TAG_NOT_FOUND",
  "message": "Price tag with code 'INVALID_CODE' not found or not published",
  "details": {
    "field": "priceTagCode",
    "value": "INVALID_CODE",
    "allowedValues": ["VOLUME_PLATFORM", "ANNUAL_DISCOUNT"]
  }
}
```

## API Endpoints

### Price Tag Retrieval

| Endpoint                     | Method | Purpose                             |
| ---------------------------- | ------ | ----------------------------------- |
| `/catalog/price-tags`        | GET    | Retrieve all published price tags   |
| `/catalog/price-tags/{code}` | GET    | Retrieve specific price tag by code |

## Query Parameters

### GET /catalog/price-tags

Retrieve all published price tags. No parameters required.

### GET /catalog/price-tags/\{ code }

Retrieve a specific price tag by its code. The code is specified in the URL path.

### Response Structure

```json
[
  {
    "id": "a0X7z000007CCkXEAW",
    "name": "Enterprise Volume Discount",
    "code": "ENTERPRISE_VOLUME",
    "description": "Volume discount for enterprise customers",
    "active": true,
    "publishStatus": "Published",
    "priceTagType": "Quantity",
    "priceType": "Volume",
    "uomDimension": "User",
    "startTime": "2025-01-01T00:00:00Z",
    "endTime": null,
    "lastPublishedById": "005xx000001Sv6YAAS",
    "lastPublishedDate": "2025-01-15T10:30:00Z",
    "recordType": "DiscountDimension",
    "priceTiers": [
      {
        "id": "a0Yxx000001TdGrEAK",
        "name": "Tier 1",
        "tierNumber": 1,
        "startUnit": 1,
        "endUnit": 9,
        "startUnitDimension": "User",
        "endUnitDimension": "User",
        "discountPercentage": 0.0,
        "chargeModel": "PerUnit"
      }
    ]
  }
]
```

## Best Practices

### Price Tag Design

1. **Clear Naming**: Use descriptive names that explain the discount purpose
2. **Logical Codes**: Create memorable, consistent codes for API integration
3. **Non-Overlapping Tiers**: Ensure tier ranges don't overlap to avoid conflicts
4. **Reasonable Discounts**: Set appropriate discount percentages for business goals

### Implementation Patterns

1. **Cache Price Tags**: Price tags change infrequently, implement caching
2. **Validate Before Application**: Check price tag validity before using in orders
3. **Handle Gracefully**: Implement fallbacks when price tags are unavailable
4. **Monitor Performance**: Track price tag application impact on pricing

### User Experience

1. **Show Savings**: Display discount amounts prominently to customers
2. **Explain Tiers**: Help customers understand quantity thresholds
3. **Time Sensitivity**: Clearly communicate promotional expiration dates
4. **Progressive Disclosure**: Show relevant price tags based on context

This comprehensive reference provides the foundation for implementing effective price tag management with the Nue Self-Service API. For specific implementation examples, see the Getting Started guide and Advanced Implementation patterns.
