Skip to main content

Merchant Help

 

Affirm Merchant Help

Promotional Messaging - Beta

Overview

Affirm promotional messaging components—monthly payment messaging and educational modals—show customers how they can use Affirm to finance their purchases. Our promotional messaging allows you to:

  • Dynamically display monthly payment pricing information  
  • Offer Prequalification  
  • Customize messaging and design with co-branded assets

This guide will review Affirm promotional messaging and tell you how to add it to your site.

Monthly payment messaging

Monthly payment messaging consists of concise copy that offers price-specific information and contains a link that triggers an educational product modal. Examples of monthly payment messaging include:

Screen Shot 2018-12-04 at 2.02.56 PM.png

Screen Shot 2018-12-04 at 2.03.34 PM.png

Screen Shot 2018-12-04 at 2.01.57 PM.png

Educational modals

Educational modals are pop-up windows that offer more information about Affirm. They also provide prequalification, which allows your customers to discover how much they qualify to spend with Affirm on your site early in their shopping process. After completing the application and finishing shopping, the prequalified amount is automatically applied at checkout when they select Affirm as their payment option. There are two types of educational modals:

  • Product modals provide price-specific information. Clicking the monthly payment message triggers the product modal.
  • Site modals offer general information about Affirm and do not include pricing information. Any HTML element can trigger a site modal, though these are typically links on Affirm-related landing pages, site banners, or your home page.

modal-image.png

Review our marketing guidelines for specific messaging, placement and layout guidance.

The steps for adding Affirm promotional messaging are:

  1. Determine Affirm promotional messaging placement
  2. Add Affirm.js
  3. Create promotional messaging components
  4. Add code to handle price changes
  5. Test and set live

Sandbox development

We recommend adding and testing promotional messaging in your development environment connected to our sandbox. To connect your development environment to our sandbox, you'll need to do the following:

1. Determine Affirm promotional messaging placement

If you’re integrating Affirm for the first time, you’ll need to go through a design process to determine where you want to include Affirm promotional messaging on your site and what the messaging should look like and say.

Please reach out to your Client Success Manager if you need help designing your messaging placement. Also, remember that Affirm must approve your messaging to ensure that it complies with regulatory guidelines. After your team finalizes the design, you can add the messaging to your site quickly.

2. Add Affirm.js

Add the Affirm.js embed code to the head of your global page template if you haven't already done so.

<!-- Affirm -->
<script>
 _affirm_config = {
   public_api_key:  "YOUR_PUBLIC_KEY",
   script:          "https://cdn1-sandbox.affirm.com/js/v2/affirm.js",
   session_id:      "YOUR_VISITOR_SESSION_ID"
 };
 (function(l,g,m,e,a,f,b){var d,c=l[m]||{},h=document.createElement(f),n=document.getElementsByTagName(f)[0],k=function(a,b,c){return function(){a[b]._.push([c,arguments])}};c[e]=k(c,e,"set");d=c[e];c[a]={};c[a]._=[];d._=[];c[a][b]=k(c,a,b);a=0;for(b="set add save post open empty reset on off trigger ready setProduct".split(" ");a<b.length;a++)d[b[a]]=k(c,e,b[a]);a=0;for(b=["get","token","url","items"];a<b.length;a++)d[b[a]]=function(){};h.async=!0;h.src=g[f];n.parentNode.insertBefore(h,n);delete g[f];d(g);l[m]=c})(window,_affirm_config,"affirm","checkout","ui","script","ready");
// Use your live public API Key and https://cdn1.affirm.com/js/v2/affirm.js script to point to Affirm production environment.
</script>
<!-- End Affirm -->

Be sure to use your public API key from the sandbox merchant dashboard for public_api_key and a session ID variable for the optional session_id to take advantage of additional analytics.

Your global page template is the only place where you need this embed code.

3. Create promotional messaging components

Add an HTML element everywhere you want to display an Affirm promotional messaging component. The element attributes (see below) determine which component displays. We generally recommend adding promotional messaging to your category, product, cart, and payment pages.

​​​​​​​Screen Shot 2018-12-04 at 1.45.14 PM.png

See the following examples for how to add promotional messaging components to your site.

To add monthly payment messaging and a product modal to your product page:

<p class="affirm-as-low-as" data-page-type="product" data-amount="your_price_variable"></p>

Be sure to use your page's price variable or price amount in USD cents (e.g., $100 = 10000) for data-amount.

To add monthly payment messaging and a product modal to your cart page:

<p class="affirm-as-low-as" data-page-type="cart" data-amount="your_price_variable"></p>

Be sure to use your page's price variable or price amount in USD cents (e.g., $100 = 10000) for data-amount.

To add a site modal to a text link on your home page:

<a class="affirm-site-modal" data-page-type="homepage">Learn more</a>

To add a site modal to a banner link:

<a class="affirm-site-modal" data-page-type="banner"><img src="https://cdn-assets.affirm.com/images/banners/300x50.png"></a>

In each HTML element, be sure to include the data-page-type attribute corresponding to the page where that promotional messaging component is placed. The data-page-type attribute allows you to customize messaging in the future without development work. By default, promotional messaging on product pages have prequalification enabled, but you can work with your Client Success Manager to change this and configure additional customizations. See the links below for additional sample code.

HTML attributes

Attribute Type Description
class string

Determines the Affirm promotional messaging component to display. Possible values are:

  • affirm-as-low-as: Displays monthly payment messaging
  • affirm-site-modal: Displays educational site modal
  • affirm-product-modal: Displays educational product modal

Required

data-amount integer The loan amount passed to display price specific messaging. Value in USD cents (e.g. $100 = 10000). Optional
data-page-type string

Identifies your promotional messaging so Affirm can apply the necessary customizations based on which page they are displayed. Possible values are:

  • homepage: Your site's homepage
  • landing: A landing page that describes Affirm
  • search: Your site's search results page
  • category: Your site's homepage
  • product: A product description page
  • cart: A landing page that describes Affirm
  • payment: The payment selection page
  • banner: A banner image (use for any promotional messaging triggered by your banner or image regardless of page location)

Required

data-affirm-type string

Sets the Affirm logo type. Default displays Affirm logo image. Possible values:

  • text: Displays Affirm logo in plain text
  • symbol: Displays Affirm logo as a symbol

Optional

data-affirm-color string

Sets the Affirm logo color. Default displays blue Affirm logo. Possible value:

  • black: Displays black color Affirm logo
  • white: Displays white color Affirm logo

Optional

data-category string Identifies the product category associated with the messaging for analytics tracking (e.g., electronics, furniture). Optional
data-brand string Identifies the brand category associated with the messaging for analytics tracking (e.g., Samsung, Goodyear). Optional
data-sku string Identifies the SKU associated with the messaging for analytics tracking (e.g., ABC123, SMSNG-50-TV). Optional
data-promo-id string Customizes the messaging with different styling, copy, or loan terms. Overrides customizations provided by data-page-type. Optional

Monthly payment messaging (affirm-as-low-as) usually display price-specific information (requires data-amount) and are typically used with the following data-page-types:

  • category
  • product
  • cart
  • payment

Since site modals (affirm-site-modal) do not display price-specific information, they are typically used with the following data-page-types:

  • homepage
  • banner
  • landing
  • search

If you don’t pass data-page-type, the component will use a default setting.

Customize monthly payment messaging

You can customize the messaging to say anything you'd like, however, Affirm will need to approve it. Popular messaging examples include:

“As low as”

As low as {payment}/mo with [affirm_logo]. Learn more.
As low as {payment}/month at {lowest_apr}% APR with [affirm_logo]. Learn more.
As low as {payment}/month with [affirm_logo]. Learn more.
For as low as {payment}/month with [affirm_logo]. Learn more.
Financing as low as {payment}/month with [affirm_logo]. Learn more.

“Starting at”

Starting at {payment}/month at {lowest_apr}% APR with [affirm_logo]. Learn more.
Starting at {payment}/month with [affirm_logo]. Learn more.

APR

{apr_range}% APR financing for {payment}/month with [affirm_logo]. Learn more.
{apr_range}% APR starting at {payment}/month with [affirm_logo]. Learn more.
Affirm monthly payments; rates from {apr_range}% APR. Learn more.

Generic

Monthly payments with [affirm_logo]. Learn more.

You can also:

  • Replace the Affirm logo with plain text (data-affirm-type = "text")
  • Change the Affirm logo color to black (data-affirm-color = "black")
  • Remove the Learn more link

Customize educational modals

You can customize your modals by adding a hero image and a logo with the following dimensions:

  • Hero image @2x: 960px width x 1462px height
  • Hero image @1x: 480px width x 731px height
  • Logo image @2x: 400px width x 112px height
  • Logo image @1x: 200px width x 56px height

4. Add code to handle price changes

The price displayed on your product or cart pages may change due to product variants, quantity changes, etc. If your Affirm promotional messaging displays before the price update, the messaging will be inaccurate. To keep messaging updated, implement this refresh function into your price change callback function:

affirm.ui.refresh();

Page reload

If the product’s price or the Affirm promotional messaging display after the page loads, or if you included the above refresh function statically on the page, wrap it in the affirm.ui.ready() callback function. Doing so ensures that the page does not call the refresh function before Affirm.js initializes.

affirm.ui.ready(function(){
    affirm.ui.refresh();
});

Price update

When the price updates on your page, call the refresh function in the same callback function that handles your price change event.

//Add to an existing callback that fires when the price updates
priceUpdateEventHandler(){
    changePriceHandler(newPrice);
}

function updateAffirmPromos(newPrice){
    //Update the wrapper elements' attributes in the DOM
    document.getElementById('affirmProductModal').setAttribute('data-amount',newPrice);
    document.getElementById('affirmLearnMore').setAttribute('data-amount',newPrice);
  
    //Call affirm.ui.refresh to re-render the promotional messaging componenets
    affirm.ui.refresh(); 
}

Detect modal close

When an education modal is closed (non-prequal), you can detect that event by using the following code:

affirm.events.on('learnMore:close',function(){console.log('fired')});

5. Test and set live

If you're implementing promotional messaging as part of your initial integration, then don't connect to our live environment until you've tested your entire integration.

Confirm that all of your Affirm promotional messaging components display as expected.

After testing everything, update the script parameter in the Affirm.js embed code to point to our live environment at https://cdn1.affirm.com and replace the public_api_key parameter with your live public API key found at https://affirm.com/dashboard/#/apikeys.

After you’ve connected to our live environment, you’re ready to deploy to your production environment.