Skip to main content

Merchant Help


Affirm Merchant Help

Promotional Messaging - Beta


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.

Educational Modals

  1. Affirm Promotional Messaging components trigger Educational Modals which present the customer with information about Affirm and the monthly price displayed.up


  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.
  5. (optional) Write new CSS rules for the rendered Promotional Messaging components

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.

  _affirm_config = {
    public_api_key:  "XXXXXXXXXXXXXXX",
    script:          ""
  (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 script to point to Affirm production environment.

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.


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. 


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.


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.

  //Add to an existing callback that fires when the price updates

  function updateAffirmPromos(newPrice){
      //Update the wrapper elements' attributes in the DOM
      //Call affirm.ui.refresh to re-render the promotional messaging componenets

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:

  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 


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". You may also want to set this to false if using an alternate, Prequalification-specific call-to-action (e.g., "Prequalify now.").




Monthly Payment Messaging's Educational Modals now support Prequalification. Prequalification is a new feature that allows your customers to discover how much they qualify to spend with Affirm on your site early in their shopping process.  This simple tool lets your customers shop with confidence. Shoppers who leveraged Prequalification during the feature beta program spent an average of up to 30% more per transaction - on top of the existing Affirm AOV lift.

Once a customer is prequalified, that prequalification will automatically be applied to their next Affirm checkout attempt on your site. No manual intervention or additional integration steps are required for Prequalification to function.

You can find more information about Prequalification here.


Prequalification can be added to the Educational Modals for your existing Monthly Payment Messaging with no changes, assuming that you're already using the latest embed code and configuring it with a Promo ID.  To start using the latest version of our Educational Modals, you can either follow the integration instructions above, or review our Educational Modal upgrade guide.

  1. Reach out to your Affirm contact, like your Client Success Manager, and request that they add Prequalification to your Educational Modals. 
  2. Affirm will provide you with a Promo ID to use in your Monthly Payment Messaging HTML embed code.
    • If you're already using a Promo ID, we can add Prequalification to that existing Promo ID, or create a new Promo ID for you to use.
  3. Enter the new Promo ID into the Monthly Payment Messaging HTML element, for example:
    <span class="affirm-as-low-as" data-promo-id="promo_set_123" data-amount="50000">

Once the new Promo ID has been added to the Affirm messaging on your pages, Prequalification will be enabled for the Educational Modals triggered by your "as low as" messaging.


Screen Shot 2018-03-12 at 9.06.17 PM.png


Prequalification-specific Monthly Payment Messaging ("As Low As")

The default call to action in Affirm Monthly Payment Messaging is 'Learn more'. The addition of Prequalification to our Educational Modals will  can have the "Starting your at $10/mo with Affirm.  Monthly Payment Messaging that is more specific to Prequalification. 


  • "Starting at $10 a month with Affirm. Prequalify now"
  • "Starting at $10 a month with Affirm. See if you prequalify"

In order to setup this type of messaging, there are two main steps:

1. Inform your Affirm Client Success Manager that you'd like the Prequalification call to action added to your Monthly Payment Messaging. 

Your Affirm contact will add the new call to action (e.g., "Prequalify now") to a given Promo ID and communicate that to your team. You'll then use that specific Promo ID anywhere that you want this call to action to appear in the Monthly Payment Messaging.

2. Remove the default 'Learn more' call to action.

The 'Learn more' call to action is always appended by default, but it can be removed by setting the Monthly Payment Messaging HTML element's 'data-learnmore-show' attribute to 'false'.

For example:
<span class="affirm-as-low-as" data-promo-id="promo_set_defaul" data-learnmore-show="false"></span>

With the new call to action being added by the Prequalification-specific Promo ID, and the default 'Learn more' removed, the Monthly Payment Messaging will now appear as expected.

Exclude Prequalification from certain Educational Modals, if desired

Affirm Prequalification is enabled in Educational Modals when a Prequalification-enabled Promo ID is specified in the Monthly Payment Messaging's HTML embed code.

For example, 'promo_set_prequal' is setup with Prequalification enabled, and 'promo_set_default' does not have Prequalificaiton enabled, we should use 'promo_set_default' as the Promo ID anywhere that Prequalification messaging shouldn't be present.

Please work with your Client Success Manager to ensure that you have all the Educational Modal varients you'll need on your pages.


With Prequalification
<p class="affirm-as-low-as" data-promo-id="XXXXXXXXXXXXX" data-amount="50000" data-learnmore-show="false"></p>

Product Modal


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 



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

  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=""></a>
    3. More examples of banner images here:
  2. Add the Promo ID to the data-promo-id field in the HTML placeholder



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 -
  3. Site-Wide Modal -