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:

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:

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.

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.

• Orders Management: provides information about affiliates’ orders. The page enables you to filter data in multiple ways and export it via email.

  

• Commissions Management: allows you to manage affiliates’ commissions and import information using files with . CSV or . XLSX extension.

  

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

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.

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.

2. 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.

3. Click on SAVE.

The following message will be displayed:

Your information was submitted successfully.

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.

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:

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.

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:

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:

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.

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

• Affiliate’s page customization
• Props
• CSS customization

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

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.

{
"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": {
"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": {
"children": ["affiliate-form"]
}
}

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.

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

affiliate-validator and affiliate-profile-validator props

affiliate_url_monitoring props

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

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.

8. 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.

Affiliate Orders Export Template

Commissions By Sku Export Template