Skip to main content

Merchant Help

 

Affirm Merchant Help

Promotional Messaging - Beta

Overview 

Affirm Promotional Messaging allows you to display the monthly payment price and educational modal on your site by using Affirm's API and runtime Javascript. The monthly payment messaging is dynamically generated into placeholder elements on your pages to inform customers about the availability of installment financing, which will help drive add to cart, increased average order value and conversion rates.

Integration

  1. Include the Affirm JS embed code to your page header template
  2. Add a placeholder HTML element for the monthly payment messaging and/or modal that you want to implement.
  3. Account for price changes by updating the 'data-amount' element and refreshing the Affirm UI.
  4. (optional) If you are using MFP, pass the promo-id which references the financing program that will be passed at checkout for this prospective purchase.

Affirm JS runtime

Include this Affirm Javascript runtime embed code the in the head of pages where Affirm promotional messaging will be displayed. You may already have this embed code present from a previous promotional messaging implementation, or on the page where Affirm checkout is integrated.

<script>
  _affirm_config = {
    public_api_key:  "XXXXXXXXXXXXXXX",
    script:          "https://cdn1-sandbox.affirm.com/js/v2/affirm.js"
  };
  (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>

Note: replace the 'public_api_key' value with your own public API key. The API key must match the Affirm-environment you're referencing ('sandbox' or 'live').

HTML wrapper

Add an HTML element for each Affirm promotional messaging component that you want displayed on a page. The wrapper element's name ('p', 'span', etc.) is arbitrary, as the implementation doesn't rely on specific names. Recommended element names are shown in the examples below.

The attributes of the wrapper element determine which component will be rendered at runtime:

Attribute name Usage Value type Accepted values Notes
class Determines the type of promotional messaging component to be rendered. String "affirm-as-low-as", "affirm-product-modal", "affirm-site-modal"  
data-amount The loan amount for monthly payment calculations and messaging. Integer Product or cart price in USD cents $499.99 = 49999
data-promo-id Renders the component with different styling, messaging, or loan terms. String Promo IDs are provided by your Affirm technical contact If an invalid Promo ID is provided, the default components will be rendered.

Placements

Monthly Payment Messaging
  • PDP - Below product price.
  • Cart - Below cart total.
  • Checkout - Inline with payment method description.
Product Modal
  • PDP - Inline with monthly payment messaging.
  • Any element which needs to display a price-specific informational modal on click.
Site Modal
  • Education/Landing page
  • Home page
  • Site banner
  • Any element which needs to display an informational modal on click.

Affirm-hosted banners to use

Promo IDs

A promo ID is an optional parameter that, if present, will display customized messaging in the rendered marketing components.

  • Promo IDs are only required if you want to customize the appearance or financing terms in Affirm marketing components.
  • Promo IDs are generated by Affirm staff, and you can reach out to Affirm Merchant Help
  • Promo IDs you're provided are unique to the customizations requested.
  • You can use that same promo ID across your entire site, for all components that should share those customizations.
  • If you want to display customizations, a promo ID must be present. 
  • An invalid or missing promo ID will result in the default presentation of the marketing components.

For example, if you're using the same messaging (and offering the same financing programs) across your entire site, you will only need to utilize one promo ID for all your marketing components on all pages.

Sandbox vs Live environment

When to use Sandbox

You should initially configure your JS embed code to use the Affirm Sandbox environment, and configure the HTML placeholders with your Promo and Modal IDs that are for the Sandbox environment. 

Going to Live environment

When you're ready to push to your production or staging environment, you can then update the JS embed code to use the Affirm Live environment, and update the HTML placeholders with your Promo IDs that are for the Live environment.

Refreshing Promos

The price displayed on your product or cart pages may update due to product variants, upsells, quantity changes, etc. If the Affirm promotional messaging component was rendered prior to the price update, the promotional messaging will no longer be accurate. To keep Affirm promotional messaging up to date, implement Affirm component updates into your price change callback:

UI refresh

This function can be called to re-render any Affirm promotional messaging components on the page. Most typically used when displayed prices are updated. 

affirm.ui.refresh();

After page load

If the price, and/or the Affirm components are being included after page load, or if the affirm.ui.refresh() function is being included statically on the page, you may need to wrap it in the affirm.ui.ready() callback. This ensures that the Affirm functions are not called before Affirm.js has been initialized.

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

Price updates

When the price updates on your page, you'll want to call affirm.ui.refresh() in the same callback that handles your 'price change' event.

Example
  //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(); 
  }

Monthly Payment Messaging

Display the monthly price for a product or cart with a customizable message, such as "Starting at [monthly_price] / month with [affirm_logo]" strings that can be included on product page, product gallery, and shopping cart for which Affirm financing is available:

Embed
  1. using HTML snippet as a placeholder from below 
    <p class="affirm-as-low-as" data-promo-id="XXXXXXXXXXXXX" data-amount="50000"></p>
  2. Include data-promo-id (provided by the Affirm Client Success Team) 
  3. Add your page's product or cart price variable to the data-amount field in the HTML placeholder above 
Design

Customization

You should work with the Affirm Client Success Team to select one of the following monthly payment pricing strings that can be included on product page, product gallery, and shopping cart for which Affirm financing is available:

For pricing strings that include the Affirm logo, choose from any of the following options:

  • "As low as"
    • As low as {payment}/mo with {affirm_logo}
    • As low as {payment}/month at {lowest_apr}% APR with {affirm_logo}
    • As low as {payment}/month with {affirm_logo}
    • or as low as {payment}/month with {affirm_logo}
    • Financing as low as {payment}/month with {affirm_logo}
       
  • "Starting at"
    • Starting at {lowest_apr}% APR at {payment}/month with {affirm_logo}
    • Starting at {payment}/month with {affirm_logo}
       
  • Rate
    • {apr_range}% APR financing for {payment}/month with {affirm_logo}
    • {apr_range}% APR starting at {payment}/month with {affirm_logo}
    • Affirm Monthly Payments; Rates From {apr_range}% APR
       
  • Generic
    • Monthly Payments with {affirm_logo}

You can also customize the  the monthly payment price for any product based on a few parameters:

  • data-affirm-type: Optional; Default value is set to Affirm logo. It can be changed to a value of "text" for plain text
  • data-affirm-color: Optional; Default value is set to blue. It can be changed to a value of "black" for the Affirm logo
  • data-learnmore-show: Optional; Default value is set to true. It can be changed to a value of "false"  

data-affirm-color

  •  
Example
<p class="affirm-as-low-as" data-promo-id="XXXXXXXXXXXXX" data-amount="50000" data-affirm-type="text" data-affirm-color="blue" data-learnmore-show="false"></p>

Product Modal

Embed

You can wrap any element on your page with a Product Modal, which will display an informational, price-specific modal when clicked. This allows you to use any of your page elements as the trigger to display an Affirm modal  .

  • data-amount: Price of the item (in cents)
  • data-promo-id: String provided by Affirm that specifies the specific product page pricing configuration that will be displayed on the page
  1. Put the HTML placeholder on your page:
    <a class="affirm-product-modal" data-amount="50000" data-promo-id="XXXXXXXXXXXXXX" > Learn more </a>
  2. Add your page's product or cart price variable to the data-amount field in the HTML placeholder above 
Design

 

Customization

You should work with the Affirm Client Success Team to configure your monthly payment pricing modals and submit assets for:

  • Hero_image:
    • @2x - width: 960px, height: 1462px
    • @1x - width: 480px, height: 731px
  • Logo:
    • @2x - width: 400px, height: 112px
    • @1x - width: 200px , height: 56px

Your Affirm Client Success Team can also help select among several options for the following configuration attributes to match the tone and aesthetic of your site:

  • Font style for text (only web fonts allowed)
  • Color (icons)

Site-Wide Modal

Embed
  1. Put the HTML placeholder on your page:
    1. As a text link:
      <a class="affirm-site-modal" data-promo-id="XXXXXXXXXXXXXX">Learn more</a>
      
    2. Or as a banner image:

      <a class="affirm-site-modal" data-promo-id="XXXXXXXXXXXXXX"><img src="https://cdn-assets.affirm.com/images/banners/300x50.png"></a>
    3. More examples of banner images here:
      Affirm_Marketing_Assets
       
  2. Add the Promo ID to the data-promo-id field in the HTML placeholder
 
Design

 

Customization

You should work with the Affirm Client Success Team to configure your monthly payment pricing modals and submit assets for:

  • Hero_image:
    • @2x - width: 960px, height: 1462px
    • @1x - width: 480px, height: 731px
  • Logo:
    • @2x - width: 400px, height: 112px
    • @1x - width: 200px , height: 56px

Your Affirm Client Success Team can also help select among several options for the following configuration attributes to match the tone and aesthetic of your site:

  • Font style for text (only web fonts allowed)
  • Color (icons)

Example Code

 

  1. Monthly Payment Price (As-Low-As)
  2. Monthly Payment Price Modal - https://jsfiddle.net/xwz8u3ya/
  3. Site-Wide Modal - https://jsfiddle.net/8q4oyosf/