Influencer Promo Code Support

info

This feature is available exclusively to GWB partners and requires Beam SDK version 1.49.0 or later

Beam now supports influencer-driven promotions through both manual entry and UTM-based promo codes.

Supported Promo Code Types

Type	Use Case
Manual Promo Codes	Manually entered by customers in the cart or at checkout (e.g. INFLUENCER20)
UTM-Based Promo Codes	Promo codes can also be captured automatically from UTM parameters appended to the URL (e.g. ?utm_campaign=summerlaunch)

Integration Steps

1. UTM-Based Promo Code Support

Step 1: Enable PromoManagerPlugin

Import the PromoManagerPlugin when initializing the Beam SDK to enable automatic UTM detection:

import { init } from "http://sdk.beamimpact.com/web-sdk/{{ settings.beam_sdk_version }}/dist/integrations/beam.js";
import { PromoManagerPlugin } from "http://sdk.beamimpact.com/web-sdk/{{ settings.beam_sdk_version }}/dist/integrations/promoManager.js";

const beam = await init({
  apiKey: "{{ settings.beam_api_key }}",
  chainId: {{ settings.beam_chain_id }},
  storeId: {{ settings.beam_store_id }},
  domain: "{{ settings.beam_store_domain }}",
  baseUrl: "{{ settings.beam_base_url }}",
  plugins: [new PromoManagerPlugin()]
});

Step 2: Add domain attribute to storefront components

Ensure the following Beam storefront components include the domain attribute to allow for promo detection:

<beam-product-details-page domain="{{ settings.beam_store_domain }}" ... >
<beam-select-nonprofit domain="{{ settings.beam_store_domain }}" ... >
<beam-post-purchase domain="{{ settings.beam_store_domain }}" ... >

---

2. Manual Promo Code Support

Manual promo codes are discount codes entered directly by customers (e.g., in a text input field or at checkout). Unlike UTM-based codes (which are auto-extracted from URLs), these require explicit user action.

Pass Promo Codes to Storefront Components (Optional)

Optional

• Optionally pass promo codes manually to Beam storefront components using the promoCodes attribute.
• If Beam cart tracking is enabled, promo codes entered by the user will automatically be read from the cart.

Supported storefront components:

• <beam-product-details-page>

• <beam-select-nonprofit>

Example:

<beam-select-nonprofit
  apiKey="{{ settings.beam_api_key }}"
  storeId="{{ settings.beam_store_id }}"
  lang="{{ beam_language }}"
  baseUrl="{{ settings.beam_base_url }}"
  domain="{{ settings.beam_store_domain }}"
  promoCodes='["CODE1", "INFLUENCER20"]'
></beam-select-nonprofit>

Attribute Type

The attribute value must be a JSON-stringified array of strings. That means you need to wrap the array in single quotes '...' and its contents in double quotes "...".

Events

BeamPromoCodesStoredEvent: Beam emits the BeamPromoCodesStoredEvent once promo codes have been processed and stored. The event contains the promo codes that have been processed and stored, including both unvalidated and validated promo codes.

Event payload structure:

/**
 * Fired when promo codes are processed and stored.
 *
 * @event BeamPromoCodesStoredEvent
 * @property {Array<UnvalidatedPromoCode>} unvalidatedPromoCodes - Raw promo codes before validation
 * @property {Array<ValidatedPromoCode>} validatedPromoCodes - Promo codes after validation
 */

{
  unvalidatedPromoCodes: Array<
    | {
        type: 'url';  // Source URL containing UTM parameters (e.g., `?utm_medium=social`)
        attributes: {
          url: string;
        };
      }
    | {
        type: 'manual';  // Code manually entered by the customer (e.g., "FREESHIP")
        attributes: {
          value: string;
        };
      }
  >;
  validatedPromoCodes: Array<{
    promoCodeId: string;
    validatedAt: string; // ISO timestamp
    apply: boolean;
  }>;
}