Skip to main content

Custom Cart Completion

Updated over a month ago

This article explains how to:

  • Set cart context (cartId, cartSize, cartValue) at render time (HTML attributes)

  • Update cart context dynamically (DOM events)

  • Mark a cart as completed (backend endpoint)

What we track (analytics)

Every plugin analytics call includes these cart fields when available:

  • cartId (cart token / cart identifier)

  • cartSize (number of items)

  • cartValue (cart total in major currency units, e.g. 129.95)

If you provide these values, they will be persisted and used in reporting/funnel analytics.

1) Render the plugin

The Contribe plugin is a Web Component.

Example:

<contribe-plugin plugin-id="YOUR_PLUGIN_ID">
</contribe-plugin>

Supported attributes (most common)

  • plugin-id (required) — your plugin identifier

  • locale (optional) — forces locale (e.g. en, da)

Cart attributes (optional)

You can set cart properties directly on the element at render time:

<contribe-plugin   
plugin-id="YOUR_PLUGIN_ID"   
cart-id="abc123"   
cart-size="3"   
cart-value="129.95">
</contribe-plugin>

Notes:

  • cart-size and cart-value are numbers.

  • cart-value must be in major currency units (e.g. 129.95, not cents).

2) Set/update cart properties via events (custom shops)

If you have a custom shop setup (not Shopify/WooCommerce), you can set or update cart data at any time by dispatching a DOM event.

Event: contribe-cart-update

Dispatch a CustomEvent on document:

document.dispatchEvent(new CustomEvent("contribe-cart-update", {        detail: {       
  cartId: "abc123",       
  cartSize: 3,       
  cartValue: 129.95,     
},   
}));

Behavior:

  • The plugin will store the values internally.

  • Subsequent analytics calls will include these values.

Debug: listen to plugin analytics events

The plugin emits a DOM event for every analytics ping:

  • Event name: contribe-event

  • event.detail contains the full payload (including cart fields)

Example:

document.addEventListener("contribe-event", (e) => {   console.log("Contribe analytics payload:", e.detail); });

3) Mark cart as completed (custom checkout / order confirmation)

If your checkout is custom (or you cannot sync orders automatically), you can explicitly mark a cart token as completed.

Endpoint

POST /plugins/v1/:pluginId/cart/complete

Request body (JSON)

Required:

  • cartId (string)

Optional:

  • cartSize (number)

  • cartValue (number, major currency units)

  • currency (string, e.g. USD, EUR)

  • order (string, your order reference)

  • completedAt (ISO 8601 datetime string)

Example:

curl -X POST \   "https://YOUR_API_BASE_URL/plugins/v1/YOUR_PLUGIN_ID/cart/complete" \   -H "Content-Type: application/json" \   -d '{     "cartId": "abc123",     "cartSize": 3,     "cartValue": 129.95,     "currency": "EUR",     "order": "ORDER-100045",     "completedAt": "2025-12-19T10:20:30.000Z"   }'
Did this answer your question?