Skip to main content

 

Affirm Merchant Help

Marketing Messaging Integration

Note: This page is for partners that are Marketing Providers. If you are a merchant looking to integrate Affirm into your emails, please visit this page instead.

Overview

Merchants offering Affirm as a payment option can include monthly payment pricing information in email, marketing message campaigns to their customers. We are partnering with marketing message providers to make it easier for merchants to include this information in their emails, media. This guide is for Marketing Messages Providers and covers how to integrate Affirm into your platform. The overall integration process is:

  1. Create a proof of concept
  2. Add Affirm tags
  3. Test and inform your customers

When developing your integration, you will need to account for 2 different methods for retrieving the monthly payment price:

  • Retrieve the monthly payment price from the HTML DOM
  • Use the Monthly Payment Messaging API

When a customer abandons the checkout process from a page displaying the monthly payment price, you can retrieve it from the HTML DOM. However, if a customer abandons the checkout process from a page that does not display the monthly payment price, you will need to call the API to retrieve it.

Use cases

The most common use cases for using the 2 integration methods are:

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.

1. Create a proof of concept

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 integration, 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. 

If you are using the old endpoint https://calculator.affirm.com/promos/payment_estimate_path/LSXKYTOB4Z3ZLLY4/0.10/135200/12 to get the monthly payment price, please update your integration to use this new API URL.

2. Track 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)

3. Test and inform your customers

After completing your proof of concept integration, coordinate testing with Affirm to verify its functionality. Once you've finished testing, set it live and inform your merchant customers about your new integration.

Best practices

To provide the best experience for customers, you should display any possible errors to the merchant before they send out their email campaign. For example, alert the merchant if the monthly pricing information is invalid for some reason otherwise their customer may receive an email containing errors.

Additionally, it’s also important to send emails to all customers who abandoned the checkout process and those who did not begin the checkout process. Customers who did not start the checkout process should receive an email without monthly pricing information.