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

# getCartEarningValue

> Get the total points or store credit value the customer's current cart would earn.

Calculate what the current cart is worth in loyalty value. The SDK reads the cart from your storefront (via Shopify's `/cart.js`) and asks the Mage server to calculate the result, so the number always matches what the customer will actually earn at checkout. The calculation includes VIP tier multipliers, active bonus campaigns, discount exclusions from your purchase earning rule, and multi currency conversion.

Works for both guests and logged in customers. Guests see the base earning rate; logged in customers see their personalised rate, including any VIP tier boost.

A common use is a cart badge: "Earn 1,250 points with this order".

## Usage

```javascript theme={null}
MageSDK.getCartEarningValue().then(function(resp) {
  if (resp.success) {
    console.log(resp.data.formatted); // "1,250" or "$12.50"
  }
});
```

### Example: cart badge

Call the method whenever your cart UI renders or updates, and drop `formatted` into your badge. Results are cached, so repeat calls for an unchanged cart are instant.

**Points mode:**

```javascript theme={null}
async function updateCartBadge() {
  const resp = await MageSDK.getCartEarningValue();
  if (!resp.success) return;

  const badge = document.querySelector('#loyalty-cart-badge');
  if (badge) {
    // formatted is "1,250"
    badge.textContent = `Earn ${resp.data.formatted} points with this order`;
  }
}

updateCartBadge();
```

**Store credit mode:**

```javascript theme={null}
async function updateCartBadge() {
  const resp = await MageSDK.getCartEarningValue();
  if (!resp.success) return;

  const badge = document.querySelector('#loyalty-cart-badge');
  if (badge) {
    // formatted is "$12.50"
    badge.textContent = `Earn ${resp.data.formatted} in store credit with this order`;
  }
}

updateCartBadge();
```

If you are unsure which mode a shop runs in, or you are building for both, check `resp.data.loyaltyMode` (`"points"` or `"store_credit"`) and pick the wording accordingly.

### Keeping the badge in sync

Run `updateCartBadge()` on page load, then again whenever the cart changes. How you detect cart changes depends on your theme and any cart apps you use, as there is no single event every Shopify storefront fires:

* Many themes dispatch a custom event after AJAX cart updates, commonly `cart:updated`, `cart:refresh`, or `ajaxProduct:added`. Check your theme's JavaScript for the event name it uses, then listen for it: `document.addEventListener('cart:updated', updateCartBadge)`.
* Cart drawer and upsell apps often re-render the cart themselves and may expose their own events or callbacks. Check the app's documentation.
* If your theme re-renders the cart section with the Section Rendering API, call `updateCartBadge()` from the same code that triggers the re-render.
* On a standard `/cart` page without AJAX updates, quantity changes reload the page, so running on page load is enough.

## Response

<ResponseField name="success" type="boolean">
  Whether the request was successful.
</ResponseField>

<ResponseField name="data.points" type="number">
  The total value the cart would earn, in the shop's loyalty unit. In points mode this is the number of points. In store credit mode this is the credit amount in minor units (for example `1250` is \$12.50). See [Loyalty modes](/js-sdk/loyalty-modes).
</ResponseField>

<ResponseField name="data.formatted" type="string">
  Display ready version of `points`, formatted in the shopper's locale. `"1,250"` in points mode, `"$12.50"` in store credit mode. In most cases this is the only field you need to render.
</ResponseField>

<ResponseField name="data.loyaltyMode" type="string">
  `"points"` or `"store_credit"`. Use it to choose the wording around the value, for example "points" versus "in store credit".
</ResponseField>

<ResponseField name="error" type="string">
  Error message when `success` is `false`.
</ResponseField>

## Notes

* Store credit is always earned in the shop's own currency. If a shopper browses your store in a different currency, the cart is converted before calculating, and `formatted` shows the shop currency value they will actually receive.
* An empty cart returns `points: 0`. If the shop has no active purchase earning rule, the value is also `0`; you may want to hide the badge in that case.
* The value is a preview. The actual award happens when the order is paid, using the same calculation.