Promos API Integration
Learn about using our Promos API to add Affirm promotional messaging.
Overview
You can use the promos server-side API endpoint to render dynamic monthly prices (or other promotional text) and to present Affirm-hosted educational modals on your website. We've designed our promos service to be lightweight and usable for both merchants and Affirm developers, making it easy to implement in different environments. Below you’ll find information about our newest Promos API along with integration instructions.
How it works
The promos endpoint interfaces with our promos service. Based on query parameters sent by the client, our service returns the correct response containing the financing terms and styles for the Affirm modal and ALA (“As Low As”) messaging.
Inputs
Base Path: https://www.affirm.com/api/promos/v2/{YOUR_PUBLIC_KEY} where YOUR_PUBLIC_KEY is your public api key.
Public API Key
Every Affirm merchant has a unique public API Key, so you should work with an Affirm CSM to onboard a new merchant you want to use this API endpoint.
Attributes
| Query Param Name | Data type | Description | Supported Values | Default |
| amount
required |
int32 | The total amount of the checkout in USD or CAD cents (e.g., 10000 cents to charge $100.00). | Current currency default locale | |
| page_type | string | Identifies your promotional messaging so Affirm can apply the necessary customizations based on which page they are displayed.
|
homepage \
landing \
search \
category \
product
cart payment banner \ marketplace |
product |
| template_field
optional |
Determine what types of promos to render. There are 3 possibilities:
|
en_US \ en_CA \ fr_CA | Current country’s default locale |
Response Fields
The following demonstrates the data returned from our promo API that can then be used to customize the text. Please work with your Affirm partner to ensure you are compliant.
To customize text returned from promos api, please work with your Affirm partner.
ALA
{
"promo": {
"html_ala": HTML formatted as low as messaging,
"config": [Internal Use Only],
"ala": As low as messaging
}
}
Modal
Note: Many of these fields are used for Affirm modal formatting.
{
"promo": {
"content_space_1": [Internal Use Only],
"Description": One-line message about what Affirm is,
"footer": Legal disclosures for educational modal,
"headline": Headline for educational modal,
"tagline": One-line sample of the best term for the specified
data amount and merchant,
"button": Call to action text for user,
"html_footer": HTML formatted legal disclosures,
"content_space_2": [Internal Use Only],
"terms_description": [Internal Use Only],
"config": {
"styles": [Internal Use Only],
"promo_style": [Internal Use Only],
"is_ada_compliant": [Internal Use Only],
"promo_prequal_enabled": indicator of if prequalification
is enabled for this merchant and
this promotional message (true or
false),
"show_white_labeling": [Internal Use Only],
"images": {
"hero2x": High quality merchant promotional image url
(default null),
"logo": Merchant logo url (default null),
"hero": Merchant promotional image url (default null),
"logo2x": High quality merchant logo url (default null),
},
"merchant_name": Merchant's name,
}
},
"offer": {
"expiry_date": [Internal Use Only],
"terms": List of sample loan terms for the given cart amount.
Each term will have the following format:
{
"loan_type": Loan type available for this merchant
(classic, affirm_go_v3, affirm_go),
"interest_amount": Amount of interest for this
loan term,
"billing_frequency": Frequency at which the user will
need to pay back the loan,
"apr": APR for this loan term,
"installment_amount": Amount due at each payment,
"minimum_loan_amount": Minimum loan amount available
to the user,
"amount": Total amount due when loan is completed,
"installment_count": Total number of installments
},
"minimum_loan_amount": Minimum loan amount available to the user
}
}
All
{
"promo": {
"html_ala": HTML formatted as low as messaging,
"ala": As low as messaging
"content_space_1": [Internal Use Only],
"Description": One-line message about what Affirm is,
"footer": Legal disclosures for educational modal,
"headline": Headline for educational modal,
"tagline": One-line sample of the best term for the specified
data amount and merchant,
"button": Call to action text for user,
"html_footer": HTML formatted legal disclosures,
"content_space_2": [Internal Use Only],
"terms_description": [Internal Use Only],
"config": {
"styles": [Internal Use Only],
"promo_style": [Internal Use Only],
"is_ada_compliant": [Internal Use Only],
"promo_prequal_enabled": indicator of if prequalification
is enabled for this merchant and
this promotional message (true or
false),
"show_white_labeling": [Internal Use Only],
"images": {
"hero2x": High quality merchant promotional image url
(default null),
"logo": Merchant logo url (default null),
"hero": Merchant promotional image url (default null),
"logo2x": High quality merchant logo url (default null),
},
"merchant_name": Merchant's name,
}
},
"offer": {
"expiry_date": [Internal Use Only],
"terms": List of sample loan terms for the given cart amount.
Each term will have the following format:
{
"loan_type": Loan type available for this merchant
(classic, affirm_go_v3, affirm_go),
"interest_amount": Amount of interest for this
loan term,
"billing_frequency": Frequency at which the user will
need to pay back the loan,
"apr": APR for this loan term,
"installment_amount": Amount due at each payment,
"minimum_loan_amount": Minimum loan amount available
to the user,
"amount": Total amount due when loan is completed,
"installment_count": Total number of installments
},
"minimum_loan_amount": Minimum loan amount available to the user
}
}
Requests
As Low As Messaging
Basic request using defaults
https://affirm.com/api/promos/v2/{YOUR_PUBLIC_KEY}?amount={AMOUNT_IN_CENTS}&field=ala&use_best_terms=true&show_cta=true
Sample request
https://affirm.com/api/promos/v2/L6MZWHPL1AHQOYOJ?amount=18500&field=ala&use_best_terms=true&show_cta=true
Sample response
{
"promo":
{
"html_ala": "Starting at <span class='affirm-ala-price'>$17</span>/mo with <span class='__affirm-logo __affirm-logo-blue'>Affirm</span>. <a class='affirm-modal-trigger'>Prequalify now</a>",
"config":
{
"promo_prequal_enabled": true,
"promo_style": "prequal"
},
"ala": "Starting at $17/mo with Affirm. Prequalify now"
}
}
Basic request with custom items
https://www.affirm.com/api/promos/v2/{YOUR_PUBLIC_KEY}?amount={AMOUNT_IN_CENTS}&field=ala&items=%5B%7B%22sku%22%3A%22{ITEM_SKU}%22%2C%22display_name%22%3A{ITEM_NAME}%2C%22qty%22%3A{QUANTITY}%2C%22unit_price%22%3A{UNIT_PRICE}%7D%5D&page_type=product
Sample request
https://www.affirm.com/api/promos/v2/L6MZWHPL1AHQOYOJ?amount=10000&field=ala&items=%5B%7B%22sku%22%3A%22ABC123%22%2C%22display_name%22%3A%22Glasses%22%2C%22qty%22%3A2%2C%22unit_price%22%3A5000%7D%5D&page_type=product
Sample response
{
"promo":
{
"html_ala": "Starting at <span class='affirm-ala-price'>$10</span>/mo with <span class='__affirm-logo __affirm-logo-blue'>Affirm</span>. <a class='affirm-modal-trigger'>Prequalify now</a>",
"config":
{
"promo_prequal_enabled": true,
"promo_style": "prequal"
},
"ala": "Starting at $10/mo with Affirm. Prequalify now"
}
}
Modal rendering
Basic request using defaults
https://affirm.com/api/promos/v2/{YOUR_PUBLIC_KEY}?amount={AMOUNT_IN_CENTS}&field=modal&use_best_terms=true
Sample request
https://affirm.com/api/promos/v2/L6MZWHPL1AHQOYOJ?amount=10000&field=modal&use_best_terms=true
Sample response
{
"promo":
{
"content_space_1": "quick_and_easy",
"description": "Get a real-time decision with just 5 pieces of info.",
"footer": "Rates are between 10–30% APR. A down payment may be required. Subject to eligibility check and approval. Payment options depend on your purchase amount. Estimated payment amount excludes taxes and shipping fees. Actual terms may vary. Payment options through Affirm are provided by these lending partners: affirm.com/lenders. Visit affirm.com/help for more info.",
"headline": "Make easy monthly payments over 3, 6, or 12 months",
"tagline": "$9.04/mo. based on a purchase price of $100.00 at 15% APR for 12 months. Rates from 10–30% APR.",
"button": "See if you qualify",
"html_footer": "Rates are between 10–30% APR. A down payment may be required. Subject to eligibility check and approval. Payment options depend on your purchase amount. Estimated payment amount excludes taxes and shipping fees. Actual terms may vary. Payment options through Affirm are provided by these lending partners: [affirm.com/lenders](https://www.affirm.com/lenders). Visit [affirm.com/help](https://affirm.com/help) for more info.",
"content_space_2": "no_hidden_fees",
"terms_description": "",
"config":
{
"styles":
{
"color": null,
"fontFamily": "'proxima-nova', sans-serif"
},
"promo_style": "prequal",
"is_ada_compliant": false,
"promo_prequal_enabled": true,
"show_white_labeling": false,
"images":
{
"hero2x": null,
"logo": null,
"hero": null,
"logo2x": null
},
"merchant_name": "[TEST] Sandbox Merchant"
}
},
"offer":
{
"expiry_date": null,
"terms":
[
{
"downpayment_amount": null,
"loan_type": "classic",
"interest_amount": 256,
"billing_frequency": "monthly",
"apr": 15.29,
"installment_amount": 3418,
"minimum_loan_amount": 50,
"amount": 10256,
"installment_count": 3
},
{
"downpayment_amount": null,
"loan_type": "classic",
"interest_amount": 449,
"billing_frequency": "monthly",
"apr": 15.24,
"installment_amount": 1742,
"minimum_loan_amount": 50,
"amount": 10449,
"installment_count": 6
},
{
"downpayment_amount": null,
"loan_type": "classic",
"interest_amount": 843,
"billing_frequency": "monthly",
"apr": 15.22,
"installment_amount": 904,
"minimum_loan_amount": 100,
"amount": 10843,
"installment_count": 12
}
],
"minimum_loan_amount": 50
}
}
Basic request with custom items
https://www.affirm.com/api/promos/v2/{YOUR_PUBLIC_KEY}?amount={AMOUNT_IN_CENTS}&field=modal&items=%5B%7B%22sku%22%3A%22{ITEM_SKU}%22%2C%22display_name%22%3A{ITEM_NAME}%2C%22qty%22%3A{QUANTITY}%2C%22unit_price%22%3A{UNIT_PRICE}%7D%5D&page_type=product
Sample request
https://www.affirm.com/api/promos/v2/L6MZWHPL1AHQOYOJ?amount=10000&field=modal&items=%5B%7B%22sku%22%3A%22ABC123%22%2C%22display_name%22%3A%22Glasses%22%2C%22qty%22%3A2%2C%22unit_price%22%3A5000%7D%5D&page_type=product
Sample response
{
"promo":
{
"content_space_1": "quick_and_easy",
"description": "",
"footer": "A down payment may be required. Subject to eligibility check and approval. Payment options depend on your purchase amount. Estimated payment amount excludes taxes and shipping fees. Actual terms may vary. Payment options through Affirm are provided by these lending partners: affirm.com/lenders. Visit affirm.com/help for more info.",
"headline": "Make easy monthly payments over 3, 6, or 12 months",
"tagline": "$9.04/mo. based on a purchase price of $100.00 at 15% APR for 12 months. Rates from 10–30% APR.",
"button": "See if you qualify",
"html_footer": "A down payment may be required. Subject to eligibility check and approval. Payment options depend on your purchase amount. Estimated payment amount excludes taxes and shipping fees. Actual terms may vary. Payment options through Affirm are provided by these lending partners: [affirm.com/lenders](https://www.affirm.com/lenders). Visit [affirm.com/help](https://affirm.com/help) for more info.",
"content_space_2": "no_hidden_fees",
"terms_description": "",
"config":
{
"styles":
{
"color": null,
"fontFamily": "'proxima-nova', sans-serif"
},
"promo_style": "prequal",
"is_ada_compliant": false,
"promo_prequal_enabled": true,
"show_white_labeling": false,
"images":
{
"hero2x": null,
"logo": null,
"hero": null,
"logo2x": null
},
"merchant_name": "[TEST] Sandbox Merchant"
}
},
"offer":
{
"expiry_date": null,
"terms":
[
{
"downpayment_amount": null,
"loan_type": "classic",
"interest_amount": 256,
"billing_frequency": "monthly",
"apr": 15.29,
"installment_amount": 3418,
"minimum_loan_amount": 50,
"amount": 10256,
"installment_count": 3
},
{
"downpayment_amount": null,
"loan_type": "classic",
"interest_amount": 449,
"billing_frequency": "monthly",
"apr": 15.24,
"installment_amount": 1742,
"minimum_loan_amount": 50,
"amount": 10449,
"installment_count": 6
},
{
"downpayment_amount": null,
"loan_type": "classic",
"interest_amount": 843,
"billing_frequency": "monthly",
"apr": 15.22,
"installment_amount": 904,
"minimum_loan_amount": 100,
"amount": 10843,
"installment_count": 12
}
],
"minimum_loan_amount": 50
}
}
Implementation
-
Create an API GET request with the required parameters to fetch the ALA messaging from the endpoint below.
https://www.affirm.com/api/promos/v2/{YOUR_PUBLIC_KEY} -
Use the ala field value in the response to get the ALA promotional messaging (e.g. Starting at $185/mo with Affirm. Prequalify now).
-
Set up an HTML hyperlink on your website for the prequalification CTA (call to action) with a parallel URL following this format:
parallel URL
https://www.affirm.com/apps/prequal/?public_api_key=YOUR_PUBLIC_KEY&unit_price=PRODUCT_PRICE&page_type=PAGE_TYPE&use_promo=true&referring_url=https://www.YourReturningURL.com
For instance, if you want to implement prequalification with the ALA “Starting at $185/mo with Affirm. Prequalify now” on your product page, you would use the following HTML snippet:
<p>Starting at $185/mo with Affirm. <a href="https://www.affirm.com/apps/prequal/?public_api_key=L6MZWHPL1AHQOYOJ&unit_price=222000&PRODUCT_PRICE&page_type=product&use_promo=true&referring_url=https%253A%252F%252Fwww.affirm.com%252F&" target="_blank">Prequalify now</a></p>
Parallel URL
The parallel URL is the url that must be visibly linked to the CTA that directs to an informational page due to regulatory requirements. Please see the following example:
parallel URL
https://www.affirm.com/apps/prequal/?public_api_key=YOUR_PUBLIC_KEY&unit_price=25000&page_type=product&use_best_terms=true&use_promo=true&referring_url=https://www.YourReturningURL.com
\
Note:
- The key of amount changes to unit_price for the informational URL.
- The referring_url is only applicable if prequalification feature is active
- If you support sku based financing, you can also pass stringified items
If prequalification is enabled, this URL will be used to redirect the user back to the website once they complete prequalification.
- Validate the functionality with a jsfiddle sample and ensure the prequalification functionality works
Questions?
If you have any questions, reach out to your technical contact at Affirm.
Example Implementation on a Product Page
Any time you would like to add Affirm As Low As messaging (e.g. “Starting at $185/mo with Affirm. Prequalify now”), you must include the following two parts:
- The ALA messaging itself: Starting at $185/mo with Affirm
- The CTA which includes a link to a modal with disclosures, etc: Prequalify now
The CTA, a link to an Affirm page with details matching and explaining the As Low As messaging, is required to satisfy lending regulations. That is, for any given promo request that is built, a parallel URL for an informational page must be built and visibly linked on the CTA of the ALA message that is returned by the ALA endpoint.
For example, on a product detail page listing, you'll use the following request to retrieve the ALA for a $250.00 product:
Request
curl --request GET \
--url https://www.affirm.com/api/promos/v2/YOUR_PUBLIC_KEY?amount=25000&use_best_terms=true&page_type=product
Response
The response returned by this request would look like the following:
JSON
{
"promo": {
"content_space_1": "quick_and_easy",
"description": "Get a real-time decision with just 5 pieces of info.",
"footer": "Rates are between 0\u201330% APR. A down payment may be required. Subject to eligibility check and approval. Payment options depend on your purchase amount. Estimated payment amount excludes taxes and shipping fees. Actual terms may vary. Payment options through Affirm are provided by these lending partners: affirm.com/lenders. Visit affirm.com/help for more info.",
"headline": "Make easy monthly payments over 3, 6, or 12 months",
"tagline": "$22.60/mo. based on a purchase price of $250.00 at 15% APR for 12 months. Rates from 0\u201330% APR.",
"html_ala": "Starting at <span class='affirm-ala-price'>$23</span>/mo with <span class='__affirm-logo __affirm-logo-blue'>Affirm</span>. <a class='affirm-modal-trigger'>Prequalify now</a>",
"ala": "Starting at $23/mo with Affirm. Prequalify now",
"html_footer": "Rates are between 0\u201330% APR. A down payment may be required. Subject to eligibility check and approval. Payment options depend on your purchase amount. Estimated payment amount excludes taxes and shipping fees. Actual terms may vary. Payment options through Affirm are provided by these lending partners: <a class='affirm-loan-originator' href='https://www.affirm.com/lenders'>affirm.com/lenders</a>. Visit affirm.com/help for more info.",
"content_space_2": "no_hidden_fees",
"terms_description": "",
"config": {
"styles": {
"color": null,
"fontFamily": "'proxima-nova', sans-serif"
},
"promo_style": "prequal",
"is_ada_compliant": false,
"promo_prequal_enabled": true,
"show_white_labeling": false,
"images": {
"hero2x": null,
"logo": null,
"hero": null,
"logo2x": null
},
"merchant_name": "Merchant Name"
},
"button": "See if you qualify"
},
"offer": {
"expiry_date": null,
"terms": [
{
"loan_type": "classic",
"interest_amount": 0,
"billing_frequency": "monthly",
"apr": 0.00,
"installment_amount": 8333,
"minimum_loan_amount": 50,
"amount": 25000,
"installment_count": 3
},
{
"loan_type": "classic",
"interest_amount": 1128,
"billing_frequency": "monthly",
"apr": 15.31,
"installment_amount": 4355,
"minimum_loan_amount": 50,
"amount": 26128,
"installment_count": 6
},
{
"loan_type": "classic",
"interest_amount": 2115,
"billing_frequency": "monthly",
"apr": 15.27,
"installment_amount": 2260,
"minimum_loan_amount": 100,
"amount": 27115,
"installment_count": 12
}
],
"minimum_loan_amount": 50
}
}
From these two responses, we would then build the HTML to insert on your page:
- Pull the html_ala from the promo response:
"html_ala": "Starting at \<span class='affirm-ala-price'>$23\</span>/mo with \<span class='**affirm-logo **affirm-logo-blue'>Affirm\</span>. \<a class='affirm-modal-trigger'>Prequalify now\</a>"
- Identify the CTA. In this example, the CTA is “Prequalify now” and it is wrapped in an tag with class=affirm-modal-trigger.
Insert your href attribute and link to the parallel URL:
href='https://www.affirm.com/apps/prequal/?public_api_key=API_KEY&unit_price=25000&page_type=product&use_promo=true
The end HTML would look like this:
HTML
Starting at <span class='affirm-ala-price'>$23</span>/mo with <span class='__affirm-logo __affirm-logo-blue'>Affirm</span>. <a class='affirm-modal-trigger' href='https://www.affirm.com/apps/prequal/?public_api_key=YOUR_PUBLIC_KEY&unit_price=25000&page_type=product&use_promo=true&referring_url=https://www.YourReturningURL.com'>Prequalify now</a>
Note
The referring_url is only applicable if the prequalification feature is active.
Updated 5 months ago