getCartEarningValue

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

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:

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:

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

boolean

Whether the request was successful.

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.

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.

string

"points" or "store_credit". Use it to choose the wording around the value, for example “points” versus “in store credit”.

string

Error message when success is false.

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.

JavaScript SDK

Methods

Usage

Example: cart badge

Keeping the badge in sync

Response

Notes

​Usage

​Example: cart badge

​Keeping the badge in sync

​Response

​Notes

Usage

Example: cart badge

Keeping the badge in sync

Response

Notes