Skip to main content
Version: v1

Cart Tracking

See Cart Setup for an easier cart tracking installation.

If you already implemented the cart setup in the Web Storefront Components Guide, you do not need to implement the APIs in this file. This API is for those not using that script only.

It is recommended to add the following API request and localStorage updates in an event listener when the user’s cart is updated. This will ensure that Beam’s Cart Completion Rate reporting is accurate within the Partner Portal.

Authorization​

The cart tracking endpoint takes the same SDK API key that is used in your web widgets.

Authorization: "Api-Key {{SDK API key received from Beam}}"

// This will look something similar to:
Authorization: "Api-Key abc123.xyz456"

Endpoint​

POST <https://api.beamimpact.com/api/v3/cart>

Body​

For non-Shopify platforms, the user’s cart can be tracked by making a POST to the Cart API with whatever unique identifier the site uses for the cart.

{
  "cartId": "ec619f1eda6985f6acb88b5ff60252ff", // String
  "beamCartId": "6a75f689-6009-ae0a-a017b967ebd4", // String
  "currencyCode": "USD",
  "itemCount": 2, // Int
  "storeId": {{ store_id }}, // Int
  "subtotal": 14.99 // Decimal
}

LocalStorage​

In addition to the POST request above, for the select-nonprofit and checkout widgets to pick up the cartId, the localStorage key beam_cart_key_{{api key received from Beam}} should be set to a JSON string: '{"cartId": "..."}'. It can also contain the subtotal, itemCount, and currencyCode.

window.localStorage.setItem("beam_cart_key_{{SDK API key received from Beam}}", '{"cartId": "...", "subtotal": 14.99, "itemCount": 2, "currencyCode": "USD"}');

Beam Cart Id​

Beam’s POST /api/v3/cart API endpoint returns a beamCartId parameter that is used for separately tracking your platform’s cart object, and the cart as seen by Beam. Your first call to this endpoint will likely not have a beamCartId, and one will be generated by the Beam system and returned in the endpoint response. Please save this value to localStorage or to a cookie, so that this value can be saved and provided in subsequent calls to this cart tracking endpoint.

Example​

<script type="module">
  import { updateCart } from "https://sdk.beamimpact.com/web-sdk/v1.30.1/dist/integrations/cart.esm.js";
// This is an example of cart tracking using Javascript to listen
// for a "cart:changed" event. This is for illustrative puporses, and may
// require modification to function correctly based on the site's existing
// cart management approach.
// In this example, the "cart" object being passed looks like
// { id: "1234", currencyCode: "USD", itemCount: 2, subtotal: 14.99 }
// Note that the API data includes "storeId" as a property, while localStorage
// does not use this property.
  window.addEventListener("cart:changed", function(cart) {
    const data = {
      cartId: cart.id,
      beamCartId: window.localStorage?.getItem("beam_cart_id"),
      currencyCode: cart.currencyCode,
      itemCount: cart.itemCount,
      subtotal: cart.subtotal,
    };

    const response = await updateCart({
      apiKey: "{{SDK API key received from Beam}}",
      storeId: {{ beam_store_id }},
      domain: "myshop.com"
    }, data);
    const beamCartInfo = await response.json();

    window.localStorage.setItem(
      "beam_cart_id",
      beamCartInfo?.beamCartId
    );
    window.localStorage.setItem("beam_cart_key_{{SDK API key received from Beam}}", JSON.stringify(cart));
    window.dispatchEvent(new CustomEvent("beamcartchange", {
      detail: data
    }));
  });
</script>