---
title: 'shopify:cart:discount-update'
description: Fires when a buyer applies or removes discount codes.
source_url:
  html: >-
    https://shopify.dev/docs/api/storefront-events-and-actions/events/cart-discount-update
  md: >-
    https://shopify.dev/docs/api/storefront-events-and-actions/events/cart-discount-update.md
api_name: storefront-events-and-actions
---

# shopify:cart:discount-update

Fires when a buyer applies or removes a discount code.

You can use this to see which codes buyers try, or to react when a code your app owns is applied.

`discountCodes` is the complete set the cart should end up with, not a delta, so send every code the buyer should have and send an empty array to clear them all. The resolved cart reports which of them the cart accepted.

You dispatch it from the discount form, when the buyer submits and before the result is known. A code the cart won't apply still resolves the promise, and the matching `discountCodes` entry comes back with `applicable: false`. A failed request rejects the promise and dispatches [`shopify:cart:error`](https://shopify.dev/docs/api/storefront-events-and-actions/events/cart-error).

#### Properties

* **discount​Codes**

  **DiscountCode\[]**

  **required**

  The full set of codes the cart should end up with. This replaces the existing codes rather than adding to them, so send an empty array to clear them all.

* **promise**

  **Promise\<CartDiscountUpdateResult>**

  **required**

  Resolves with a `CartDiscountUpdateResult` when the update finishes. It rejects if the request fails or is aborted.

* **detail**

  **Record\<string, unknown>**

  Optional custom data for the storefront's internal use. Listeners can read it.

### DiscountCode

A discount code applied to the cart.

* code

  The code as the buyer typed it, such as \`SPRING20\`.

  ```ts
  string
  ```

### CartDiscountUpdateResult

The value a \`shopify:cart:discount-update\` promise resolves with.

* cart

  The cart after the codes were applied. Check \`discountCodes\[].applicable\` to see which ones the cart accepted.

  ```ts
  StandardEventCart | null
  ```

* userErrors

  Validation errors from the mutation.

  ```ts
  CartMutationUserError[]
  ```

* warnings

  Non-blocking warnings from the mutation.

  ```ts
  CartMutationWarning[]
  ```

* detail

  Optional custom data for the storefront's internal use. Listeners can read it.

  ```ts
  Record<string, unknown>
  ```

### StandardEventCart

A subset of the \[Storefront API Cart object]\(/docs/api/storefront/latest/objects/Cart) that cart events carry.

* id

  The cart GID.

  ```ts
  string
  ```

* totalQuantity

  The total number of items in the cart.

  ```ts
  number
  ```

* cost

  The total cost of the cart.

  ```ts
  StandardEventCartCost
  ```

* lines

  The lines in the cart.

  ```ts
  StandardEventCartLine[]
  ```

* discountCodes

  The discount codes on the cart.

  ```ts
  StandardEventCartDiscountCode[]
  ```

### StandardEventCartCost

The cost of a cart or a cart line.

* totalAmount

  The total amount.

  ```ts
  MoneyV2
  ```

### MoneyV2

An amount with its currency, matching the Storefront API \[\`MoneyV2\`]\(/docs/api/storefront/latest/objects/MoneyV2) format.

* amount

  A decimal money amount, such as \`29.99\`.

  ```ts
  string
  ```

* currencyCode

  The three-letter currency code, such as \`USD\`.

  ```ts
  string
  ```

### StandardEventCartLine

A single line in the cart.

* id

  The cart line ID. A storefront on the AJAX cart API passes its own line keys through, so don't assume a GID.

  ```ts
  string
  ```

* quantity

  The quantity of merchandise on the line.

  ```ts
  number
  ```

* cost

  The cost of the line.

  ```ts
  StandardEventCartCost
  ```

### StandardEventCartDiscountCode

A discount code on the cart.

* code

  The discount code the buyer entered.

  ```ts
  string
  ```

* applicable

  Whether the discount code applies to the cart.

  ```ts
  boolean
  ```

### CartMutationUserError

A validation error returned by a cart mutation.

* code

  A machine-readable error code, such as \`INVALID\` for a malformed input or \`MAXIMUM\_EXCEEDED\` for a quantity above the item's maximum. See \[\`CartErrorCode\`]\(/docs/api/storefront/latest/enums/CartErrorCode) for the full list.

  ```ts
  string
  ```

* field

  The path to the field that caused the error.

  ```ts
  string[]
  ```

* message

  A human-readable message.

  ```ts
  string
  ```

### CartMutationWarning

A non-blocking warning returned by a cart mutation.

* code

  A machine-readable warning code, such as \`MERCHANDISE\_OUT\_OF\_STOCK\` for a line whose merchandise ran out or \`MERCHANDISE\_NOT\_ENOUGH\_STOCK\` when only part of the requested quantity is available. See \[\`CartWarningCode\`]\(/docs/api/storefront/latest/enums/CartWarningCode) for the full list.

  ```ts
  string
  ```

* message

  A human-readable message.

  ```ts
  string
  ```

* target

  The cart line or field the warning applies to.

  ```ts
  string
  ```

Examples

### Examples

* ####

  ##### Dispatch the event

  ```javascript
  import { CartDiscountUpdateEvent } from '@shopify/standard-events';

  const deferred = CartDiscountUpdateEvent.createPromise();

  element.dispatchEvent(
    new CartDiscountUpdateEvent({
      discountCodes: [{ code: 'SPRING20' }],
      promise: deferred.promise,
    }),
  );

  const ajaxCart = await applyDiscounts(['SPRING20']);

  deferred.resolve({
    cart: CartDiscountUpdateEvent.createCartFromAjaxResponse(ajaxCart),
  });
  ```

* ####

  ##### Listen for the event

  ```javascript
  document.addEventListener('shopify:cart:discount-update', (event) => {
    event.promise.then(({ cart }) => {
      const rejected = cart?.discountCodes.filter((code) => !code.applicable);

      if (rejected?.length) {
        showMessage(`${rejected[0].code} isn't valid for this cart.`);
      }
    });
  });
  ```

***