Influencer Promo Code Support

info

This feature is available exclusively to GWB partners and requires Beam SDK version 1.50.2 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)

Considerations for URL formats

When uploading URLs to Beam's Partner Portal for inclusion in an Influencer Boost, you'll want to make sure that the URL's query string is valid. A valid URL query parameter string generally follows this structure:

1. It starts with a question mark (?): The query string is appended to the main URL path and is introduced by a question mark. This separator is not part of the query string itself.
2. Key-value pairs: The query string consists of one or more "parameters" each represented by a key-value pair.

• Key and Value Separation: Within each pair, the parameter's name (key) and its assigned data (value) are separated by an equals sign (=).
  • Example: utm_campaign=summerlaunch
• Parameter Separation: When multiple parameters are present, they are separated by an ampersand (&).
  • Example: utm_campaign=summerlaunch&utm_source=instagram

Example of a valid URL query parameter string:

https://mysite.com/landing?utm_campaign=summerlaunch&utm_source=instagram&utm_medium=social

In this example:

• ? marks the beginning of the query string.
• utm_campaign=summerlaunch is the first parameter, with utm_campaign as the key and summerlaunch as the value.
• & separates the first and second parameters.
• utm_source=instagram is the second parameter.
• & separates the second and third parameters.
• utm_medium=social is the third parameter.

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()]
});

Shopify Discount Cookie Handling

To support promo codes applied before cart creation, Beam checks Shopify's discount_code cookie as a fallback source when enabled.

Configuration:

new PromoManagerPlugin({
  disableDiscountCodeCookieCheck: false, // Default
});

Value	Use Case
false (default)	Enables automatic discount code cookie checking
true	Disables automatic discount code cookie checking

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 }}" ...>
    </beam-post-purchase></beam-select-nonprofit
></beam-product-details-page>

---

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;
  }>;
}