All Collections
Okendo Referrals
Headless Installation
Installing Referrals Widget (Headless)
Installing Referrals Widget (Headless)
Norma Cooper avatar
Written by Norma Cooper
Updated over a week ago

When a referrals product is enable in a store, the API is normally added automatically to the metafields. However, with many headless implementations you'll need to manually add them, which will be outlined in this article.

Adding Referrals API to a store

To load the Referrals API on your store, you will need these two elements in your store.

Referrals API JS

Add the referrals-api.js script in the header, and make sure it has the defer attribute or is otherwise only loaded after the DOM has finished loading.

For example, add the following to your site’s <head> element:

<script type="text/javascript" defer="" src=""></script>

Referral Settings

The Referrals API will use these settings to identify your store, so they will need to be added to your store’s <head> element or elsewhere depending on your headless implementation.

For example, add the following to your site’s <head> element (replace the xxxx in the following with your own subscriberId):

<script id="okeReferralSettings" type="application/json">{"subscriberId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}</script>

If you're unsure about your subscriberId, you can find it in the Okendo Admin under:

Settings > Integrations > Okendo > User ID:

Using the Referrals Widget

On page load, we check to see if the full Referrals Widget needs to be loaded or not, to make the page load as fast as possible.

When the Referrals API JS loads, it will check the following:

  • If there is an element (i.e. <div></div>) on the page containing the “data-oke-referrals-widget” attribute, the widget will be embedded in that element

  • If there is a query string containing referralSenderId or referralId, then we are assuming that the user has arrived from a “referral share link” or from a “referral verification email”, so the widget will be opened automatically as a modal (or else we will scroll to the widget if it is embedded in the page)

If you don’t want to have the widget embedded on the page but would like users to be able to open it using a button, link, or on a custom event:

  • Add an element (e.g. <button>Refer A Friend</button>) containing the “data-oke-open-referrals” attribute (this will only work if the element is in the body of your page when the Referrals API JS loads, otherwise you will need to do the following as a custom click event).

  • In a custom event (or click event), call window.okeReferralsApi.openModal()

Did this answer your question?