Affiliates Program app

📘

For the Affiliates Program app, an affiliate is different from the standard definition of affiliate in VTEX. In the app's context, an affiliate is anyone who associates with a VTEX store to promote sales while receiving a commission.


The Affiliates Program app creates a specific URL of your VTEX store for each of your affiliates, and every URL is targeted with a parameter that identifies the affiliate. When an affiliate shares their URL with shoppers, and they buy something through that link, the affiliate earns a commission over sales.

The image below is an example of an affiliate’s page to be shared with shoppers:


29892989

The app also creates a profile page for the affiliate to keep track of orders and commissions, as you will see in the next section. Affiliates do not need access to your VTEX store Admin in order to access their profile page, which looks like the following image:


29872987

The Affiliates Program app’s main characteristics and behavior are the following:

  • The app provides pages and dashboards in your VTEX Admin, allowing your store to manage affiliates, orders, and commissions.
  • The merchant using a VTEX store can register an affiliate by filling out a form. More information on the next section.
  • The merchant using a VTEX store configures a default affiliates’ commission percentage over all products. It is possible to configure a specific commission for an SKU, and that configuration is prioritized over the default value.
  • The affiliates’ URLs can be customized to show specific products and guide the customer’s user experience.

Affiliates Program in VTEX Admin

After installing and configuring the app, you will find three pages in your VTEX Admin:

  • Affiliate Management: allows you to add new affiliates and manage the existing ones. You can add a new affiliate by clicking on the button Add affiliate and filling out the form.

13661366
  • Orders Management: provides information about affiliates’ orders. The page enables you to filter data in multiple ways and export it via email.
13661366
  • Commissions Management: allows you to manage affiliates’ commissions and import information using files with .CSV or .XLSX extension.
13661366

Compatibility

The Affiliates Program app is compatible only with stores using VTEX IO, so make sure you fit the criteria. Stores using Legacy CMS or Headless CMS are not compatible.


Installation

To install the Affiliates Program app, follow the steps below:

  1. In the VTEX App Store, log into your VTEX store’s account.
  2. Go to the Affiliates Program app page.
  3. Click on GET APP.
  4. In your cart in the VTEX App Store, click on PLACE ORDER.
  5. Click on GO TO INSTALL PAGE.
  6. In the VTEX Admin, click on INSTALL.

The app settings will appear in your VTEX Admin under Other > Affiliates, and you will see a page like the image below:

If using the New VTEX Admin, you will find the app settings under Apps > Affiliates.


13661366

In Settings, you will define for how long the lead will be valid and set a default commission percentage. To do so, follow the steps below:

  1. Fill in the Lead duration in days field with the number of days you wish to configure the lead. It is the lead that sets the priority of an affiliate to receive commissions.

🚧

Every affiliate has its own unique identification code, which is the Affiliate ID. When a shopper buys something through the affiliate's URL, the Affiliate ID is linked to the shopper for the period configured in this step - 60 days by default. If within the lead duration that shopper makes a second purchase, whether by accessing the store in an organic way, or through another affiliate's URL, the Affiliate ID of the first affiliate is prioritized and ensures commission. Note that the Affiliate ID for the app's context is not the Affiliate ID in the standard definition of affiliate in VTEX.


  1. Fill in the Default value to be used for sku commission field with the percentual you want to set to determine the affiliates’ commission over sales. Use numbers only, decimals are not allowed.
  2. Click on SAVE.

The following message will be displayed:

Your information was submitted successfully.


Configuration

You will need to access your VTEX store’s code to set up the app and the affiliate’s URL, as shown in the following sections.


Set up the Affiliates Program app

Open your store's Store Theme app directory in your code editor and add the Affiliates Program app to your theme's manifest.json file inside peerDependencies, as shown below:


"peerDependencies": {
  "vtex.affiliates": "1.x"
 }

When you add the Affiliates Program app as a dependency, the app exports theme blocks used to create pages on the storefront: affiliate, affiliate-profile, and affiliate-form. These pages will be available with a default layout:

  • Affiliate’s page: the page the affiliate sends to shoppers based on your VTEX store storefront. The URL is {storeName.com}/affiliates/{affiliateSlug}.
  • Affiliates profile page: a page where the affiliate can see orders made through their URL and analyze a dashboard with different metrics. The URL is {storeName.com}/affiliates/{affiliateSlug}/profile.
  • Affiliate’s form: a page with a form to be filled by anyone who wants to become an affiliate. The URL is {storeName.com}/affiliate/form.

To access the first two pages, you will have to configure an affiliate to be able to replace {affiliateSlug} with a valid slug.


Set up a shareable URL

For the affiliate to be able to share their URL, you will need to add the affiliate-url-monitoring block into the header of your theme. That block seeks parameters with a valid affiliate slug to add the affiliate’s information to the purchase.

To do so, check out the example below:


"header-layout.desktop": {
    "children": [
+     "affiliate-url-monitoring",
      "flex-layout.row#1-desktop",
      "flex-layout.row#3-desktop",
    ]
  },

    "header-layout.mobile": {
    "children": [
+     "affiliate-url-monitoring",
      "flex-layout.row#1-desktop",
    ]
  }

After that, the affiliate will share a URL with the parameter targeting with their slug as value so that the affiliate’s information is associated with the sale. See an example in the table below:


Example URLBehavior
https://storeName.com/product/pURL without the targeting parameter, which does not identify the affiliate.
https://storeName/product/p?targeting=affiliateNameURL with the targeting parameter, which links the shopper’s purchase to the affiliate.

It is possible to change the parameter property used for the affiliate to share the URL by changing the code in props. You can also change it in VTEX Admin, by accessing CMS > Site Editor > Blocks > Affiliate Monitoring and editing the Parameter field, as shown in the image below:

If using the New VTEX Admin, go to Storefront > Site Editor > Blocks > Affiliate Monitoring.


261261

Advanced configurations

You can customize the appearance and content of the affiliate’s page - {storeName.com}/affiliates/{affiliateSlug}, as explained in the next sections:


Affiliate’s pages customization

The default implementation of the affiliate’s page is the following:


BlockRoute
store.affiliates interface/affiliates/:slug
store.affiliates-profileaffiliates/:slug/profile
store.affiliate-formaffiliate/form

To customize these pages, follow the steps below:

  1. Open your store's Store Theme app directory in your code editor.

  2. Go to store/blocks.

  3. Create the following files:

    • affiliates.jsonc
    • affiliates-profile.jsonc
    • affiliates-form.jsonc
  4. Copy the respective block’s code – you will find them below.

  5. Paste the code in the corresponding file. For example, paste the store.affiliates JSON in the affiliates.jsonc file.

  6. Customize the code as you wish.

  7. Repeat steps 4 to 6 for each of the three blocks.

  8. Deploy the changes.


store.affiliates

{
  "store.affiliates": {
    "blocks": ["affiliate-validator"]
  },

  "affiliate-validator": {
    "props": {
      "Valid": "affiliate-template",
      "Invalid": "affiliate-invalid-template"
    }
  },

    "affiliate-template": {
    "children": [
      "affiliate-store-name",
      "flex-layout.row#banner",
      "affiliate-profile-button",
      "search-result-layout.customQuery#affiliate"
    ]
  },

  "flex-layout.row#banner": {
    "children": ["image#affiliate-banner"]
  },

  "image#affiliate-banner": {
    "props": {
      "src": "https://upload.wikimedia.org/wikipedia/commons/thumb/a/a9/VTEX_Logo.svg/400px-VTEX_Logo.svg.png"
    }
  },

  "search-result-layout.customQuery#affiliate": {
    "props": {
      "querySchema": {
        "skusFilter": "ALL_AVAILABLE",
        "simulationBehavior": "default",
        "queryField": "137",
        "mapField": "productClusterIds",
        "facetsBehavior": "Dynamic"
      }
    },
    "blocks": [
      "search-result-layout.desktop",
      "search-result-layout.mobile",
      "search-not-found-layout"
    ]
  }, 

  "affiliate-invalid-template": {
    "children": ["rich-text#invalid-affiliate"]
  },

  "rich-text#invalid-affiliate": {
    "props": {
      "textAlignment": "CENTER",
      "textPosition": "CENTER",
      "text": "**Affiliate does not exist or has not been approved**",
      "font": "t-heading-1"
    }
  }


}

store.affiliates-profile

{
  "store.affiliates-profile": {
    "children": ["affiliate-profile"]
  },

  "affiliate-profile": {
    "children": ["affiliate-profile-topbar", "affiliate-profile-validator"]
  },

  "affiliate-profile-validator": {
    "props": {
      "Valid": "flex-layout.row#profile",
      "Invalid": "rich-text#profileerror"
    }
  },

  "rich-text#profileerror": {
    "props": {
      "text": "### Faça o login com a conta correta do afiliado para acessar as informações",
      "textAlignment": "CENTER",
      "textPosition": "CENTER"
    }
  },

  "flex-layout.row#profile": {
    "children": ["flex-layout.col#profile"]
  },

  "flex-layout.col#profile": {
    "children": [
      "affiliate-profile-title",
      "affiliate-profile-totalizer",
      "affiliate-profile-table"
    ]
  },

}

store.affiliate-form

{
  "store.affiliate-form": {
    "children": ["affiliate-form"]
  }
}

Props

You will have to configure two specific component types with props for them to work correctly.

affiliate-validator and affiliate-profile-validator props


Prop nameTypeDescriptionDefault value
validstringSet the block name that will be rendered if the affiliate is valid.affiliate-template
invalidstringSet the block name that will be rendered if the affiliate is invalid.affiliate-invalid-template

affiliate_url_monitoring props

Prop nameTypeDescriptionDefault value
parameterstringParameter name that will be used to validate the URL the affiliate shared.targeting

CSS customization

If you wish to apply CSS customizations to the Affiliates Program app blocks, check out Using CSS Handles for store customization.


CSS Handles
affiliateStoreName
affiliateProfileTitle
profileButtonContainer

Email templates

The Affiliates Program app allows your VTEX store to export spreadsheets with information about the affiliates' orders and commissions. Exported spreadsheets will be sent via email to the VTEX Admin user.

For this configuration, you need to create two email templates on the Message Center:

  • Affiliate Orders Export Template
  • Commissions By Sku Export Template

To create a new custom email template, follow the steps below:

  1. In your VTEX Admin, go to Customer > Message Center > Templates.

  2. Click on the New Template button.

  3. Check the Enable sending emails flag.

  4. Fill in the fields that appear.

    You can use the image below as a reference, but use your information.

12091209
  1. Copy the Affiliate Orders Export Template code - you will find it below.

  2. Paste it in the Html section.

  3. Change it as you wish.

    You can scroll down the page to check the preview.

  4. Click on Save.


After creating the Affiliate Orders Export Template, repeat the process to create the Commissions By Sku Export Template. Use the image below as an example for step 4. On step 5, copy the Commissions By Sku Export Template code, which can be found at the end of this section.


12031203

Affiliate Orders Export Template

<!DOCTYPE html>
<html lang="pt-br">

<head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
    <meta name="viewport" content="initial-scale=1.0">
    <!-- So that mobile webkit will display zoomed in -->
    <meta name="format-detection" content="telephone=no">
    <!-- disable auto telephone linking in iOS -->
    <title>{{_accountInfo.TradingName}}</title>
    <style type="text/css">
        p {
            font-family: Fabriga, -apple-system, BlinkMacSystemFont, avenir next, avenir, helvetica neue, helvetica, ubuntu, roboto, noto, segoe ui, arial, sans-serif;
        };
        .vtex-button {
            border-width: .125rem;
            border-style: solid;
            font-weight: 500;
            vertical-align: middle;
            padding: 0;
            line-height: 1;
            border-radius: .25rem;
            min-height: 2.5rem;
            box-sizing: border-box;
            font-family: Fabriga, -apple-system, BlinkMacSystemFont, avenir next, avenir, helvetica neue, helvetica, ubuntu, roboto, noto, segoe ui, arial, sans-serif;
            font-size: 1rem;
            text-transform: uppercase;
            letter-spacing: 0;
            background-color: #134cd8;
            border-color: #134cd8;
            color: #fff;
            cursor: pointer;
        };
    </style>
</head>

<body marginwidth="0" marginheight="0" bgcolor="#fff" style="padding:0px 0px;color:#333;" leftmargin="0" topmargin="0">
    <!-- 100% wrapper (grey background) -->
    <table width="100%" height="100%" cellpadding="0" cellspacing="0" border="0" align="left" valign="top">
        <tbody>
            <tr>
                <td align="center" valign="top">
                    <table width="100%" style="max-width: 36rem;" align="center" cellpadding="0" cellspacing="0"
                        border="0" valign="top">
                        <tbody>
                            <tr>
                                <td>
                                    <div
                                        style="border:1px solid #e3e4e6;border-radius:8px;margin-top:1rem;margin-bottom:1rem;padding-top:3rem;padding-right:3rem;padding-bottom:3rem;padding-left:3rem">
                                        <img src="https://master--qamarketplace.myvtex.com/_v/public/assets/v1/published/[email protected]/public/react/cdbfb2a8b730a7ee840752d7af7ddc1c.png"
                                            width="77px" height="28px"
                                            style="display:block;outline:none;border:none;text-decoration:none"
                                            class="CToWUd">
                                        <p style="font-size:24px;color:#25354d;margin-bottom:32px">
                                            <strong>Planilha de pedidos de afiliados exportada</strong></p>
                                        <p style="font-size:16px;color:#3f3f40;margin-bottom:32px">
                                            Olá,</p>
                                        <p style="font-size:16px;color:#3f3f40">
                                            Segue o link para baixar a planilha pedidos de afiliados.
                                        </p>
                                        <div style="margin-bottom: 24px">
                                            <a href="{{link}}" download>
                                                <button
                                                    style="border-width: .125rem; border-style: solid; font-weight: 500; vertical-align: middle; padding: 0; line-height: 1; border-radius: .25rem; min-height: 2.5rem;  box-sizing: border-box; font-family: Fabriga, -apple-system, BlinkMacSystemFont, avenir next, avenir, helvetica neue, helvetica, ubuntu, roboto, noto, segoe ui, arial, sans-serif;  font-size: 1rem;  text-transform: uppercase;  letter-spacing: 0; background-color: #134cd8; border-color: #134cd8;  color: #fff; cursor: pointer;"
                                                    type="button">
                                                    <div style="display: flex; align-items: center; justify-content: center; height: 100%; padding-left: 1.5rem; padding-right: 1.5rem; padding-top: 0.25rem; padding-bottom: 0.25rem;">
                                                        Baixar Planilha
                                                    </div>
                                                </button>
                                            </a>
                                        </div>
                                        <p style="margin-bottom:4px;font-size:16px;color:#3f3f40">
                                            Abraços,</p>
                                        <p style="margin-top:0px;font-size:16px;color:#3f3f40">
                                            VTEX</p><br>
                                        <p style="font-size:12px;color:#727273;margin-bottom:0px">
                                            O link para download é válido por 24 horas. Após esse tempo, será necessário realizar a exportação novamente.
                                        </p>
                                        <div
                                            style="color:#e3e4e6;border-top:1px solid #e3e4e6;border-bottom:0px solid #e3e4e6;margin-bottom:2rem;margin-top:1rem">
                                        </div>
                                        <p style="font-size:12px;color:#727273;margin-bottom:0px">
                                            Esse email é enviado automaticamente e não recebe respostas.
                                        </p>
                                        <p style="font-size:12px;color:#727273;margin-top:.25rem;margin-bottom:0px">
                                            Precisa de ajuda? <a href="https://help.vtex.com/?locale=pt" alt="VTEX Help"
                                                style="font-weight:bold;color:#3F3F40">Fale Conosco</a>
                                        </p><br>
                                        <p style="font-size:12px;color:#727273;margin-bottom:0px">
                                            © VTEX Praia de Botafogo, 300, 3º Andar, Botafogo, Rio de Janeiro, RJ,
                                            22250-040
                                        </p>
                                    </div>
                                </td>
                            </tr>
                        </tbody>
                    </table>
                </td>
            </tr>
        </tbody>
    </table>
    <!--/600px container -->
    <!--/100% wrapper-->
</body>
</html>

Commissions By Sku Export Template

<!DOCTYPE html>
<html lang="pt-br">

<head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
    <meta name="viewport" content="initial-scale=1.0">
    <!-- So that mobile webkit will display zoomed in -->
    <meta name="format-detection" content="telephone=no">
    <!-- disable auto telephone linking in iOS -->
    <title>{{_accountInfo.TradingName}}</title>
    <style type="text/css">
        p {
            font-family: Fabriga, -apple-system, BlinkMacSystemFont, avenir next, avenir, helvetica neue, helvetica, ubuntu, roboto, noto, segoe ui, arial, sans-serif;
        };
        .vtex-button {
            border-width: .125rem;
            border-style: solid;
            font-weight: 500;
            vertical-align: middle;
            padding: 0;
            line-height: 1;
            border-radius: .25rem;
            min-height: 2.5rem;
            box-sizing: border-box;
            font-family: Fabriga, -apple-system, BlinkMacSystemFont, avenir next, avenir, helvetica neue, helvetica, ubuntu, roboto, noto, segoe ui, arial, sans-serif;
            font-size: 1rem;
            text-transform: uppercase;
            letter-spacing: 0;
            background-color: #134cd8;
            border-color: #134cd8;
            color: #fff;
            cursor: pointer;
        };
    </style>
</head>

<body marginwidth="0" marginheight="0" bgcolor="#fff" style="padding:0px 0px;color:#333;" leftmargin="0" topmargin="0">
    <!-- 100% wrapper (grey background) -->
    <table width="100%" height="100%" cellpadding="0" cellspacing="0" border="0" align="left" valign="top">
        <tbody>
            <tr>
                <td align="center" valign="top">
                    <table width="100%" style="max-width: 36rem;" align="center" cellpadding="0" cellspacing="0"
                        border="0" valign="top">
                        <tbody>
                            <tr>
                                <td>
                                    <div
                                        style="border:1px solid #e3e4e6;border-radius:8px;margin-top:1rem;margin-bottom:1rem;padding-top:3rem;padding-right:3rem;padding-bottom:3rem;padding-left:3rem">
                                        <img src="https://master--qamarketplace.myvtex.com/_v/public/assets/v1/published/[email protected]/public/react/cdbfb2a8b730a7ee840752d7af7ddc1c.png"
                                            width="77px" height="28px"
                                            style="display:block;outline:none;border:none;text-decoration:none"
                                            class="CToWUd">
                                        <p style="font-size:24px;color:#25354d;margin-bottom:32px">
                                            <strong>Planilha de comissionamento por SKU exportada</strong></p>
                                        <p style="font-size:16px;color:#3f3f40;margin-bottom:32px">
                                            Olá,</p>
                                        <p style="font-size:16px;color:#3f3f40">
                                            Segue o link para baixar a planilha de comissionamento por SKU.
                                        </p>
                                        <div style="margin-bottom: 24px">
                                            <a href="{{link}}" download>
                                                <button
                                                    style="border-width: .125rem; border-style: solid; font-weight: 500; vertical-align: middle; padding: 0; line-height: 1; border-radius: .25rem; min-height: 2.5rem;  box-sizing: border-box; font-family: Fabriga, -apple-system, BlinkMacSystemFont, avenir next, avenir, helvetica neue, helvetica, ubuntu, roboto, noto, segoe ui, arial, sans-serif;  font-size: 1rem;  text-transform: uppercase;  letter-spacing: 0; background-color: #134cd8; border-color: #134cd8;  color: #fff; cursor: pointer;"
                                                    type="button">
                                                    <div style="display: flex; align-items: center; justify-content: center; height: 100%; padding-left: 1.5rem; padding-right: 1.5rem; padding-top: 0.25rem; padding-bottom: 0.25rem;">
                                                        Baixar Planilha
                                                    </div>
                                                </button>
                                            </a>
                                        </div>
                                        <p style="margin-bottom:4px;font-size:16px;color:#3f3f40">
                                            Abraços,</p>
                                        <p style="margin-top:0px;font-size:16px;color:#3f3f40">
                                            VTEX</p><br>
                                        <p style="font-size:12px;color:#727273;margin-bottom:0px">
                                            O link para download é válido por 24 horas. Após esse tempo, será necessário realizar a exportação novamente.
                                        </p>
                                        <div
                                            style="color:#e3e4e6;border-top:1px solid #e3e4e6;border-bottom:0px solid #e3e4e6;margin-bottom:2rem;margin-top:1rem">
                                        </div>
                                        <p style="font-size:12px;color:#727273;margin-bottom:0px">
                                            Esse email é enviado automaticamente e não recebe respostas.
                                        </p>
                                        <p style="font-size:12px;color:#727273;margin-top:.25rem;margin-bottom:0px">
                                            Precisa de ajuda? <a href="https://help.vtex.com/?locale=pt" alt="VTEX Help"
                                                style="font-weight:bold;color:#3F3F40">Fale Conosco</a>
                                        </p><br>
                                        <p style="font-size:12px;color:#727273;margin-bottom:0px">
                                            © VTEX Praia de Botafogo, 300, 3º Andar, Botafogo, Rio de Janeiro, RJ,
                                            22250-040
                                        </p>
                                    </div>
                                </td>
                            </tr>
                        </tbody>
                    </table>
                </td>
            </tr>
        </tbody>
    </table>
    <!--/600px container -->
    <!--/100% wrapper-->
</body>

</html>