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

Email Service Providers can include Affirm Monthly Payment Prices for those merchants that already have Affirm Monthly Payment Messaging on their site. This document is intended to instruct an ESP on what an integration with Affirm looks like, how to complete that integration, and how to best highlight those benefits for their merchant clients.

Integrate Affirm into your ESP platform

  1. Create a proof of concept (POC) using the Integration instructions below.
  2. Verify which Monthly Payment Messaging embed method the merchant is using (current or legacy).
  3. Implement Affirm tags that pull from the the Monthly Payment Price displayed on the page.
  4. Test the implementation.
  5. Become certified as an Affirm Marketing Partner (AMP).

Develop marketing collateral

Affirm is a natural compliment to ESPs, as both businesses can bolster the success of our mutual merchant clients. Affirm increases the value that an ESP can offer by providing additional incentives that can be presented to the customer. These benefits are best articulated through marketing collateral, such as white papers or solution designs, that is developed as a joint effort between Affirm and your team.


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

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

  • Getting Monthly Payment Price from the DOM of the page

This scenario assumes that merchant has Affirm Monthly Payment Messaging on their site and in most cases already sends product and user information using Javascript to Email/Marketing Service Providers. Affirm Monthly Payment Price which is rendered on the product or cart pages should be retrieved using Javascript and sent as another variable along with the other data to include it in email templates, media messages. 

  • Calling API from the front-end pages

Monthly Payment Messaging API can be called from the front-end pages to get the Monthly Payment Price while sending user, product related data back to Email/Marketing Service Providers. Preferably, Monthly Payment Price should be retrieved from the DOM and API should be used on pages where Monthly Payment Messaging is not implemented. 

  • Calling API at the time of content generation

Before the marketing content is generated, Monthly Payment Messaging API should be called to get the Affirm Monthly Payment Price. This value should then be parsed to the Affirm variable used as a content tag in the email templates, media messages. 

  • Appending Monthly Payment Price to the product database 

If product data feed or catalog is maintained to generate the marketing messages, a script could be used to get the Monthly Payment Price. This script uses the Affirm Monthly Payment Messaging API to get the Monthly Payment Price. Affirm Monthly Payment Price should then be appended to the existing product catalog as another product attribute. This script should be triggered every time product catalog is refreshed and product price is changed.


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.

 

Marketing to merchants

Benefits of combining Affirm and your Email Service

  • Monthly price for the customer's product or shopping cart lowers barriers for purchase
  • Existing Affirm customers can checkout more quickly
  • Bundling products and showing a monthly price for the entire shopping cart leads to higher AOV

Requirements

  • Sign-up as an Affirm merchant
  • Integrate Affirm Monthly Payment Messaging onto your product and/or cart pages
  • Coordinate with your Email Service Provider to extract the Affirm Monthly Payment Price on the page
  • Update your abandonment/retargeting emails to include the Affirm Monthly Payment Price