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: Your site's homepage
  • landing: A landing page that describes Affirm
  • search: Your site's search results page
  • category: Your site's category page
  • product: A product description page
  • cart: Your site's cart page
  • payment: The payment selection page
  • banner : A banner image (use for any promotional messaging triggered by your banner or image regardless of page location)
  • marketplace: The marketplace landing page
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: English speaking United States
  • en_CA: English speaking Canada
  • fr_CA: French speaking Canada
  • 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

    1. 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}

    2. Use the ala field value in the response to get the ALA promotional messaging (e.g. Starting at $185/mo with Affirm. Prequalify now).

    3. 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.

    1. 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:

    1. 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>"
    
    1. 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.