About promotional messaging for global integrations

❗️

Due to international regulations, customizing Affirm's promotional messaging is prohibited.

For Affirm hosted promos, changing or hard coding parts of the Affirm promotional messaging language is prohibited and any additional customizations outside of what is listed below must be made by Affirm or have explicit approval from Affirm's compliance team. Please reach out to your Client Success Manager with any additional questions.

Marketing guidelines

Following our Affirm CA 2022 Brand Guidelines for Merchants helps you ensure that your messaging and communications are compliant and maintain the quality of the Affirm brand. The guidelines and this page include:

• Branding specifications (logo size, color).
• Homepage messaging guidelines (layout and approved messaging).
• Product, category, cart, and payment page messaging guidelines.
• Educational modals overview (named Learn More modals).
• Email marketing guidelines (layout and approved messaging).
• Social media marketing guidelines.

All of your Affirm-related marketing content must be available to all of your customers.

Quickstart

Monthly payment messaging and educational modals show customers how they can use Affirm to finance their purchases. Our promotional messaging enables you to:

• Dynamically display monthly payment pricing information. 
• Offer Pre-qualification.  

Below, we explain Affirm promotional messaging and how to add it to your site. Once you determine where to display the Affirm pay-over-time-messaging on your website, there are three steps to render and ensure it works correctly.

1. Add Affirm.js

Our global integration features extended parameters to reach international customers, which consists of an exposed locale and country-code field in the Affirm config.

Including the Affirm.js script

Add the Affirm.js embed code to the head of your global page template, if you haven't already. This communicates with Affirm to help calculate the “Starting at $x/mo” messaging based on the financing offerings on your website.

	_affirm_config = {
		public_api_key: "{YOUR_PUBLIC_API_KEY}",
		script: "https://cdn1-sandbox.affirm.com/js/v2/affirm.js",
		locale: "fr_CA",
		country_code: "CAN",
	};

(function(m,g,n,d,a,e,h,c){var b=m[n]||{},k=document.createElement(e),p=document.getElementsByTagName(e)[0],l=function(a,b,c){return function(){a[b]._.push([c,arguments])}};b[d]=l(b,d,"set");var f=b[d];b[a]={};b[a]._=[];f._=[];b._=[];b[a][h]=l(b,a,h);b[c]=function(){b._.push([h,arguments])};a=0;for(c="set add save post open empty reset on off trigger ready setProduct".split(" ");a<c.length;a++)f[c[a]]=l(b,d,c[a]);a=0;for(c=["get","token","url","items"];a<c.length;a++)f[c[a]]=function(){};k.async=
  !0;k.src=g[e];p.parentNode.insertBefore(k,p);delete g[e];f(g);m[n]=b})(window,_affirm_config,"affirm","checkout","ui","script","ready","jsReady");

Locale

The locale parameter enables Affirm to identify which locale you are serving your site in for any particular user. For example, you're rendering your site in Canadian French because the user's browser setting detected Canadian French. You can provide Affirm with the user's language setting by passing it in the locale parameter. Affirm then reads the locale and translates the pages accordingly, thus, matching the language the user had seen on your site. We do not attempt to read the user's locale directly.

Country_code

The country_code parameter represents the country of legal incorporation of your store, which is shown to any given user. So, if you are showing your Canadian website/store to a user and you have a legal presence in Canada, you pass CAN into the country_code parameter. This enables Affirm to determine which regulations to abide by and which banks to partner with for this transaction.

Additionally, Affirm expects an “Alpha 3” three-letter country code for this parameter. If nothing is sent, Affirm uses "USA".

Supported values

Affirm supports the following combinations for these arguments:

country_code:USA
locale:en_US
country_code:CAN
locale:en_CA
locale:fr_CA

When a:

• locale is not provided, the locale automatically uses en_US (English speaking US).
• country_code is not provided, the country_code automatically uses USA.

2. Create promotional messaging components

Add the affirm-as-low-as HTML element where you want to display an Affirm promotional messaging component. This renders the “Starting at $x/mo” messaging on the webpage. The element attributes, such as data-page-type, determine which component displays. We recommend adding promotional messaging to your category, product, cart, and payment pages. See the HTML Reference for more information.

3. Add code to handle price changes

The price displayed on your product or cart pages may change based on product variants, quantity changes, etc. If your Affirm promotional messaging displays before the price update, the messaging will be inaccurate. To maintain accurate messaging, add this refresh function to your price change callback function:

affirm.ui.refresh();

Page reload

If a product’s price or the Affirm promotional messaging displays after the page loads, or if you include the refresh function statically on the page, wrap the refresh function in the affirm.ui.ready() callback function to ensure 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 element IDs to promotional messaging components to easily access and modify their attributes. Note that we use example ID names below.

//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-prequa), you can detect that event by using the following code:

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

📘

The above script didn't work for your merchant?

Use the same code, but replace 'learnMore' with 'prequal', as shown below.

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

Examples

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>

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>

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, include the data-page-type attribute corresponding to the page where that promotional messaging component is placed. The data-page-type attribute enables you to customize messaging in the future without development work. Promotional messaging on product pages have pre-qualification automatically enabled, but you can work with your Client Success Manager to change this and configure additional customizations. See additional sample code below.

Monthly payment messaging with prequalification (single price):

Site modal: