Skip to main content

Merchant Help

 

Affirm Merchant Help

Monthly Payment Price in Marketing Messages

Overview

Affirm Monthly Payment Prices can be included in the marketing messages like emails, display ads, Google ads, Facebook ads, text messages, push notifications, etc. This document provides instructions on integration options available to include the Affirm Monthly Payment Price.


 

Integration

There are two ways to include Affirm Monthly Payment Messaging in any of the marketing messages:

  1. Monthly Payment Pricing from the HTML DOM
  2. Monthly Payment Messaging API

Monthly Payment Pricing from the DOM

This integration method is for those merchants that already have Affirm Monthly Payment Messaging on their website:   

  1. Load the example page that has Affirm On-Site Marketing embedded. This displays both ways that a merchant might have Affirm Monthly Payment Messaging integrated.
  2. Select the rendered Monthly Payment Messaging HTML element.
  3. Parse out the Monthly Payment Price.
  4. Include that Monthly Payment Price in your email templates, media messages, etc.
Full example page

This example page demonstrates both the current and legacy embed methods for Monthly Payment Messaging

HTML

Click here to download the HTML example page

JSFiddle

Current

HTML placeholder:

<span class="affirm-as-low-as" data-amount="CART_OR_PRODUCT_PRICE" data-affirm-type="text" data-affirm-color="blue">

JavaScript:

Promotional Messaging JS

Legacy

Example HTML placeholder:

<a id="learn-more" href="#"></a>

Example JavaScript:

<script>
  affirm.ui.ready( function() { updateAffirmAsLowAs( CART_OR_PRODUCT_PRICE ) } );
  function updateAffirmAsLowAs( amount ){
    if ( ( amount == null ) || ( amount < 1000 ) ) { return; }
    var options = {
      apr: "0.10",
      months: 12,
      amount: amount
    };
    try {typeof affirm.ui.payments.get_estimate;}
    catch (e) {return;}
    function handleEstimateResponse (payment_estimate) {
      var dollars = payment_estimate.payment_string;
      var a = document.getElementById('learn-more');
      var iText = ('innerText' in a)? 'innerText' : 'textContent';
      a[iText] = "Starting at $" + dollars + " a month. Learn More";
      a.onclick = payment_estimate.open_modal;
      a.style.visibility = "visible";
    };
    affirm.ui.payments.get_estimate(options, handleEstimateResponse);
  }
</script>

Selecting the Monthly Payment Messaging Placeholder

The Affirm monthly payment messaging on the product or cart page will only render after the page loads. Therefore, you will want to extract the monthly payment price from the DOM. You can select the element containing the monthly price in the following ways:

Current integration
  • Standard
    • Fixed class name of 'affirm-as-low-as'.
    • e.g., <div class="affirm-as-low-as"></div>
    • document.getElementsByClassName('affirm-as-low-as')[0];
      
  • Custom
    • Custom element class names are not supported. Element may have a merchant-defined ID.
       
Legacy integration
  • Standard
    • Fixed <a> element with ID of 'learn-more'.
    • e.g., <a id="learn-more"></a>
    • document.getElementbyId('learn-more')
      
  • Custom
    • Merchant-defined element ID that's also defined in the handleEstimateResponse() function.
    • e.g., <a id="affirm-monthly-price"></a>

Extracting the Monthly Payment Price

  • For all integration variations, the monthly price will be shown as a string, inside the placeholder element.
  • For legacy integrations, there will be a JavaScript variable that the payment estimate response is assigned to.

Extracting terms and disclosure information

  • There is no way for third-parties to programmatically retrieve terms and disclosures for a given monthly payment price returned from Affirm at this time
  • Terms and disclosures should be mapped to a merchant's available financing programs, assuming the lowest possible APR for a given range
  • Examples:
    • A merchant offers only standard terms of 10-30% APR, then monthly prices can be assumed to be calculated at 10% APR at 12 months. (6 months if between $50-100)
    • A merchant offers 0% APR, then monthly prices can be assumed to be calculated at 0% APR at 12 months when the corresponding 'data-promo-id' parameter value is detected.

Monthly Payment Messaging API 

Monthly Payment Messaging API facilitates the option of making real time requests to the get the Affirm monthly payment price.  

  1. Collect the loan amount, APR, and loan term length.
  2. Make a call to the Monthly Payment Messaging API. 
  3. Parse the JSON response. Pull out the monthly price and related messaging.
  4. Include that Monthly Payment Messaging in your email template, media messages, etc. 

Collect the loan details

  • Amount
    • Expressed in integer USD cents.
    • e.g.,$535.49 -> 53549
    • Maximum: 3000000
    • Minimum: 5000
       
  • APR
    • Expressed as a decimal percentage.
    • e.g., 10% -> 0.10
    • Should remain constant for a given merchant or merchant promotion
    • Maximum: 0.30
    • Minimum: 0.00
       
  • Term length
    • Expressed in months.
    • e.g., 12 months -> 12
    • Should remain constant for a given merchant or merchant promotion
    • Maximum: 18
    • Minimum: 3

Make the API call

Scenarios

Extracting the monthly price, terms, and disclosures

The response from the Monthly Payment Messaging API will look like this:

{"disclosure": "Based on the purchase price of $1352.00 at 10% APR for 12 months", "months": 12, "payment_string": "119", "payment": 11886}
  • Terms and disclosures are specific to the loan parameters (amount, APR, and term length)
  • Loan parameters depend on the financing programs that the merchant has available.
  • Any monthly payment price should also include in-line descriptions or a link to descriptions of the price calculation, such as:

    "Starting at $44 a month with Affirm for a product price of $500 and 10% APR over 12 months."

Tracking Affirm promotions

If you find that you are wanting to track what those financing programs or types of promotions are (and not just pulling in the rendered monthly price), that can be handled exclusively between you and the merchant. 

Merchants will be aware of what promo IDs they're using at a given time, and what messaging or financing programs those correlate to. Therefore, you should be able to maintain a mapping as part of the merchant's integration, such as:

  • 'data-promo-id'='ABC123' = zero-percent promotion
  • 'data-promo-id'=[blank] = standard 10-30% APR
  • 'data-promo-id'='something_else' = standard 10-30% APR

In addition, you can provide an ability to add tracking parameters to all the outgoing links that have Affirm branded messaging within the email templates, media messages, etc. Below is the list of parameters that can be appended as query parameters to the outgoing links (Ex: Affirm promotional messaging sends the customers to a cart page, the string used within the email template should add these parameters, https://www.example.com/cart?aff_cid=unique_value&aff_fm=t)

  • aff_cid="unique_value" (Required) - Unique value, either already available or created, which provides tracking information about the email service provider and/or the merchant
  • aff_fm="t" (Optional) - Forces the Affirm educational modal to open when a customer lands on the page where Affirm promotional messaging is available

Compliance

  • We all are responsible for making sure that financing programs are kept up-to-date so that 0% loan parameters are not communicated to users when that program is unavailable on the merchant's site.
  • Examples of financing program dependencies:
    • A merchant offers only standard terms of 10-30% APR, then monthly prices can be assumed to be calculated at 10% APR at 12 months. (6 months if between $50-100)
    • A merchant offers 0% APR, then monthly prices can be assumed to be calculated at 0% APR at 12 months when their 0% financing program is active.
  • Any time a monthly price is communicated to users, it must have accompanying disclosures or information that explain how that monthly price was calculated.
  • As a result, any monthly price should also include in-line descriptions or a link to descriptions of the price calculation, such as:
    "Starting at $44 a month with Affirm for a product price of $500 and 10% APR over 12 months."
Monthly Payment Messaging Disclosures
  • Interest rate in APR
  • Length of loan term
  • Given product/cart price
  • Explanation that not all applicants will qualify for the advertised interest rate.

Best Practices

  • Error Handling - A default message should replace the Affirm monthly payment message if your script is not able to retrieve the monthly payment price for any reason.
  • Email User Segmentation - You should be sending emails with Affirm monthly payment messaging to all the users that abandoned the cart and did not start the Affirm checkout process. All users that started the Affirm checkout process and cancelled (voluntarily or by Affirm) should receive an email without the Affirm monthly payment messaging.