Skip to Content

ORBCART DOCUMENTATION

Track storefront events

Send cart and checkout events to Google Tag Manager or your own analytics receiver.

Attach a listener when you create OrbCart in the browser. The cart and checkout tell the listener what happened without waiting for analytics delivery.

import { createEvents } from "@orbcommerce/storefront-events";
import { createCommerce } from "@orbcart/client";
import { toDataLayer } from "@orbcart/client/ga4";

export const events = createEvents({ ga: toDataLayer() });
export const commerce = createCommerce({ url, key, events });

Use one event stream per page, not one per component or cart. With Google Tag Manager installed, configure tags for the GA4 events you want to send. The adapter only pushes to window.dataLayer; it does not load the Google tag or manage consent. The cart and checkout emit their facts through the SDK's cart.checkout() store. The React checkout reports its forms and steps automatically. The kit's <Cart> reports when it comes into view inside <CartProvider>; outside the provider, pass viewCart={bag.viewCart} from useCart. Pass tellInteraction={bag.tellInteraction} to standalone forms outside the provider if you want their rejection events. If you build a custom cart view, call checkout.viewCart?.(cart) once it has shown the cart.

Which events can I listen to?

EventWhat it meansGA4
cart.viewedThe storefront showed the cartview_cart
cart.line_addedAn addition was confirmedadd_to_cart
cart.line_removedA removal was confirmedremove_from_cart
cart.line_changedA quantity change was confirmed—
cart.code_entered, cart.gift_card_enteredA code was tried; only the result is reported—
checkout.startedCheckout opened with an open cartbegin_checkout
checkout.step_entered, checkout.step_completedThe kit showed a step or saved the regions it holds—
checkout.shipping_chosenThe runtime confirmed the chosen shipping methodadd_shipping_info
checkout.payment_chosenThe buyer chose an available payment method, or submitted the default oneadd_payment_info
checkout.refusedThe runtime refused a checkout operation—
checkout.order_requestedThe buyer submitted a quote for purchase—
checkout.payment_failedA payment failed or was canceled—
checkout.orderedA purchase the checkout followed produced an orderpurchase
product.viewedYour storefront showed a productview_item
product_list.viewedYour storefront showed a product listview_item_list
product.selectedYour storefront selected a product from a listselect_item
ui.pressed, ui.opened, ui.closed, ui.submittedA named button, disclosure, or form was used—
ui.rejectedThe kit or your storefront reported a form refusal—

A cart mutation that cannot be attributed to the current step from consecutive cart answers is omitted rather than guessed. Browser analytics is best effort: keep using signed order events for fulfillment, finance, or reconciliation.

Customize

Name an element or tell a product fact

Use stable names, not labels or translations. Buttons, native disclosures, and forms with data-part report interactions automatically. Ancestors with data-scope put the same part in different places without changing its name. Put a scope on your own cart drawer or modal to distinguish it from the same kit component on a page.

<section data-scope="product-page">
  <button data-part="size-guide">Size guide</button>
</section>

That button reports part: "size-guide" and path: ["product-page", "size-guide"]. If you open your own dialog, tell ui.opened yourself and pass { from: trigger } to read the path from the trigger. On a product page, tell the standard product fact once the page shows it. Product prices use decimal major units.

events.tell({
  type: "product.viewed",
  data: {
    reference: "PACK-30",
    title: "30 L Backpack",
    price: { value: 89.9, currency: "EUR" },
  },
});

A listener is either a function that takes an ordered batch or an object with run, types, and when. Leave out types for all events. Use a full event name or a prefix such as checkout.*.

import { createEvents, toEndpoint } from "@orbcommerce/storefront-events";

const events = createEvents({
  warehouse: {
    run: toEndpoint("https://collect.example.com/events"),
    types: ["cart.*", "checkout.*", "ui.rejected"],
    when: () => banner.allows("analytics"),
  },
});

// Call this whenever the banner answer changes.
banner.onChange(() => events.flush());

The SDK reads when when an event is told and again before delivery. Keep it a cheap, synchronous read of your banner state. Return true to send, false to drop, or undefined to hold in memory while the banner is unanswered. On page exit a final batch may start before an older request finishes. Deduplicate by event ID and use sequence rather than arrival order. A closed page loses its unsent events. A network listener should respect the delivery's abort signal; it is aborted after five seconds. Keep custom listeners asynchronous if they do expensive or slow work: synchronous code blocks the browser's main thread even when scheduled in the background.

Your collector receives a JSON array. An event has an id, type, time, sequence, and source; cart events also carry their cart ID as subject. Deduplicate retries by id. OrbCart sends no buyer-entered values or tokens; the GA4 coupon is the merchant's discount ID, never the entered code. You are responsible for values in your own events and listener mappings.

Rename GA4 events or map your own facts

Declare your own event names and payloads once, then pass the type to both the event stream and the adapter. The ui, product, product_list, cart, and checkout prefixes are reserved.

import { createEvents } from "@orbcommerce/storefront-events";
import { toDataLayer } from "@orbcart/client/ga4";

type ShopEvents = { "wishlist.added": { reference: string } };

const events = createEvents<ShopEvents>({
  ga: toDataLayer<ShopEvents>({
    names: { view_cart: "shop_cart_opened" },
    map: {
      "wishlist.added": ({ data }) => ({
        event: "add_to_wishlist",
        ecommerce: { items: [{ item_id: data.reference }] },
      }),
    },
  }),
});

events.tell({ type: "wishlist.added", data: { reference: "PACK-30" } });

Next steps

ReadWhen
Set up checkoutYou want to put the checkout on your storefront.
Receive signed order eventsYour backend needs a reliable record of financial events.

On this page