Skip to main content

Merchant Help

 

Affirm Merchant Help

Email Service Providers

Note: This page is for Email Service 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 campaigns to their customers. We are partnering with email service providers to make it easier for merchants to include this information in their emails. This guide is for email service 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 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, APR, and the loan term length. The API will return a JSON response that includes the monthly payment price and disclosure messaging.

URL

https://calculator.affirm.com/promos/payment_estimate_path/

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
apr float The annual percentage rate for the loan you are offering in decimal percentage (e.g., 10% is 0.10). Min: 0.00, Max: 0.30. Required
amount integer The total loan amount being offered, stated in USD cents ($500 = 50000). Min: 5,000, Max: 3,000,000. Required
term_length integer The term length of the loan being offered in number of months (e.g., 12 months is 12). Min: 3, Max: 8. Required

Example API call and response

https://calculator.affirm.com/promos/payment_estimate_path/LSXKYTOB4Z3ZLLY4/0.10/135200/12 

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:

"Based on the purchase price of $1352.00 at 10% APR for 12 months."

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.