1 of 50

Rewardful Developer Center

Introduction

Welcome to the Rewardful Developer documentation! We're excited to see what you build 🙂

REST API

Programmatically manage resources within your Rewardful account.

Webhooks

Receive notifications to your own app (or Zapier) about events that occur within your Rewardful account.

JavaScript API

Overview

Introduction to Rewardful's JavaScript API

Rewardful's remote script loads asynchronously to make it as performant and reliable as possible. You can use our asynchronous JavaScript API to perform client-side conversion tracking as well as execute functions when Rewardful has initialized.

Add the JavaScript tag + snippet

To add support for our asynchronous JavaScript API, place this code snippet onto every page of your website, ideally in the <head> tag:

<script>(function(w,r){w._rwq=r;w[r]=w[r]||function(){(w[r].q=w[r].q||[]).push(arguments)}})(window,'rewardful');</script>

This code will add a rewardful function to the page, which can be immediately called and passed instructions that Rewardful will execute once loaded. The general format of these method calls is rewardful(methodName, arg1, arg2, arg3, ...)

<script>(function(w,r){w._rwq=r;w[r]=w[r]||function(){(w[r].q=w[r].q||[]).push(arguments)}})(window,'rewardful');</script>
<script async src='https://r.wdfl.co/rw.js' data-rewardful='YOUR-API-KEY'></script>

Client-Side Conversion Tracking

Rewardful's JavaScript API allows you to track conversions with frontend code only — no backend code is required. This can make integrating Rewardful much simpler, and enables you to use Rewardful in scenarios where you're unable to modify backend/server code, such as when using a hosted platform to sell your products.

To track a conversion client-side, use the "convert" function, and pass the customer's email address using the email parameter. This code should appear on your thank-you or receipt page (or whatever page your customers are taken to immediately after purchase).

For example:

<script>
  rewardful('convert', { email: 'joe@example.com' })
</script>

This code will search for the most recently created customer with the email address "joe@example.com" in your Stripe account. If the customer exists and the Rewardful cookie is present (i.e. this visitor is a referral), Rewardful with associate the customer with the affiliate.

Note: this code only performs network requests if the current website visitor is a referral. If the visitor arrived on your website through another channel, the convert function does nothing.

Requirements

In order to use Client-Side Conversion Tracking there are a few prerequisites:

Your platform creates Stripe Customers within your Stripe account when a purchase is made.
You are able to add client-side code snippets to your website & receipt/thank-you page, and access the customer's email address on these pages.

The Stripe customer must have been created within the last 24 hours in order to be tracked with client-side conversion tracking.

Executing code when Rewardful loads

In some cases you might want to execute code once Rewardful has fully loaded and performed any tracking/network requests.

Pass a callback function to the ready handler to have it executed when Rewardful has fully loaded. This function always executes, whether the current visitor is a referral or not. For example:

<script>
  rewardful('ready', function() {
    console.log('Rewardful Ready!')
  });
</script>

If you only want code to run if the current visitor is a referral, you can check the Rewardful.referral property:

<script>
  rewardful('ready', function() {
    if(Rewardful.referral) {
      // The current website visitor is a referral from an affiliate.
    }
  });
</script>

Calls to rewardful are queued and executed in order once Rewardful has loaded. This means you can queue up multiple functions, and even call rewardful if Rewardful is loaded (which effectively calls the underlying function immediately). For example:

<script>
  rewardful('ready', function() {
    console.log('This will fire first.')
  });
  
  rewardful('ready', function() {
    console.log('This will fire second.')
  });
  
  rewardful('ready', function() {
    console.log('This will fire third.')
  });
</script>

Do not run critical code within a ready handler (i.e. checkout code). If Rewardful fails to load for any reason (network issue, adblockers, etc.) then the ready handler will never run and your code will not execute.

If you must place critical code within a ready handler, use defensive programming techniques (such as setTimeout) to ensure your critical code will execute even if Rewardful never loads.

Specify traffic source

It's possible to force the current visitor to be attributed to an affiliate even if the visitor didn't arrive through an affiliate link. This is useful for creating landing pages with friendly URLs for a partner promotion, or for creating URLs that are easier to share verbally (i.e. on podcasts).

<script>
  rewardful('source', AFFILIATE_LINK_TOKEN)
</script>

Example: instead of example.com/?via=bond007 you could create a page at example.com/bond and include the snippet below to ensure all visitors to this page get attributed to James Bond:

<script>
  rewardful('source', 'bond007')
</script>

It's important to note that this operation overwrites any existing referral for the visitor that's stored in the cookie. Continuing our example above, if the visitor first arrived through example.com/?via=batman but then went on to visit example.com/bond (where the code above is executed) then James Bond would ultimately get credited for the conversion.

Preloading a referral ID

However, there may be situations where you want to preload a specific referral ID into the cookie. This can be done by adding a ?referral=<UUID> parameter to the URL:

https://www.example.com/pricing?referral=bffa8b94-b25a-45a4-97a0-1c8ecb8018b9

An example of when this is relevant is when the checkout process is embedded within an iframe. If the parent URL and iframe URL both have a via parameter then two referrals will be created (one for each window) which artificially inflates visitor stats.

In this scenario, the parent window can check for an existing referral ID and pass it to the iframe by adding a referral=<UUID>parameter to the iframe URL before inserting the iframe into the DOM:

rewardful('ready', function() {
  const iframe = document.createElement('iframe')

  iframe.src = 'https://checkout.example.com'

  if(Rewardful.referral) {
    iframe.src += `?referral=${Rewardful.referral}`
  }

  document.appendChild(iframe)
});

Attributes

Referral

Rewardful.referral will return the Referral ID of the current visitor if they were referred, for example: "98288128-0d5f-45a9-88b3-ef95b229f798"

If the current visitor was not referred by a Rewardful affiliate, Rewardful.referral will return an empty string: ""

<script>
  rewardful('ready', function() {
    if(Rewardful.referral) {
      console.log('Current referral ID: ', Rewardful.referral);
    } else {
      console.log('No referral present.');
    }
  });
</script>

Affiliate

Rewardful.affiliate will return some information about who sent you a referral, for example:

{
  id: "b533bfca-7c70-4dec-9691-e136a8d9a26c",
  name: "James Bond",
  first_name: "James",
  last_name: "Bond",
  token: "james007"
}

You might want to use this for personalizing your website based on who the affiliate was:

<script>
  rewardful('ready', function() {
    if(Rewardful.affiliate) {
      $('.affiliate-banner').text(
        `Hi there, friend of ${Rewardful.affiliate.first_name}!`
      ).show();
    }
  });
</script>

Rewardful.affiliate returns false if there is no affiliate, i.e. the current visitor was not referred.

Campaign

Rewardful.campaign will return the ID and name of the campaign the affiliate is associated with:

{
  "campaign": {
  "id": "1f51675a-646d-4a83-898b-16e0ceeb0373",
  "name": "Friends of Acme, Inc."
  }
}

Coupon Details

For example, a 25% discount that repeats for 12 months might look like:

{
  id: "bf-2019",
  name: "Black Friday 2019",
  duration: "repeating",
  duration_in_months: 12,
  percent_off: 25,
  amount_off: null,
  currency: null
}

And a one-time $25 USD discount might look like:

{
  id: "save-25",
  name: "One-time $25 credit",
  duration: "once",
  duration_in_months: null,
  percent_off: null,
  amount_off: 2500,
  currency: "usd"
}

We recommend checking for the coupon's existence before attempting to access it's attributes, for example:

<script>
  rewardful('ready', function() {
    if(Rewardful.coupon) {
      showCouponBanner(Rewardful.coupon);
    }
  });
</script>

Methods

Attaching to forms

On page load Rewardful will automatically inject a hidden input into forms with a data-rewardful attribute. This makes it simple to get the referral ID sent to your server along with the rest of the data from your signup or payment form.

For example, your signup form might look something like this:

<form action="/signup" method="post" data-rewardful="true">
  <input type="text" name="name">
  <input type="email" name="email">
  <button>Sign Up</button>
</form>

If the current visitor came to your site through an affiliate link, Rewardful will detect the data-rewardful attribute and automatically insert a hidden input named referral with the unique click ID (UUID) as the value. For example:

<form action="/signup" method="post" data-rewardful="true">
  <input type="text" name="name">
  <input type="email" name="email">
  <button>Sign Up</button>
  
  <!-- Inserted automatically by Rewardful: -->
  <input type="hidden" name="referral" value="78476c40-0137-11eb">
</form>

When the form is submitted, the POST data sent to your server will include the referral parameter, along with the rest of the customer data. You can extract this value ($_POST['referral'] in PHP, params[:referral] in Rails, etc) and add it to the Stripe customer's metadata or save it in your own database for future use.

Manually attaching to forms

To attach to all forms present in the DOM with the data-rewardful attribute, you can call Rewardful.Forms.attach()

Turbolinks example:

document.addEventListener("turbolinks:load", function() {
  Rewardful.Forms.attach();
});

$('#signup-modal').on('shown.bs.modal', function (e) {
  Rewardful.Forms.attach();
});

Attaching to specific forms

If you'd like to manually attach the hidden referral input into a specific form, you can do so with Rewardful.Forms.add(formElement), for example:

const signupForm = document.getElementById('signup-form');
Rewardful.Forms.add(signupForm);

This can be useful in circumstances where you cannot easily modify the source code of the form tag (for example, using a CMS or hosted service) and are unable to add the data-rewardful attribute.

Troubleshooting

If you're running into issues with your JavaScript integration it's possible to inspect the data stored in the Rewardful cookie using the Rewardful._cookie attribute.

IMPORTANT: TheRewardful._cookie is for debugging purposes only. This data structure is for may change formats at any time without warning and should not be used for any purpose other than troubleshooting.

Here's an example of the data structure returned by Rewardful._cookie:

{
  "id": "c4b3c530-3d7b-4f01-89bf-12ce7cbe1e4b",
  "created_at": "2021-01-10T13:27:16.766-07:00",
  "affiliate": {
    "id": "b533bfca-7c70-4dec-9691-e136a8d9a26c",
    "name": "James Bond",
    "first_name": "James",
    "last_name": "Bond",
    "token": "jb007"
  },
  "campaign": {
    "id": "1f51675a-646d-4a83-898b-16e0ceeb0373",
    "name": "Friends of Acme, Inc."
  },
  "coupon": null,
  "cookie": {
    "domain": "example.com"
  }
}

Attribute

Description

id

The UUID of the referral (equivalent toRewardful.referral)

created_at

Timestamp at which this referral was originally created.

affiliate

Equivalent to Rewardful.affiliate

campaign

Equivalent to Rewardful.campaign

coupon

Equivalent to Rewardful.coupon

cookie

Additional metadata about the cookie

REST API

Overview

Introduction to Rewardful's REST API

Authentication

Be sure to replace YOUR_API_SECRET with your actual API Secret. For example, if your API secret was ABC123, the curl command to fetch all affiliates would be:

Keep your API Secret safe!

Your API Secret grants full access to your Rewardful account. Do not:

Share your API Secret with third parties
Commit your API Secret to version control (i.e. Git)
Share your API Secret over email or chat
Send your API Secret to the web browser in HTML or JavaScript

Request and Response Formats

Errors

Missing or invalid authorization will return a 401 Unauthorized JSON response:

Requesting a nonexistent object will return a 404 Not Found JSON response:

Passing invalid data to a create/update endpoint will return a 422 Unprocessable Entity JSON response:

Pagination

API endpoints that return a list of objects include pagination, unless noted otherwise. The data structure has two root objects:

The `pagination` object

Example

This example demonstrates the pagination for a collection of 150 objects in total, split into 3 pages of 50 objects per page:

Expanding objects

Many objects allow you to request additional information as an expanded response by using the expand request parameter. You can use expand to expand a single type of object, or expand[] to expand multiple types of objects.

The documentation for each endpoint will list which objects are expandable (if any) for that endpoint.

For example, to expand an affiliate you would prepend this query string parameter to the request URL:

To expand both affiliate and sale objects, prepend this query string parameter to the request URL:

Rate limits

In most cases the API rate limit is 45 requests per 30 second window. Please treat these limits as absolute maximums and do not generate unnecessary load.

If you plan to run a batch script (such as programmatically creating many affiliates via API), please throttle your API usage by adding sleep/delay mechanisms to your script. We may reduce limits at any time to prevent abuse.

Campaigns

Create, retrieve, and update campaigns through REST API calls.

The campaign object

A campaign represents a specific program offer with its own display settings and rules that affiliates may register to promote.

Attributes

List campaigns

Returns a list of all your campaigns.

Request

Method

URL

GET

https://api.getrewardful.com/v1/campaigns

Examples

List all campaigns

curl --request GET \
  --url https://api.getrewardful.com/v1/campaigns \
  -u YOUR_API_SECRET:

Response

Create campaign

Creates a new campaign in your account with the specified parameters.

This endpoint allows merchants to create new campaigns on demand by providing a set of the most common parameters used

Request

Method

URL

POST

https://api.getrewardful.com/v1/campaigns

Parameters

Parameter

Required?

Description

name

Yes

The campaign's name

url

Yes

The base URL that will be used to generate affiliate links for the campaign

private

true if the campaign should be invite-only, false if it should be open to the public. (Default: false)

reward_type

Yes

The type of reward associated with this campaign - percent or amount

commission_percent

Yes, if reward_type is percent

The commission percentage for this campaign

commission_amount_cents

Yes, if reward_type is amount

The amount of the fixed commission for this campaign in cents

commission_amount_currency

Yes, if reward_type is amount

ISO currency code in which the fixed commission for this campaign is denominated. Fixed commissions can be defined in any currency, but they will be converted to and displayed in your company's display currency when awarded.

minimum_payout_cents

The minimum amount of cumulative commissions required for an affiliate to receive a payout in cents denominated in your company's display currency. (Default: 0)

stripe_coupon_id

Example

curl --request POST \
  --url https://api.getrewardful.com/v1/campaigns \
  -u YOUR_API_SECRET: \
  -d "name=Special Friends of Rewardful" \
  -d url=https://rewardful.com \
  -d private=true \
  -d reward_type=percent \
  -d commission_percent=50.0 \
  -d minimum_payout_cents=5000

Response

Response code

Body

200

Invalid parameters

Response code

Body

422

JSON object describing validation errors.

{
  "error": "Could not create campaign.",
  "details": ["Name can't be blank"]
}

Authentication failure

Response code

Body

401

Description of the authentication failure.

{  "error": "Invalid API Secret." }

Retrieve campaign

Retrieves the details of an existing campaign specified by its unique identifier.

Request

Example

Response

Update campaign

Updates the specified campaign by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Request

Parameters

Example

Response

Not found

Authentication failure

Affiliates

Create, retrieve, and update affiliates through REST API calls.

The affiliate object

{
  "id": "d0ed8392-8880-4f39-8715-60230f9eceab",
  "created_at": "2019-05-09T16:18:59.920Z",
  "updated_at": "2019-05-09T16:25:42.614Z",
  "first_name": "Adam",
  "last_name": "Jones",
  "email": "adam.jones@example.com",
  "paypal_email": null,
  "state": "active",
  "stripe_customer_id": "cus_ABCDEF123456",
  "stripe_account_id": "acct_ABCDEF123456",
  "visitors": 100,
  "leads": 42,
  "conversions": 18,
  "campaign": {
    "id": "a638ebe4-291d-47cd-a1dc-1519f9331bbd",
    "created_at": "2019-04-27T18:13:13.123Z",
    "updated_at": "2019-05-05T20:58:24.200Z",
    "name": "Best Friends of Kyle"
  },
  "links": [
    {
      "id": "eb844960-6c42-4a3b-8009-f588a42d8506",
      "url": "http://www.example.com/?via=adam",
      "token": "adam",
      "visitors": 100,
      "leads": 42,
      "conversions": 18,
    }
  ], 
  "coupon": {
   "id": "75434e84-255b-4314-a278-820df5e76813",
   "external_id": "promo_1a2b3c",
   "token": "CODE",
   "leads": 0,
   "conversions": 0,
   "affiliate_id": "95d48f70-f1d4-42d9-b929-21996b6d9eb4"
  }
}

Attributes

Name

Data Type

Description

id

string

Unique identifier for the affiliate.

created_at

string

Time at which the affiliate was created.

updated_at

string

Time at which the affiliate was last updated.

first_name

string

The affiliate's first name.

last_name

string

The affiliate's last name.

email

string

The affiliate's email address name.

paypal_email

string

wise_email

string

state

string

The affiliate's current state.

visitors

string

The total number of unique visitors attributes to this affiliate.

leads

string

The total number of leads (anonymous visitors who became customers) attributed to this affiliate.

conversions

string

The total number of conversions (leads who have made at least one payment) attributed to this affiliate.

campaign

object

A campaign object representing the campaign this affiliate belongs to.

links

array

An array of link objects representing the affiliate's links.

coupon

object

A coupon object representing the affiliate's coupon.

Additional attributes for customer referrers

These attributes only apply to affiliates who are members of a customer referral program.

Name

Data Type

Description

stripe_customer_id

string

Represents the Stripe Customer associated with this affiliate. This is the Stripe Customer that will receive rewards in the form of account credits.

stripe_account_id

string

The Stripe Account that contains the customer represented by stripe_customer_id.

State

Affiliates have a state attribute that can be one of the following values:

active (default)
disabled
suspicious

Disabled and Suspicious affiliates will not have visitors/leads/conversions tracked, cannot earn new commissions, and cannot login to the affiliate dashboard.

Related Help Center Articles

List affiliates

Returns a list of your affiliates. The affiliates are returned sorted by creation date, with the most recent affiliates appearing first. The list can also be filtered using various criteria.

Request

Method

URL

GET

https://api.getrewardful.com/v1/affiliates

Optional parameters

Parameter

Description

campaign_id

A filter based on the affiliate's campaign.

email

A filter based on the affiliate's email address.*

stripe_customer_id

A filter based on the affiliate's Stripe customer ID.* (Applies to customer referrers)

page

limit

How many results to return per page. Default is 25, maximum is 100.

expand

*Filtering by email or stripe_customer_id will return a list with one (or zero) items.

Expandable objects

Parameter

Description

campaign

Includes the campaign details as a nested object for each affiliate in the list.

links

Includes an array of the affiliate's links as a nested object for each affiliate in the list.

commission_stats

Include a nested object describing the affiliate's commission stats for each affiliate in the list.

Examples

List all affiliates

curl --request GET \
  --url https://api.getrewardful.com/v1/affiliates \
  -u YOUR_API_SECRET:

List all affiliates and expand campaign data

curl --request GET \
  --url https://api.getrewardful.com/v1/affiliates?expand=campaign \
  -u YOUR_API_SECRET:

List all affiliates and expand campaign and links data

curl --request GET \
  --url https://api.getrewardful.com/v1/affiliates?expand[]=campaign&expand[]=links \
  -u YOUR_API_SECRET:

Filter list of affiliates by campaign

curl --request GET \
  --url https://api.getrewardful.com/v1/affiliates?campaign_id=c3482343-8680-40c5-af9a-9efa119713b5 \
  -u YOUR_API_SECRET:

Filter list of affiliates by email address

curl --request GET \
  --url https://api.getrewardful.com/v1/affiliates?email=joe@example.com \
  -u YOUR_API_SECRET:

Create affiliate

Creates a new affiliate in your account with the specified parameters.

This endpoint allows merchants to create affiliates on demand.

Both normal affiliates and customer referrers can be created through this endpoint. To create a customer referrer, simply pass the stripe_customer_id parameter that indicates the Stripe Customer that should receive account credits as rewards.

Request

Parameters

receive_new_commission_notifications may also be optionally provided. This parameter indicates whether or not the affiliate should receive emails when new rewards and commissions are earned. Accepts true (default) or false.

Example

Response

Invalid parameters

Authentication failure

Retrieve affiliate

Retrieves the details of an existing affiliate. You need only supply the unique affiliate identifier that was returned upon affiliate creation.

Request

Example

Response

Update affiliate

Updates the specified affiliate by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Request

Parameters

Example

Response

Not found

Authentication failure

Affiliate Links

Create, retrieve, and update affiliate links through REST API calls.

The affiliate link object

Attributes

Referrals

A referral represents a unique visitor that arrived on your website through an affiliate link, which may have gone on to become a lead or paying customer (conversion).

Webhooks

Overview

Introduction to Rewardful's JavaScript API

Add the JavaScript tag + snippet

To add support for our asynchronous JavaScript API, place this code snippet onto every page of your website, ideally in the <head> tag:

<script>(function(w,r){w._rwq=r;w[r]=w[r]||function(){(w[r].q=w[r].q||[]).push(arguments)}})(window,'rewardful');</script>

It's important for this snippet to appear in your HTML before any calls to the rewardful function. To make it simple, we recommend adding it immediately before the script tag that loads the remote Rewardful script from in the setup instructions. Your final Step #1 snippet should look something like this:

<script>(function(w,r){w._rwq=r;w[r]=w[r]||function(){(w[r].q=w[r].q||[]).push(arguments)}})(window,'rewardful');</script>
<script async src='https://r.wdfl.co/rw.js' data-rewardful='YOUR-API-KEY'></script>

Remember to replace YOUR-API-KEY with your Rewardful API Key, which can be found on the page in your Rewardful dashboard.

Client-Side Conversion Tracking

For example:

<script>
  rewardful('convert', { email: 'joe@example.com' })
</script>

Note: this code only performs network requests if the current website visitor is a referral. If the visitor arrived on your website through another channel, the convert function does nothing.

Requirements

In order to use Client-Side Conversion Tracking there are a few prerequisites:

Your Stripe account must be connected to Rewardful with .
Your platform creates Stripe Customers within your Stripe account when a purchase is made.
You are able to add client-side code snippets to your website & receipt/thank-you page, and access the customer's email address on these pages.

The Stripe customer must have been created within the last 24 hours in order to be tracked with client-side conversion tracking.

Executing code when Rewardful loads

In some cases you might want to execute code once Rewardful has fully loaded and performed any tracking/network requests.

Pass a callback function to the ready handler to have it executed when Rewardful has fully loaded. This function always executes, whether the current visitor is a referral or not. For example:

<script>
  rewardful('ready', function() {
    console.log('Rewardful Ready!')
  });
</script>

If you only want code to run if the current visitor is a referral, you can check the Rewardful.referral property:

<script>
  rewardful('ready', function() {
    if(Rewardful.referral) {
      // The current website visitor is a referral from an affiliate.
    }
  });
</script>

<script>
  rewardful('ready', function() {
    console.log('This will fire first.')
  });
  
  rewardful('ready', function() {
    console.log('This will fire second.')
  });
  
  rewardful('ready', function() {
    console.log('This will fire third.')
  });
</script>

If you must place critical code within a ready handler, use defensive programming techniques (such as setTimeout) to ensure your critical code will execute even if Rewardful never loads.

Specify traffic source

<script>
  rewardful('source', AFFILIATE_LINK_TOKEN)
</script>

Example: instead of example.com/?via=bond007 you could create a page at example.com/bond and include the snippet below to ensure all visitors to this page get attributed to James Bond:

<script>
  rewardful('source', 'bond007')
</script>

Preloading a referral ID

Normally Rewardful will look for the ?via=token query string parameter when attributing a visit to an affiliate. When the via parameter is present and valid, a new referral will be created for the affiliate and the referral ID stored in the cookie as .

However, there may be situations where you want to preload a specific referral ID into the cookie. This can be done by adding a ?referral=<UUID> parameter to the URL:

https://www.example.com/pricing?referral=bffa8b94-b25a-45a4-97a0-1c8ecb8018b9

When a user browses to this URL, the existing referral with ID bffa8b94-b25a-45a4-97a0-1c8ecb8018b0 will be loaded into the cookie. (This is actually how ).

In this scenario, the parent window can check for an existing referral ID and pass it to the iframe by adding a referral=<UUID>parameter to the iframe URL before inserting the iframe into the DOM:

rewardful('ready', function() {
  const iframe = document.createElement('iframe')

  iframe.src = 'https://checkout.example.com'

  if(Rewardful.referral) {
    iframe.src += `?referral=${Rewardful.referral}`
  }

  document.appendChild(iframe)
});

This will ensure the iframe is using the same referral ID as the parent window and will prevent double-tracking visitors. If using the approach above to insert your checkout iframe, ensure you have a fallback plan in case Rewardful never loads. See for more information.

Attributes

Because Rewardful loads asynchronously, we recommend accessing these attributes within the rewardful('ready')handler. See for details.

Referral

Rewardful.referral will return the Referral ID of the current visitor if they were referred, for example: "98288128-0d5f-45a9-88b3-ef95b229f798"

If the current visitor was not referred by a Rewardful affiliate, Rewardful.referral will return an empty string: ""

<script>
  rewardful('ready', function() {
    if(Rewardful.referral) {
      console.log('Current referral ID: ', Rewardful.referral);
    } else {
      console.log('No referral present.');
    }
  });
</script>

Affiliate

Rewardful.affiliate will return some information about who sent you a referral, for example:

{
  id: "b533bfca-7c70-4dec-9691-e136a8d9a26c",
  name: "James Bond",
  first_name: "James",
  last_name: "Bond",
  token: "james007"
}

You might want to use this for personalizing your website based on who the affiliate was:

<script>
  rewardful('ready', function() {
    if(Rewardful.affiliate) {
      $('.affiliate-banner').text(
        `Hi there, friend of ${Rewardful.affiliate.first_name}!`
      ).show();
    }
  });
</script>

Rewardful.affiliate returns false if there is no affiliate, i.e. the current visitor was not referred.

Campaign

Rewardful.campaign will return the ID and name of the campaign the affiliate is associated with:

{
  "campaign": {
  "id": "1f51675a-646d-4a83-898b-16e0ceeb0373",
  "name": "Friends of Acme, Inc."
  }
}

Coupon Details

If you've , the coupon object will be available through Rewardful.coupon. The attributes correspond directly to the in Stripe.

For example, a 25% discount that repeats for 12 months might look like:

{
  id: "bf-2019",
  name: "Black Friday 2019",
  duration: "repeating",
  duration_in_months: 12,
  percent_off: 25,
  amount_off: null,
  currency: null
}

And a one-time $25 USD discount might look like:

{
  id: "save-25",
  name: "One-time $25 credit",
  duration: "once",
  duration_in_months: null,
  percent_off: null,
  amount_off: 2500,
  currency: "usd"
}

We recommend checking for the coupon's existence before attempting to access it's attributes, for example:

<script>
  rewardful('ready', function() {
    if(Rewardful.coupon) {
      showCouponBanner(Rewardful.coupon);
    }
  });
</script>

Methods

Attaching to forms

For example, your signup form might look something like this:

<form action="/signup" method="post" data-rewardful="true">
  <input type="text" name="name">
  <input type="email" name="email">
  <button>Sign Up</button>
</form>

<form action="/signup" method="post" data-rewardful="true">
  <input type="text" name="name">
  <input type="email" name="email">
  <button>Sign Up</button>
  
  <!-- Inserted automatically by Rewardful: -->
  <input type="hidden" name="referral" value="78476c40-0137-11eb">
</form>

Manually attaching to forms

If your form is dynamically added to the page (, a single-page app or a modal) you'll need to manually tell Rewardful to attach to these forms after they have been added to the DOM.

To attach to all forms present in the DOM with the data-rewardful attribute, you can call Rewardful.Forms.attach()

Turbolinks example:

document.addEventListener("turbolinks:load", function() {
  Rewardful.Forms.attach();
});

$('#signup-modal').on('shown.bs.modal', function (e) {
  Rewardful.Forms.attach();
});

Attaching to specific forms

If you'd like to manually attach the hidden referral input into a specific form, you can do so with Rewardful.Forms.add(formElement), for example:

const signupForm = document.getElementById('signup-form');
Rewardful.Forms.add(signupForm);

This can be useful in circumstances where you cannot easily modify the source code of the form tag (for example, using a CMS or hosted service) and are unable to add the data-rewardful attribute.

Troubleshooting

If you're running into issues with your JavaScript integration it's possible to inspect the data stored in the Rewardful cookie using the Rewardful._cookie attribute.

Here's an example of the data structure returned by Rewardful._cookie:

{
  "id": "c4b3c530-3d7b-4f01-89bf-12ce7cbe1e4b",
  "created_at": "2021-01-10T13:27:16.766-07:00",
  "affiliate": {
    "id": "b533bfca-7c70-4dec-9691-e136a8d9a26c",
    "name": "James Bond",
    "first_name": "James",
    "last_name": "Bond",
    "token": "jb007"
  },
  "campaign": {
    "id": "1f51675a-646d-4a83-898b-16e0ceeb0373",
    "name": "Friends of Acme, Inc."
  },
  "coupon": null,
  "cookie": {
    "domain": "example.com"
  }
}

Attribute

Description

id

The UUID of the referral (equivalent toRewardful.referral)

created_at

Timestamp at which this referral was originally created.

affiliate

Equivalent to Rewardful.affiliate

campaign

Equivalent to Rewardful.campaign

coupon

Equivalent to Rewardful.coupon

cookie

Additional metadata about the cookie