Skip to content
Operator handbook
Refer a Friend
Hygraph
Sign in
Hygraph

Refer a Friend

This article explains which parts of the Refer a Friend program are managed in Hygraph. A customer shares their referral code with a friend. The friend gets a discount on their first order, and once that order is paid the customer gets a voucher of their own.

The amounts, minimum order values and how long a voucher stays valid are not set in Hygraph or commercetools. They are Voucherify settings. Ask the development team to change them.

For what you can see in commercetools, see Refer a Friend in commercetools.

Overview

The program has three parts in Hygraph:

  • Landing page: a regular Page that explains the program, for example /de/friend-referral.
  • Referral portal: a Protected Area at /de/refer-a-friend. A logged-in customer sees their code, their share link, their stats and the vouchers they earned.
  • Portal texts: the texts inside the portal are Static Words.

The emails (welcome, voucher earned, voucher about to expire) are sent from Emarsys, not Hygraph.

Landing page

The landing page is a normal Page built from existing sections, such as Hero Banner, Text Section, Grid and FAQ Section. Edit it like any other page, see Pages and Sections, Components and Elements.

Landing page

Keep these in mind:

  • The amounts are written in the copy. Hygraph does not know the real amounts, so nothing updates by itself. When the development team changes an amount or a minimum order value, update the landing page, its FAQ and the portal content below in every language.
  • Friend and referrer have different minimums. The friend's discount needs a minimum for their first order, the referrer's voucher needs a higher minimum. Check which of the two a sentence is about before writing the number.
  • Buttons to the portal link to /refer-a-friend.
  • Publish every language. After publishing, check the page in each language. A section that shows in one language but is missing in another usually has no version for that language yet. See Save, Publish and Schedule.
  • Say product value, not order value. The minimum is checked against the products in the cart after discounts, without shipping. In German that is Warenwert, not Bestellwert. The live page words it like this:
Language Example
German Gültig ab 75,00 € Warenwert
French Valable à partir de 75,00 € de marchandises
Italian Valido da 75,00 € di merce
Spanish Válido a partir de 75,00 € en productos
Dutch Geldig vanaf € 75,00 aan producten

Referral portal

How to configure

To view or edit the portal, in Hygraph navigate via the left menu pane to Content, and in the secondary left menu pane under DEFAULT VIEWS select Protected Area. Open the entry Refer a friend.

Protected Area in Hygraph

The dashboard itself (code, share link, stats, history and the claim dialog) is built into the shop. You change its texts through Static Words, see Portal texts. Everything else is set on the Protected Area.

Referral portal

Protected Area fields

Title

Title (title) is the heading of the portal and its breadcrumb. It is localized, so fill it in for every language.

Tenant and Storefronts

Tenant (tenant) and Storefronts (storefront) decide which shops show this portal. This portal only appears on the webshops you select. If you leave a storefront unselected, it will not show there.

Customer Group

Customer Group (customerGroup) is the key of the commercetools customer group that holds the program's participants, for example vitaminexpress-friend-referrers. The shop also uses this key to find the program in Voucherify.

The key has to match commercetools and Voucherify exactly. Do not change it. If it is wrong, the portal cannot find a program and shows an error.

Area Type

Area Type (areaType) decides who may open the area:

Area Type

  • Friend to Friend (friendToFriend): any logged-in customer. On their first visit they join the program automatically and get their referral code. Used for Refer a Friend.
  • Professionals (professionals): only customers who are already in the customer group, for example therapists. Anyone else is sent to their account.

Customers who are not logged in are sent to the login page first, for both types.

Do not change the Area Type of an existing area.

SEO

SEO (seo) holds the URL identifier of the portal and its SEO title and description per language. URL Path is filled in automatically from it (refer-a-friend) and cannot be edited.

Do not change the URL without the development team. The website learns the list of portal URLs during a build, so a new URL only works after the next build, and every link to the old URL breaks. The same goes for creating a new Protected Area.

Pages

Pages (pages) adds sub pages to the area, shown in a menu next to the dashboard. The therapist area uses this. Leave it empty for Refer a Friend: without pages there is no menu and the dashboard uses the full width.

Bottom content blocks

Bottom content blocks (bottomContentComponents) are the sections shown below the dashboard, for example an explanation of the steps or a FAQ. You can use Text Section, Grid, FAQ Section, Infobox, Cta, Image Text Component and a few others.

The same rules as on the landing page apply: keep the amounts in line with the real settings and publish every language.

The share section in the portal links to Terms and Conditions. That link goes to the shop's general terms page, the content page with the URL terms. Put the program's conditions on that page. See Content Pages.

Portal texts

All texts on the dashboard are Static Words. Their keys start with FriendReferral., for example FriendReferral.share_section_title ("Share your referral code") or FriendReferral.claim_voucher ("Claim voucher"). In Hygraph navigate to Content, select Static Word under DEFAULT VIEWS and search for FriendReferral to see them all.

Portal texts

  • Keep placeholders like {discount}, {amount}, {count} and {days} exactly as they are. The shop fills in the real amount or number there.
  • Changes to Static Words need a build to show. Builds run automatically at night, and can be requested via the Slack channel #help-commercetools-hygraph. See Static Words and Page revalidation.
  • Some messages the program shows live under Common.:
    • Common.error_discount_code_new_customers_only: the code was entered by a customer who ordered in the last 12 months.
    • Common.error_discount_code_own_referral_code: a customer entered their own referral code.
    • Common.error_discount_code_login_required: someone who is not logged in entered a referrer's voucher. Vouchers only work when logged in.
    • Common.error_discount_code_already_applied: the cart already has a code.
    • Common.error_discount_code_min_order_not_met: the cart is below the minimum, for example "Add €5.01 more to use this discount code". The code stays on the cart and activates once enough is added, so the text should say that, not that the code is invalid. When the missing amount is unknown, Common.error_discount_code_does_not_match_cart is shown instead.

These Common. keys are shared with all other discount codes, so a change shows everywhere.

Cart below the minimum

Ask the development team

Ask the development team, via #help-commercetools-hygraph, for:

  • Changing an amount, a minimum order value or how long a voucher stays valid
  • Changing the rules, for example who counts as a new customer or how often a code can be used
  • Starting the program on another brand or currency
  • Changing the portal URL, the customer group or creating a new Protected Area