---
updatedAt: 2026-07-15T19:10:41.000Z
agentTools:
siteIndex: https://docs.affirm.com/llms.txt
projectIndex: https://docs.affirm.com/developers/llms.txt
---
# Set Up Promotional Messaging
Integrate Affirm's promotional messaging to showcase flexible financing options, increase conversion rates, and enhance customer experience. This guide walks you through placement, setup, and configuration.
## Prerequisites
* Review [Affirm Marketing Compliance Guidelines](https://businesshub.affirm.com/hc/en-us/articles/5997808392724-Getting-Started-With-Affirm-Compliance-and-Guidelines).
* Determine where to display Affirm messaging on your site (e.g., product, category, cart, and homepage).
* Confirm your public API keys are available, you can access them in the [Affirm Merchant Portal](https://affirm.com/dashboard/#/apikeys). You’ll need this to configure Affirm.js and API requests.
* (*Optional*) Work with your Client Success Manager to customize [co-branded visuals](https://businesshub.affirm.com/hc/en-us/articles/12497969065620-How-can-I-co-brand-promotional-messaging-modals) or prequalification settings.
## Steps
### 1. Add Affirm.js (AFJS)
Embed the following snippet into the `` section of your site’s global template:
```javascript AFJS
```
### 2. Insert HTML Tags Where Messaging Will Appear
Place Affirm HTML components on relevant pages. Examples:
```html Promotional Messaging HTML Tags
Learn more
```
Use the `data-amount` in cents (e.g., 100.00 = 10000) and `data-page-type` values that correspond to the location.
#### Full HTML Example
The following example shows how to include Affirm.js and the necessary HTML tags on a product detail page:
```html Promotional Messaging Full HTML Example
Product Detail Page
Product Name
Product Description
Price: $100
Buy Now
$500.00
```
#### Promotional Messaging Placement Examples
* **Banner**
* **Products Page**
* **Product Overview Page**
### 3. Add Code to Handle Price Changes
If product pricing on your site updates dynamically, such as when customers select different variants or adjust quantities, ensure that Affirm’s promotional messaging reflects the updated pricing. The following functions are covered in this section:
* Refresh UI
* Page Reload
* Price Update
* Detect Modal Close
#### Refresh UI
To keep messaging updated, add this refresh function into your price change callback function:
```javascript Promotional Messaging Refresh UI
affirm.ui.refresh();
```
#### Page Reload
If the product’s price or the Affirm promotional messaging display after the page loads, or if you included the previous refresh function statically on the page, wrap it in the affirm.ui.ready() callback function. Doing so ensures that the page calls the refresh function only after Affirm.js initializes.
```javascript Promotional Messaging Page Reload
affirm.ui.ready(function(){
affirm.ui.refresh();
});
```
#### Price Update
When the price updates on your page, call the refresh function in the same callback function that handles your price change event. Add element IDs to promotional messaging components for easy access and modification of their attributes. Note that we use example ID names below.
```javascript Promotional Messaging Price Update
priceUpdateEventHandler(){
changePriceHandler(newPrice);
}
function updateAffirmPromos(newPrice){
//Update the wrapper elements' attributes in the DOM
document.getElementById('affirmProductModal').setAttribute('data-amount',newPrice);
document.getElementById('affirmLearnMore').setAttribute('data-amount',newPrice);
//Call affirm.ui.refresh to re-render the promotional messaging components
affirm.ui.refresh();
}
```
#### Detect Modal Close
When an education modal is closed (non-prequal), you can detect that event by using the following code:
```javascript Promotional Messaging Detect Modal Close
affirm.events.on('learnMore:close',function(){console.log('fired')});
```
### 4. Add Prequalification Messaging (*Optional*)
To give shoppers the option to check if they prequalify for Affirm financing, integrate As Low As (ALA) messaging. ALA placements automatically support prequalification modals when clicked and no separate integration is needed.
#### Prequalification Flow (New Customer)
#### Prequalification Flow (Existing Customer)
### 5. Test and Deploy
1. Confirm all Affirm components render correctly.
2. Switch your JS script from the sandbox to production ().
3. In the Affirm.js code you added to your site, replace `"YOUR_PUBLIC_KEY"` with your live key from the [Affirm Merchant Portal](https://affirm.com/dashboard/#/apikeys).
4. Validate functionality end-to-end before going live.
## What's Next?
* [Promos API](https://docs.affirm.com/developers/docs/promos-api-integration-overview)
* [Test and Go Live](https://docs.affirm.com/developers/docs/partner-test-and-go-live)
* [Marketing and Compliance](https://docs.affirm.com/developers/docs/email-marketing)
* [Manage Promotional Messaging Components](https://docs.affirm.com/developers/docs/manage-components)
# Sub pages
* [Promos API Integration Overview](https://docs.affirm.com/developers/docs/promos-api-integration-overview.md)
# Sibling pages
* [About Promotional Messaging and Prequalification](https://docs.affirm.com/developers/docs/about-promotional-messaging-and-prequalification.md)
* [Manage Promotional Messaging Components](https://docs.affirm.com/developers/docs/manage-components.md)
* [HTML Reference: Promotional Messaging](https://docs.affirm.com/developers/docs/html-reference-promotional-messaging.md)
* [About Google Tag Manager](https://docs.affirm.com/developers/docs/google-tag-manager.md)
* [Set Up Google Tag Manager](https://docs.affirm.com/developers/docs/set-up-google-tag-manager.md)
* [Marketing and Compliance](https://docs.affirm.com/developers/docs/email-marketing.md)
