API Reference

This reference documents the GrowSurf JavaScript SDK, including all available public methods and examples of each.

Using AI? Follow Build with AI.

Use this page to look up individual GrowSurf JavaScript SDK methods. All asynchronous methods support both callback and Promise styles unless otherwise noted.

SDK LIFECYCLE ↓

Initialize / Reinitialize GrowSurf

Initializes or reinitializes the window.growsurf Object.

The method is useful for the following use-cases:

If you have participant authentication enabled for your program and you would like to automatically authenticate your participants after they log in within your own user portal.
Load multiple programs on a single webpage depending on where the traffic is coming from. View a tutorial here.

growsurf.init(settings);

Example use

// Using a Callback
growsurf.init({ email: "participant@email.com", hash: "HASH_VALUE" }, () => {
    // GrowSurf is Ready
});

// Using a promise
growsurf.init({ email: "participant@email.com", hash: "HASH_VALUE" }).then(() => {
    // GrowSurf is Ready
});

Parameter

Data Type

Description

settings

Object

(Optional) The settings GrowSurf should use when initializing or reinitializing.

campaignId- Provide this to initialize another program
email- The email of the participant you wish to auto authenticate (only applies if authentication is enabled for your program).
hash- The hash token generated by your server. Used to auto authenticate a participant (only applies if authentication is enabled for your program).
language- The language code to show your program in, such as es (only applies if the language is turned on in Options > Languages). While it is set, participants cannot change their language on the page. Learn more.

Get participant ID

Returns the ID of the authenticated participant or null if there is no participant authentication cookie present.

Example: Someone signed up as a participant in your referral/affiliate program from your website. Calling this method will return aj7auu1 (which is the participant ID).

growsurf.getParticipantId();

Example use

growsurf.getParticipantId();

Example response

"aj7auu1"

Log out

Logs the participant out of the browser (clears the participant's GrowSurf browser cookie and local storage).

growsurf.logout();

Example use

growsurf.logout();

CAMPAIGNS ↓

Get campaign

Retrieves limited details of your program.

growsurf.getCampaign(callback);

Parameter

Data Type

Description

callback

Function

(Optional) A callback function that will be invoked with the program data.

Returns a Promise that resolves with an Objectcontaining limited program data of id and rewards.

Example use

// Using a Callback
growsurf.getCampaign((campaign) => {
    // Handle Campaign
    console.log(campaign);
});

// Using a Promise
growsurf.getCampaign().then(campaign =>  {
    // Handle Campaign
    console.log(campaign);
});

Example response

{
    "id": "bpsxg4",
    "type": "REFERRAL",
    "rewards": [
        {
            "id": "crew_xyz789",
            "type": "DOUBLE_SIDED",
            "description": "Refer a friend and get $20",
            "referralDescription": "Sign up and get $10 off your first invoice",
            "referredRewardUpfront": false,
            "isUnlimited": false,
            "limit": 1,
            "conversionsRequired": 1,
            "numberOfWinners": 3,
            "imageUrl": "https://piedpiper.com/reward-image.png",
            "metadata": {
                "rewardValueForReferrer": 20,
                "rewardValueForReferred": 10
            },

            // Only for affiliate programs:
            "commissionStructure": {
                "amount": null,
                "event": "SALE",
                "type": "PERCENT",
                "minPaidReferrals": 3,
                "holdDuration": 30,
                "duration": "FOREVER",
                "durationInMonths": 12,
                "approvalRequired": false,
                "percent": 50,
                "hasMaxAmount": false,
                "maxAmount": null,
                "maxAmountISO": "USD",
                "hasIntro": false,
                "introType": null,
                "introPercent": null,
                "introAmount": null,
                "introAmountISO": "USD",
                "introDuration": "REPEATING",
                "introDurationInMonths": 2
            }
        }
    ]
}

GROWSURF WINDOW ↓

Open GrowSurf window

Opens the GrowSurf window.

growsurf.open(callback);

Parameter

Data Type

Description

callback

Function

(Optional) A callback function that will be invoked once complete

Returns a Promise that resolves once complete.

Example use

// Using a Callback
growsurf.open(function() {
    // Do something here
});

// Using a Promise
growsurf.open().then(() => {
    // Do something here
});

CSS Alternative:

Instead of using the JavaScript method growsurf.open(), you can add a CSS class growsurf-open-window to a button.

A benefit of this option is that if the participant has any unread rewards, the unread badge will automatically show up as well. Here is an example:

<a class="growsurf-open-window">
  Refer and Earn
</a>

Note: You'll need to make sure you have the GrowSurf Universal Code installed.

Close GrowSurf window

Closes the GrowSurf window.

growsurf.close(callback);

Parameter

Data Type

Description

callback

Function

(Optional) A callback function that will be invoked once complete

Returns a Promise that resolves once complete.

Example use

// Using a Callback
growsurf.close(() => {
    // Do something here
});

// Using a Promise
growsurf.close().then(() => {
    // Do something here
});

REFERRERS ↓

Get referrer ID

Returns the ID of the participant that referred the visitor or null if the visitor was not referred. This method will first check to see if a grsf URL parameter exists, then will check for the presence of a referrer ID as a browser cookie (which was set from the initial visit).

Example: If someone refers their friend, and the friend visits https://yoursite.com?grsf=1h97da, calling this method will return 1h97da (which is the referrer ID).

growsurf.getReferrerId();

Example use

growsurf.getReferrerId();

Example response

"1h97da"

Note: You can verify that the referrer ID is valid by calling growsurf.validateReferrer().

Validate referrer

Checks whether a referrer (participant) exists in the program. Returns true if the referrer exists, false otherwise. Unlike getParticipantById(), this method needs no participant authentication and returns no participant data.

When to use this: Use validateReferrer() when you need to confirm that a referral link is valid or to check if a participant exists. If you want to add a referred signup only when the referrer is valid, use addReferredParticipant().

growsurf.validateReferrer(referrerId, callback);

Parameter

Data Type

Description

referrerId

String

(Optional) The GrowSurf referrer ID to validate. If omitted, the referrer ID is automatically resolved from the grsf URL parameter or browser cookie.

callback

Function

(Optional) A callback function that will be invoked with true if the referrer exists or false if the referrer does not exist.

Returns a Promise that resolves with a Boolean. Returns true if the referrer exists as a participant in the program, false otherwise.

Example use

// Using a Callback
// Without specifying a referrer ID (auto-detects referrer)
growsurf.validateReferrer(isValid => {
  if (isValid) {
    // Referrer exists
  }
});

// With a specific referrer ID
growsurf.validateReferrer('kafewp', (isValid) => {
  if (isValid) {
    // Referrer exists
  }
});

// Using a Promise
// Without specifying a participant ID (auto-detects referrer)
growsurf.validateReferrer().then(isValid => {
  if (isValid) {
    // Referrer exists
  }
});

// With a specific participant ID
growsurf.validateReferrer('kafewp').then(isValid => {
  if (isValid) {
    // Referrer exists
  }
});

Example response

true

PARTICIPANTS ↓

Add referred participant

Adds a participant only when the current visitor has a valid referrer. Use this method when you want to track referred signups.

GrowSurf uses signed visit receipts to apply the program’s first-click or last-click setting. If no usable receipt is available, it validates the explicit referredBy value or the referrer ID from the grsf URL parameter or browser cookie. If no valid referral can be verified, no participant is added (see notAddedReason).

Tips: Though they are optional, we recommend passing firstName and lastName. These fields show up in referred friend motivator elements, if enabled.

growsurf.addReferredParticipant(data, callback);

Parameter

Data Type

Description

data

String or Object

(Required) A String containing the participant email or an Object containing the participant email and any other data to include for the participant.

If providing an Object, referredBy is optional and replaces the automatically detected code. A verified visit receipt can take precedence according to the program’s attribution setting. Any Object keys other than email, firstName, lastName, referredBy, referredAt, and gdprAgreements will be treated as metadata by GrowSurf.

callback

Function

(Optional) A callback function that will be invoked with the result.

Returns a Promise that resolves with a result object.

Example use

growsurf.addReferredParticipant({
  email: 'gavin@hooli.com',
  firstName: 'Gavin',
  lastName: 'Belson'
}, (result) => {
  if (result.added) {
    // handle result.participant
  }
});

const result = await growsurf.addReferredParticipant({
  email: 'gavin@hooli.com',
  firstName: 'Gavin',
  lastName: 'Belson'
});

if (result.added) {
  // handle result.participant
}

Example response

{
    "added": true,
    "validReferral": true,
    "referredBy": "kafewp",
    "participant": {
        "id": "gavin",
        "firstName": "Gavin",
        "lastName": "Belson",
        "referralCount": 0,
        "monthlyReferralCount": 0,
        "shareUrl": "https://piedpiper.com?grsf=gavin-kafewp",
        "rewards": [],
        "vanityKeys": [
            "gavin-kafewp"
        ]
    }
}

If no participant is added, notAddedReason will be one of no_referrer, invalid_referrer, or participant_already_exists.

Add participant

Adds a participant to the referral/affiliate program. Use this method for the following use-cases:

Add every signup to your GrowSurf program. If a referral link was used, GrowSurf automatically submits the referrer ID behind the scenes.
Generate referral links for your signed-in users on the fly (or return existing data if they are an existing participant)

For referral-only signup tracking, use growsurf.addReferredParticipant() instead.

Tips: Though they are optional, we recommend passing firstName and lastName. These fields show up in referred friend motivator elements, if enabled.

Note: Returns 401 if the program uses participant authentication, the browser has no participant cookie, and the given email belongs to an existing participant.

growsurf.addParticipant(data, callback);

Parameter

Data Type

Description

data

String or Object

(Required) A String containing the participant email or an Object containing the participant email and any other data to include for the participant.

If providing an Object, any Object keys other than email, firstName, lastName , and gdprAgreements will be treated as metadata by GrowSurf. For more information about metadata please see our API Guidelines.

callback

Function

(Optional) A callback function that will be invoked with the added participant data if successful.

Returns a Promise that resolves with an Objectcontaining limited participant data.

Example use

// Email only using a Callback
growsurf.addParticipant('gavin@hooli.com', (participant) => {
  // handle participant
});

// Object using a Callback
growsurf.addParticipant({
  email: 'gavin@hooli.com',
  firstName: 'Gavin', // optional participant name
  lastName: 'Belson', // optional participant name
  company: 'Hooli, Inc', // Fields that are not email, firstName, or lastName will be saved as custom metadata
  companySize: 10000 // Fields that are not email, firstName, or lastName will be saved as custom metadata
}, (participant) => {
  // handle participant
});

// Email only using a Promise
growsurf.addParticipant('gavin@hooli.com').then(participant => {
  // handle participant
});

// Object using a Promise
growsurf.addParticipant({
  email: 'gavin@hooli.com',
  firstName: 'Gavin', // optional participant name
  lastName: 'Belson', // optional participant name
  company: 'Hooli, Inc', // Fields that are not email, firstName, or lastName will be saved as custom metadata
  companySize: 10000 // Fields that are not email, firstName, or lastName will be saved as custom metadata
}).then(participant => {
  // handle participant
});

Example response

{
    "id": "kafewp",
    "firstName": "Gavin",
    "lastName": "Belson",
    "referralCount": 0,
    "monthlyReferralCount": 0,
    "shareUrl": "https://piedpiper.com?grsf=gavin-kafewp",
    "rewards": [],
    "vanityKeys": [
        "gavin-kafewp"
    ]
}

Get participant by email

Retrieves limited details of an existing participant. You will need to supply the unique email of the participant.

Note: Returns 403 if the program uses participant authentication and the browser has no participant cookie.

growsurf.getParticipantByEmail(participantEmail, callback);

Parameter

Data Type

Description

participantEmail

String

(Required) The email of the participant to retrieve.

callback

Function

(Optional) A callback function that will be invoked with the participant data if successful or undefined if the participant does not exist.

Returns a Promise that resolves with an Objectcontaining the participant data. If the participant does not exist in the program, then undefined is returned.

Example use

// Using a callback
growsurf.getParticipantByEmail('gavin@hooli.com', (participant) => {
    // Handle participant data
});

// Using a promise
growsurf.getParticipantByEmail('gavin@hooli.com').then(participant => {
    // Handle participant data
});

Example response

{
    "id": "kafewp",
    "firstName": "Gavin",
    "lastName": "Belson",
    "referralCount": 0,
    "monthlyReferralCount": 0,
    "shareUrl": "https://piedpiper.com?grsf=gavin-kafewp",
    "rewards": [],
    "vanityKeys" [
        "gavin-kafewp"
    ]
}

Get participant by ID

Retrieves limited details of an existing participant. You will need to supply the GrowSurf unique identifier that was returned upon participant creation.

Note: Returns 403 if the program uses participant authentication and the browser has no participant cookie.

growsurf.getParticipantById(participantId, callback);

Parameter

Data Type

Description

participantId

String

(Required) The GrowSurf identifier of the participant to retrieve.

callback

Function

(Optional) A callback function that will be invoked with the participant data if successful or undefined if the participant does not exist.

Returns a Promise that resolves with an Objectcontaining the participant data. If the participant does not exist in the program, then undefined is returned.

Example use

// Using a Callback
growsurf.getParticipantById('kafewp', (participant) => {
    // Handle participant data
});

// Using a promise
growsurf.getParticipantById('kafewp').then(participant => {
    // Handle participant data
});

Example response

{
    "id": "kafewp",
    "firstName": "Gavin",
    "lastName": "Belson",
    "referralCount": 0,
    "monthlyReferralCount": 0,
    "shareUrl": "https://piedpiper.com?grsf=gavin-kafewp",
    "rewards": [],
    "vanityKeys" [
        "gavin-kafewp"
    ]
}

REFERRALS AND INVITES ↓

Updates the pre-populated social share message for the given share type (e.g, email, Facebook, Twitter). This method will update all social share buttons in GrowSurf embedded elements and the GrowSurf window.

Example: This method is useful for optimizing referral asks when your participants complete an "aha moment". You would present your participant with the GrowSurf Embedded Form element and then call this method to update social share message(s) to be specific to the "aha moment". See this tutorial for an example.

growsurf.updateSocialShareMessage(type, message, subjectLine);

Parameter

Data Type

Description

type

String

(Required) The social share type to update.

These are the options:

email
facebook
twitter
threads
bluesky
pinterest
sms
whatsapp
reddit
tumblr

message

String

(Required) The new pre-populated social share message.

Use {{shareUrl}} to reference the participant's referral link.

subjectLine

String

(Optional) The new pre-populated subject line (only applies when type is email).

Use {{shareUrl}} to reference the participant's referral link.

Example use

const message = "I have saved 1,540 hours using this service. Highly recommend! {{shareUrl}}";
const subjectLine = "Check this out!";

// Update the pre-populated email social share message
growsurf.updateSocialShareMessage('email', message, subjectLine);

// Update the pre-populated Facebook social share message
growsurf.updateSocialShareMessage('facebook', message);

// Update the pre-populated Twitter social share message
growsurf.updateSocialShareMessage('twitter', message);

// Update the pre-populated Threads social share message
growsurf.updateSocialShareMessage('threads', message);

// Update the pre-populated Bluesky social share message
growsurf.updateSocialShareMessage('bluesky', message);

// Update the pre-populated Pinterest social share message
growsurf.updateSocialShareMessage('pinterest', message);

// Update the pre-populated SMS social share message
growsurf.updateSocialShareMessage('sms', message);

// Update the pre-populated WhatsApp social share message
growsurf.updateSocialShareMessage('whatsapp', message);

// Update the pre-populated Reddit social share message
growsurf.updateSocialShareMessage('reddit', message);

// Update the pre-populated Tumblr social share message
growsurf.updateSocialShareMessage('tumblr', message);

Update email invite message

Updates the pre-populated email invite message. This method will only apply updates to GrowSurf Embedded Invite elements (the email invite section within the GrowSurf window will not be updated).

Example: This method is useful for optimizing referral asks when your participants complete an "aha moment". You would present your participant with the GrowSurf Embedded Invite element and then call this method to update the email invite message to be specific to the "aha moment". See this tutorial for an example.

growsurf.updateEmailInviteMessage(message, subjectLine);

Parameter

Data Type

Description

message

String

(Required) The new pre-populated email invite message.

Use {{shareUrl}} to reference the participant's referral link.

subjectLine

String

(Optional) The new pre-populated subject line.

Use {{shareUrl}} to reference the participant's referral link.

Example use

const message = "I have saved 1,540 hours using this service. Highly recommend! {{shareUrl}}";
const subjectLine = "Check this out!";

// Update the pre-populated email invite message and subject line
growsurf.updateEmailInviteMessage(message, subjectLine);

REFERRAL PROGRAMS ↓

Trigger referral

Referral programs only

Triggers a referral, awarding referral credit to the referrer of an existing or new participant. If the program participant does not exist, they will be newly added.

Note: Returns 401, but still triggers the referral, if the program uses participant authentication, the browser has no participant cookie, and the given email belongs to an existing participant.

growsurf.triggerReferral(data, callback);

Parameter

Data Type

Description

data

String or Object

(Optional) A String containing the participant email or an Object containing the participant email and any other data to include for the participant.

If providing an Object, any Object keys other than email, firstName, and lastName will be treated as metadata by GrowSurf.

*This parameter is only optional if the participant has already signed up for the program and GrowSurf is able to determine they are a participant (does not include participants imported or manually added using the dashboard). For more information about metadata please see our API Guidelines.

callback

Function

(Optional) A callback function that will be invoked with the added or updated participant data if successful.

Returns a Promise that resolves with an Objectcontaining limited participant data.

Example use

// Email only using a Callback
growsurf.triggerReferral('gavin@hooli.com', (participant) => {
  // handle participant
});

// Object using a Callback
growsurf.triggerReferral({
  email: 'gavin@hooli.com',
  firstName: 'Gavin', // optional participant name
  lastName: 'Belson', // optional participant name
  company: 'Hooli, Inc', // Fields that are not email, firstName, or lastName will be saved as custom metadata
  companySize: 10000 // Fields that are not email, firstName, or lastName will be saved as custom metadata
}, (participant) => {
  // handle participant
});

// Email only using a Promise
growsurf.triggerReferral('gavin@hooli.com').then(participant => {
  // handle participant
});

// Object using a Promise
growsurf.triggerReferral({
  email: 'gavin@hooli.com',
  firstName: 'Gavin',
  lastName: 'Belson',
  company: 'Hooli, Inc',
  companySize: 10000
}).then(participant => {
  // handle participant
});

Example response

{
    "id": "kafewp",
    "firstName": "Gavin",
    "lastName": "Belson",
    "referralCount": 0,
    "shareUrl": "https://piedpiper.com?grsf=gavin-kafewp",
    "rewards": [],
    "vanityKeys" [
        "gavin-kafewp"
    ]
}

Get upfront discount

Referral programs only

Use this method when you want to apply an upfront discount to a referred friend (e.g., "Get 20% off your first invoice").

Returns the upfront discount promotion code and coupon ID for the current referred visitor. Returns null if the visitor was not referred, if no upfront discount is enabled, or if the program has ended.

Note: The upfront discount must be enabled on a Double-Sided reward (via the "Give the referred friend their reward upfront instead of after they complete the qualifying action" toggle) and a coupon integration (Stripe, Chargebee, or Recurly) must be connected with referred friend coupon settings. The visitor must have been referred (i.e., arrived via a referral link) for a discount to be returned.

Parameter

Data Type

Description

integrationType

String

(Optional) One of 'stripe', 'chargebee', or 'recurly'. If omitted, returns the first available upfront discount across all integrations.

Returns an Object or null.

Example use

// Get the first available upfront discount
const discount = window.growsurf.getUpfrontDiscount();

// Get Stripe-specific upfront discount
const stripeDiscount = window.growsurf.getUpfrontDiscount('stripe');

// Get Chargebee-specific upfront discount
const chargebeeDiscount = window.growsurf.getUpfrontDiscount('chargebee');

if (discount) {
  // Apply the promotion code to your checkout flow
  applyDiscount(discount.promotionCode);
}

Example response

{
  integration: 'stripe',          // Which integration the discount is from
  promotionCode: 'GRSF-A1B2C3D4', // Customer-facing code
  couponId: 'coupon_abc123'       // Provider coupon ID
}

Get referral summary

Referral programs only

Returns referral summary statistics for the currently logged-in participant.

Note: Returns 401 if the program uses participant authentication and the browser has no participant cookie.

growsurf.getReferralSummary();

Returns a Promise that resolves with an Object containing the participant's referral summary stats.

Example use

// Using a Callback
growsurf.getReferralSummary({}, (summary) => {
  console.log('Referral Summary:', summary);
});

// Using a Promise
const summary = await growsurf.getReferralSummary();
console.log(summary);

Example response

{
  "referrals": 23,         // Number of successful referrals
  "leads": 45,             // Number of pending referrals (leads)
  "expiredReferrals": 3,   // Number of referrals that expired before being credited
  "clicks": 23000,         // Number of unique visitors from the participant's referral link
  "rewardsEarned": 4,      // Number of rewards the participant has earned (approved)
  "pendingRewards": 1,     // Number of rewards still waiting to be approved (not yet earned)
  "invitesSent": 12,       // Number of email invites the participant has sent through GrowSurf
  "currencyISO": "USD"     // The ISO 4217 currency code of the campaign
}

AFFILIATE PROGRAMS ↓

Get commissions

Affiliate programs only

Returns a paginated list of commissions for the logged-in participant.

Note: Returns 401 if the program uses participant authentication and the browser has no participant cookie.

growsurf.getCommissions(options, callback);

Parameter

Data Type

Description

options

Object

(Optional) An object containing pagination options.

options.limit

Number

(Optional) The number of commissions to return per page. Defaults to 20.

options.nextId

String

(Optional) The ID of the commission to start the next result set with. This can be used to skip through the list or to page the list results. Each response will provide a nextId value if there are more commissions otherwise the nextId value will be null.

Returns a Promise that resolves with an Objectcontaining limited commissions data.

Example use

// Using a Callback - First page
growsurf.getCommissions({ limit: 10 }, (result) => {
  console.log(result.commissions); // Array of commission objects
  console.log(result.summary); // Summary of commissions by status
  console.log(result.hasMore); // Boolean indicating if more results are available
  console.log(result.nextId); // Cursor ID for next page (undefined if no more results)
});

// Fetching the next page
growsurf.getCommissions({ limit: 10, nextId: 'comm_abc123' }, (result) => {
  console.log(result.commissions); // Next page of results
});

// Using a Promise - First page
const result = await growsurf.getCommissions({ limit: 10 });
console.log(result.commissions); // Array of commission objects
console.log(result.summary); // Summary of commissions by status

// Fetching additional pages
if (result.hasMore) {
  const nextPage = await growsurf.getCommissions({ limit: 10, nextId: result.nextId });
  console.log(nextPage.commissions); // Next page of results
}

Example response

{
  "commissions": [
    {
      "id": "comm_t1so1w",
      "amount": 7228,
      "currencyISO": "USD",
      "status": "PENDING",
      "holdDuration": 0,
      "createdAt": 1764768074294,
      "amountInCampaignCurrency": 7228,
      "saleAmountInCampaignCurrency": 38900,
      "campaignCurrencyISO": "USD"
    }
  ],
  "summary": {
    "pending": {
      "count": 1,
      "totalAmount": 7228
    },
    "approved": {
      "count": 0,
      "totalAmount": 0
    },
    "paid": {
      "count": 0,
      "totalAmount": 0
    },
    "reversed": {
      "count": 0,
      "totalAmount": 0
    }
  },
  "totalCount": 1,
  "totalAmount": 7228,
  "nextId": "comm_def456",
  "hasMore": true
}

Get payouts

Affiliate programs only

Returns a paginated list of payouts for the logged-in participant.

Note: Returns 401 if the program uses participant authentication and the browser has no participant cookie.

growsurf.getPayouts(options, callback);

Parameter

Data Type

Description

options

Object

(Optional) An object containing pagination options.

options.limit

Number

(Optional) The number of payouts to return per page. Defaults to 20.

options.nextId

String

(Optional) The ID of the payout to start the next result set with. This can be used to skip through the list or to page the list results. Each response will provide a nextId value if there are more payouts otherwise the nextId value will be null.

Returns a Promise that resolves with an Objectcontaining limited payouts data.

Example use

// Using a Callback - First page
growsurf.getPayouts({ limit: 10 }, (result) => {
  console.log(result.payouts); // Array of payout objects
  console.log(result.summary); // Summary of payouts by status
  console.log(result.hasMore); // Boolean indicating if more results are available
  console.log(result.nextId); // Cursor ID for next page (undefined if no more results)
});

// Fetching the next page
growsurf.getPayouts({ limit: 10, nextId: 'payout_xyz' }, (result) => {
  console.log(result.payouts); // Next page of results
});

// Using a Promise - First page
const result = await growsurf.getPayouts({ limit: 10 });
console.log(result.payouts); // Array of payout objects
console.log(result.summary); // Summary of commissions by status

// Fetching additional pages
if (result.hasMore) {
  const nextPage = await growsurf.getPayouts({ limit: 10, nextId: result.nextId });
  console.log(nextPage.payouts); // Next page of results
}

Example response

{
	"payouts": [
		{
			"id": "po_kj19ss",
			"amount": 91212,
			"currencyISO": "USD",
			"status": "UPCOMING",
			"createdAt": 1763974665314,
			"amountInCampaignCurrency": 91212,
			"campaignCurrencyISO": "USD"
		},
		{
			"id": "po_asaj1s",
			"amount": 89120,
			"currencyISO": "USD",
			"status": "ISSUED",
			"paymentMethod": "PAYPAL",
			"createdAt": 1763974665314,
			"amountInCampaignCurrency": 89120,
			"campaignCurrencyISO": "USD"
		}
	],
  "summary": {
    "upcoming": {
      "count": 1,
      "totalAmount": 91212
    },
    "queued": {
      "count": 0,
      "totalAmount": 0
    },
    "issued": {
      "count": 1,
      "totalAmount": 89120
    }
  },
	"totalCount": 2,
	"totalAmount": 180332,
	"nextId": "po_x99s1o",
	"hasMore": true
}

Once a payout has been paid, it includes a paymentMethod showing how it was sent: PAYPAL, WISE, ACH, WIRE, CHECK, GIFT_CARD, CARD, WALLET, or OTHER. Payouts that have not been paid yet return paymentMethod: null.

Get affiliate summary

Affiliate programs only

Returns affiliate summary statistics for the currently logged-in participant.

Note: Returns 401 if the program uses participant authentication and the browser has no participant cookie.

growsurf.getAffiliateSummary();

Returns a Promise that resolves with an Objectcontaining the participant's affiliate summary stats.

Example use

// Using a Callback
growsurf.getAffiliateSummary({}, (summary) => {
  console.log('Affiliate Summary:', summary);
});

// Using a Promise
const summary = await growsurf.getAffiliateSummary();
console.log(summary);

Example response

{
  "referralRevenue": 2500000, // Total revenue generated from referrals (in minor currency units, e.g., cents)
  "totalPaidOut": 1500000, // Total commissions paid out to the affiliate (in minor currency units)
  "upcomingPayout": 500000, // Pending commissions to be paid out (in minor currency units)
  "referrals": 23, // Number of successful referrals
  "leads": 45, // Number of pending referrals (leads)
  "clicks": 23000, // Number of unique visitors from the affiliate's referral link (aka unique impressions)
  "currencyISO": "USD" // The ISO 4217 currency code of the campaign (e.g., "USD")
}

NOTIFICATIONS ↓

Initialize unread notifications badge

This method will inject an unread notifications badge onto a target element.

This method is useful for highlighting an unread notifications badge to your users from within your own user portal.

We recommend that the target element be a button that opens the GrowSurf window (via growsurf.open()), because the unread notifications badge will be cleared when the participant views the respective section in the GrowSurf window (rewards section for referral programs; commissions or payouts sections for affiliate programs).

Alternatively, you can use growsurf.markNotificationsAsRead() to clear the unread notifications badge.

If a participant cookie doesn't exist, the badge will not be displayed on the target element.

growsurf.initUnreadNotificationsBadge(targetElement, type);

Parameter

Data Type

Description

targetElement

String

(Required) The target element

Example: .my-button

type

String

(Optional) Available options: rewards commissions payouts If no type is provided, then all unread notification badges will be initialized.

Example use

<a class="my-button">
  Refer and Earn
</a>

<script>
  growsurf.initUnreadNotificationsBadge('.my-button');
</script>

CSS Alternative:

Instead of using the JavaScript method growsurf.initUnreadNotificationsBadge(), you can add a CSS class growsurf-unread-notifications-badge to your target element. This will also inject the unread badge without requiring JavaScript. Here is an example:

<a href="/refer"
   class="my-button growsurf-unread-notifications-badge">
  Refer and Earn
</a>

Note: You'll need to make sure you have the GrowSurf Universal Code installed.

Important Note: Notification counts will not appear if you have certain sections disabled within the Program Editor > 2. Design > Rewards section. For example:

For referral programs, if you have the rewards section hidden (see image below), the notification counts will not appear.
For affiliate programs, if you have the commissions or payouts sections hidden (see image below), the notification counts will only reflect the sections that are enabled.

Get unread notifications count

Returns the number of unread notifications (rewards for referral programs; commissions and payouts for affiliate programs) of the authenticated participant or null if there is no participant authentication cookie present. This method is useful for highlighting an unread notifications badge to your users from within your own user portal.

Alternatively, you can use the growsurf.initUnreadNotificationsBadge() method for displaying the unread notifications count as a badge on a target element.

Parameter

Data Type

Description

type

String

(Optional) Available options: rewards commissions payouts If no type is provided, then all unread notification counts will be returned.

growsurf.getUnreadNotificationsCount(type);

Example use

growsurf.getUnreadNotificationsCount('rewards');

Example response

Important Note: Notification counts will not appear if you have certain sections disabled within the Program Editor > 2. Design > Rewards section. For example:

For referral programs, if you have the rewards section hidden (see image below), the notification counts will not appear.
For affiliate programs, if you have the commissions or payouts sections hidden (see image below), the notification counts will only reflect the sections that are enabled.

Mark notifications as read

Mark unread notifications of the authenticated participant. This method is useful if you are using growsurf.initUnreadNotificationsBadge() instead of the GrowSurf window to show your users their unread notifications count and want to clear out the unread badge.

growsurf.markNotificationsAsRead(type);

Parameter

Data Type

Description

type

String

(Optional) Available options: rewards commissions payouts If no type is provided, then all unread notifications will be marked as read.

Returns a Promise that resolves with an Objectwith a success response.

Example use

// Using a Callback
growsurf.markNotificationsAsRead(response => {
  // handle success response
});

// Using a Promise
growsurf.markNotificationsAsRead().then(response => {
  // handle success response
});

Example response

{
    "success": true
}

EVENTS ↓

Adds an event subscription of the given event type. When an event of the given type occurs, the given callback will be invoked. Below are detailed descriptions of each event type.

growsurf.subscribe(eventType, callback);

Parameter

Data Type

Description

eventType

String

(Required) The event type to subscribe to.

These are the options:

referral
referralTrigger
signup
share
invite

callback

Function

The callback function that will be invoked when the event occurs.

Example use

/**
 * REFERRED FRIEND EVENTS
 */

// Subscribe to a `referral` event type
growsurf.subscribe('referral', (participant) => {
  // A new participant was referred
});

// Subscribe to a `referralTrigger` event type
growsurf.subscribe('referralTrigger', (participant) => {
  // A referred participant triggered a referral (AKA they completed the qualifying action)
});


/**
 * REFERRER EVENTS
 */

// Subscribe to a `signup` event type
growsurf.subscribe('signup', (participant) => {
  // A new participant was added (only non-referred signups)
});

// Subscribe to a `share` event type
growsurf.subscribe('share', (data) => {
  // A participant shared their unique referral URL by clicking a social share button
});

// Subscribe to an `invite` event type
growsurf.subscribe('invite', (participant) => {
  // A participant sent out an invite
});

Example response

Dispatched anytime an event happens. The provided callback will be invoked with an Object containing data relevant to the event.

The 'referral' event returns limited data of the new referred participant. The referredBy key represents the referring participant's unique ID.

{
    "id": "kafewp",
    "email": "gavin@hooli.com",
    "firstName": "Gavin",
    "lastName": "Belson",
    "referredBy": "xyz789",
    "referralCount": 0,
    "shareUrl": "https://piedpiper.com?grsf=kafewp",
    "rewards": [],
    "campaign": {
       "id": "abc123"
    }
}

The 'referralTrigger' Event returns limited data of the referred participant that triggered a referral (which means they completed a qualifying action).

Note: This event happens when calling growsurf.triggerReferral(). If you are looking for the referred signup event, use the 'referral' Event that contains a referredBy property.

{
    "id": "kafewp",
    "email": "gavin@hooli.com",
    "firstName": "Gavin",
    "lastName": "Belson",
    "referralCount": 0,
    "shareUrl": "https://piedpiper.com?grsf=kafewp",
    "rewards": [],
    "campaign": {
       "id": "abc123"
    }
}

The 'signup' Event returns limited data of the new non-referred participant.

{
    "id": "kafewp",
    "email": "gavin@hooli.com",
    "firstName": "Gavin",
    "lastName": "Belson",
    "referralCount": 0,
    "shareUrl": "https://piedpiper.com?grsf=kafewp",
    "rewards": [],
    "campaign": {
       "id": "abc123"
    }
}

The 'share' Event returns limited data of the participant and the share type.

The shareType value will either be a social network (e.g., linkedin, reddit) or copyLink if the participant copied their link to share (e.g., they clicked "Copy Link").

{
    "participant": {
        "id": "kafewp",
        "email": "gavin@hooli.com",
        "firstName": "Gavin",
        "lastName": "Belson",
        "referralCount": 0,
        "shareUrl": "https://piedpiper.com?grsf=kafewp",
        "rewards": []
    },
    "shareType": "facebook",
    "campaign": {
       "id": "abc123"
    }
}

The 'invite' Event returns limited data of the participant and the number of invites sent.

If your program is set up for email invites to be sent by participants, invitesAttempted will always match invitesSent. If email invites are sent by your company, invitesSent will only count successfully delivered emails confirmed by our server. Learn more here.

{
    "participant": {
        "id": "kafewp",
        "email": "gavin@hooli.com",
        "firstName": "Gavin",
        "lastName": "Belson",
        "referralCount": 0,
        "shareUrl": "https://piedpiper.com?grsf=kafewp",
        "rewards": []
    },
    "invitesAttempted": 3,
    "invitesSent": 3,
    "campaign": {
       "id": "abc123"
    }
}

Last updated 3 days ago

Was this helpful?

SDK LIFECYCLE ↓

Initialize / Reinitialize GrowSurf

Get participant ID

Example use

Log out

Example use

CAMPAIGNS ↓

Get campaign

Example use

Example response

GROWSURF WINDOW ↓

Open GrowSurf window

Example use

CSS Alternative:

Close GrowSurf window

Example use

REFERRERS ↓

Get referrer ID

Example use

Example response

Validate referrer

Example use

Example response

PARTICIPANTS ↓

Add referred participant

Example use

Example response

Add participant

Example use

Example response

Get participant by email

Example use

Example response

Get participant by ID

Example use

Example response

REFERRALS AND INVITES ↓

Update social share message

Example use

Update email invite message

Example use

REFERRAL PROGRAMS ↓

Trigger referral

Example use

Example response

Get upfront discount

Example use

Example response

Get referral summary

Example use

Example response

AFFILIATE PROGRAMS ↓

Get commissions

Example use

Example response

Get payouts

Example use

Example response

Get affiliate summary

Example use

Example response

NOTIFICATIONS ↓

Initialize unread notifications badge

Example use

CSS Alternative:

Get unread notifications count

Example use

Mark notifications as read

Example use

Example response

EVENTS ↓

Subscribe to event

Example use

Example response