Skip to main content

 

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. Retrieve the Monthly Payment Price from the HTML DOM
  2. Monthly Payment Messaging API

Most common scenarios describing how these integration methods can be used to retrieve monthly payment price are explained below:

  • Get the monthly payment price from your page DOM

The merchant has added Affirm Monthly Payment Messaging to their site and likely already sends product and customer information using Javascript to Email/Marketing Service Providers. Retrieve the monthly payment messaging on the product or cart pages via JavaScript and send it as another variable along with the rest of the data to include in email templates and media messages.

  • Call the API from your front-end pages

For pages where you have not added Affirm Monthly Payment Messaging, call the Monthly Payment Messaging API from those front-end pages to get the monthly payment price. You can then send it along with customer and product-related data back to your email or marketing service providers.

  • Call the API at the time of content generation

Call the Monthly Payment Messaging API before generating your marketing content to get the monthly payment price. Set the Affirm variable used as a content tag in email templates and media messages to the price value.

  • Append the monthly payment price to your product database

If you use a product data feed or catalog to generate marketing messages, you can use a script to get the monthly payment price via the Affirm Monthly Payment Messaging API. After getting the price value, append it to your existing product catalog as another product attribute. Be sure to trigger the script every time the product catalog refreshes and the product price changes.


Retrieve the Affirm monthly payment price from the HTML DOM

Determine how the merchants are integrated:

Your integration will need to account for merchants who have integrated Affirm using our current method or an older legacy method. Merchants who have integrated Affirm using our current method will display monthly payment messaging on their site product description or cart pages using the following HTML code.

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

Merchants using our legacy integration will display monthly payment messaging using the following HTML code and additional JavaScript.

Example HTML:

<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>

For merchants using our current integration, extract the pricing information using the following code where AffirmMonthlyPrice is any variable you choose:

var AffirmMonthlyPrice = document.getElementsByClassName('affirm-ala-price')[0].innerHTML;

For merchants using our legacy integration, extract the pricing information using the following code where AffirmMonthlyPrice is any variable you choose:

var AffirmMonthlyPrice = document.getElementbyId('learn-more');

In both cases, the monthly price will be a string. For legacy integrations, there is also a JavaScript variable that contains the monthly payment price.

 Examples:

Terms and disclosure information
Terms and disclosure information needs to accompany each monthly payment price. There is currently no way to pass this information from the HTML DOM so you'll need to provide a field that contains a template for this information. The merchant will be responsible for working with Affirm to edit this field correctly. Examples include:

  • “Starting at $44 a month with Affirm for a product price of $500 and 10% APR over 12 months.”
  • “As low as $167 a month with Affirm for a total of $2000 and 0% financing over 12 months.”

Use the Monthly Payment Messaging API

Call the API with the merchant’s public key, the loan amount and data promo id. The API will return a JSON response that includes the monthly payment price and disclosure messaging.

URL https://www.affirm.com/api/promos/v2/{public_api_key}

Options

  • Type: GET
  • Authorization: Basic
  • Content type: application/JSON
  • Data: JSON string

Data

Parameter Type Description
public_api_key string Your public API key. Required
amount integer The total loan amount being offered, stated in USD cents ($500 = 50000). Min: 5,000, Max: 3,000,000. Required
promo_external_id string

External Promo ID which calculates monthly payment messaging based on the merchant’s financing program. By default, if a merchant has a custom financing program enabled (0% for anything above $1000, etc.), this parameter does not need to be added to the request. Please work with the Affirm Customer Success team to get the appropriate value for promo_external_id if a merchant is running multiple financing programs (certain product SKUs, brands, etc.). Optional

 

Example API call and response

Request: https://www.affirm.com/api/promos/v2/ARQBLCL7NAMBTZ7F?amount=99900 

Response:

{
 "promo": {
   "description": "",
   "footer": "Subject to credit check and approval. Down payment may be required. For purchases under $50, limited payment options are available. Estimated payment amount excludes taxes and shipping fees. Affirm loans are made by Cross River Bank, a New Jersey State Chartered Commercial Bank, Member FDIC. See www.affirm.com/faqs for details.",
   "headline": "Make easy monthly payments over 3, 6, or 12 months",
   "tagline": "$87.88/mo. based on a purchase price of $999.00 at 10% APR for 12 months. Rates from 10–30% APR.",
   "html_ala": "Starting at <span class='affirm-ala-price'>$88</span>/month with <span class='__affirm-logo __affirm-logo-blue'>Affirm</span>. <a class='affirm-modal-trigger'>Learn more</a>",
   "ala": "Starting at $88/month with Affirm. Learn more",
   "content_space_2": "no_hidden_fees",
   "content_space_1": "quick_and_easy",
   "config": {
     "styles": {
       "color": null,
       "fontFamily": "'Arial', 'Helvetica', sans-serif"
     },
     "promo_prequal_enabled": false,
     "images": {
       "hero2x": null,
       "logo": null,
       "hero": null,
       "logo2x": null
     },
     "promo_style": "classic"
   },
   "button": "Just select Affirm at checkout."
 },
 "offer": {
   "terms": [],
   "expiry": null
 }
}

 

Terms and disclosure information

Terms and disclosure information needs to accompany each monthly payment price. The JSON response includes a disclosure statement. Merchants can edit this disclosure statement themselves as well. In the example API call above, the disclosure is provided in the tagline:

"$87.88/mo. based on a purchase price of $999.00 at 10% APR for 12 months. Rates from 10–30% APR."

To enable this API for your merchant, please work with the Affirm Customer Success Manager (CSM). Before enabling the API Key, you will be asked to provide the following as part of the onboarding process for every merchant:

  • Requests per day 
  • Peak request hours
  • Peak requests per hour 
  • Campaign start and end date

Note: Every Affirm merchant has unique public API Key, so you should work with Affirm CSM to onboard a new merchant you want to enable Affirm marketing messages and use this API endpoint. 


Tracking Affirm promotions

Add the following as query parameters to outgoing links (e.g., a link that sends the customer to your cart page):

  • aff_cid="unique_value" - “unique value” is an existing or newly created tracking ID, which may provide additional information about the email service provider and/or the merchant (optional)
  • aff_fm="t" - this opens an Affirm educational modal when a customer lands on the page where Affirm promotional messaging is available (optional)

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.

 

  • Was this article helpful?