---
title: "Implementing price overrides in Associate App"
slug: "newstore-price-override-integration-guide"
updated: 2026-05-05T19:07:31Z
published: 2026-05-05T19:07:31Z
canonical: "docs.newstore.com/newstore-price-override-integration-guide"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.newstore.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Implementing price overrides in Associate App

Price overrides allow store associates to [change the price of an individual item at checkout](/v1/docs/checking-out-a-cart#price-override-app) — higher or lower than the catalog price. Typical use cases include:

- Correcting a promotion not applying correctly in the app
- Handling incorrect pricebook data
- Managing exchanges with already-applied promotions

---

## Configuration and setup

### Enabling price overrides

Configure these properties in `cart_management_v2` via the Associate App Config API. See [Manual Discounts](/v1/docs/manual-discounts).

| Property | Description |
| --- | --- |
| `orderDiscount` | Enables order-level manual discount |
| `itemDiscount` | Enables item-level manual discount |
| `priceOverride` | Enables item-level price override |

### Excluding products from price overrides

To prevent specific products from being overridden, set the `price_override_exclusion_list` via the [Checkout Configuration API](https://docs.newstore.net/api/configuration/checkout/checkout_admin). This exclusion applies across all stores, catalogs, and pricebooks.

### Configuring reason codes

Predefined reason codes can be set up so associates select a reason rather than entering free-form text. If no reason codes are configured, a free-text field (max 256 characters) is displayed instead.

- **Create:** Use the create reason code method, specifying `code` and `name` (for example, `dmgd` / `Damaged`).
- **Update:** Use the Update reason code method.
- **Delete:** Use the Delete reason codes method.

> [!TIP]
> Note
> 
> Ensure the `Accept-Language` header matches the locale set for the store. To display a free-text field instead, do not create a reason code for the store's locale.

### Printing receipt templates

To print the correct overridden price on receipts, pull from the `price_net` field rather than `price_catalog` for items with price overrides applied. Apply this consistently across sales, exchange, and return receipt templates.

---

## Using price overrides

1. Tap the item, then tap **Price override**.
2. Select a predefined reason code (or enter free-form text if no codes are configured).
3. Enter the new price and tap **Apply**.
4. To remove the price override, tap the item, then tap **Remove discount**.

### **Limitations**

- A manual discount must be removed before applying a price override, and vice versa.
- Cart-level discounts can still be applied, but items with a price override are not affected by them.
- The override does not change the catalog price — if the same item is added again, you must reapply the override.

---

## ERP integration via the Event Stream

### Triggering an event

When an in-store or endless aisle order is completed (including orders with price overrides), NewStore emits the `order.opened` event via the [Event Stream](https://docs.newstore.net/api/webhooks/stream_webhook_sink_hook/).

### Relevant payload fields

| Field | Description |
| --- | --- |
| `pricebook_price` | Original catalog price |
| `list_price` | Listed price |
| `overridden_price` | Price set by the associate override |
| `override_reason` | Reason provided for the override |
| `item_discounts` | Item-level discount amount |
| `order_discounts` | Order-level discount amount |

### Integrating with the Event Stream

1. Subscribe to the `order.opened` event via the Event Stream.
2. Fetch additional details (for example, payment data) via the GraphQL API, as payments are processed asynchronously.
3. Create the sales transaction in the ERP using item pricing data, referencing `overridden_price` where applicable.

### Sample GraphQL query

```graphql
query MyQuery {
  order(id: "012345Ab-CdEf-GhIj-KlMn-OpQrStUvWxYz", tenant: "dodici") {
    externalId
    placedAt
    demandLocationId
    currency
    isExchange
    isHistorical
    channel
    channelType
    shippingTax
    shippingTotal
    taxExempt
    taxStrategy
    taxTotal
    subtotal
    grandTotal
    discounts {
      edges {
        node {
          couponCode
        }
      }
    }
    paymentAccount {
      instruments {
        edges {
          node {
            paymentMethod
            paymentOrigin
            paymentProvider
            paymentAccountTransactions {
              edges {
                node {
                  amount
                  currency
                  transactionType
                }
              }
            }
          }
        }
      }
    }
    items {
      edges {
        node {
          productId
          quantity
          pricebookPrice
          itemDiscounts
          orderDiscounts
          tax
          shippingServiceLevel
          fulfillmentLocationId
        }
      }
    }
  }
}
```

See these guides for more information:

- [ERP integration playbook to sync in-store purchases](/v1/docs/erp-integration-playbook-to-sync-in-store-purchases)
- [ERP integration playbook to sync endless-aisle orders](/v1/docs/erp-integration-playbook-to-sync-endless-aisle-orders)

---

## Exception handling

| Scenario | Recommended Handling |
| --- | --- |
| ERP unavailable | Return `500`; the Event Stream automatically retries the event |
| Payment details unavailable | Return `200` and move the event to an internal queue (for example, SQS) for reprocessing later |

## Data extraction best practices

- Use REST APIs as the primary data source — they are the source of truth with no processing delay.
- Use GraphQL to supplement event data with additional context (for example, payment details), but do not use it as a source of truth or for bulk historical queries.
- Use the Event Stream to trigger downstream workflows in real time. See the [Data reconciliation and completeness playbook](/v1/docs/data-reconciliation-and-completeness-playbook).