Promos API integration

# 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
<table>
  <tr>
   <td><strong>Query Param Name</strong>
   </td>
   <td><strong>Data type</strong>
   </td>
   <td><strong>Description</strong>
   </td>
   <td><strong>Supported Values</strong>
   </td>
   <td><strong>Default</strong>
   </td>
  </tr>
  <tr>
   <td>amount
<p>
required
   </td>
   <td><em>int32</em>
   </td>
   <td>The total amount of the checkout in USD or CAD cents (e.g., 10000 cents to charge $100.00).
   </td>
   <td>
   </td>
   <td>Current currency default locale
   </td>
  </tr>
  <tr>
   <td>page_type
   </td>
   <td><em>string</em>
   </td>
   <td>Identifies your promotional messaging so Affirm can apply the necessary customizations based on which page they are displayed.<strong> </strong>
<ul>
<li><em>homepage</em>: Your site's homepage
<li><em>landing</em>: A landing page that describes Affirm
<li><em>search</em>: Your site's search results page
<li><em>category</em>: Your site's category page
<li><em>product</em>: A product description page
<li><em>cart</em>: Your site's cart page
<li><em>payment</em>: The payment selection page
<li><em>banner</em>	: A banner image (use for any promotional messaging triggered by your banner or image regardless of page location)
<li><em>marketplace</em>: The marketplace landing page
</li>
</ul>
   </td>
   <td>homepage \
landing \
search \
category \
product
<p>
cart
<p>
payment
<p>
banner \
marketplace
   </td>
   <td>product
   </td>
  </tr>
  <tr>
   <td>template_field
<p>
<em>optional</em>
   </td>
   <td>
   </td>
   <td>Determine what types of promos to render. There are 3 possibilities:
<p>
<li><em>en_US</em>: English speaking United States
<li><em>en_CA</em>: English speaking Canada
<li><em>fr_CA</em>: French speaking Canada
</li>
</ul>
   </td>
   <td>en_US \
en_CA \
fr_CA
   </td>
   <td>Current country’s default locale
   </td>
  </tr>
</table>
## 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
﻿
### Modal
Note: Many of these fields are used for Affirm modal formatting.
﻿
### All
﻿
# Requests
### As Low As Messaging
#### Basic request using defaults
﻿
##### Sample request
﻿
##### Sample response
﻿
#### Basic request with custom items
﻿
##### Sample request
﻿
##### Sample response
﻿
### Modal rendering
#### Basic request using defaults
﻿
##### Sample request
﻿
##### Sample response
﻿
#### Basic request with custom items
﻿
##### Sample request
﻿
##### Sample response
﻿
# 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
﻿
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:
﻿
#### 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
﻿
#### Response
The response returned by this request would look like the following:
JSON
﻿
From these two responses, we would then build the HTML to insert on your page:
Pull the html_ala from the promo response: 
﻿
Identify the CTA. In this example, the CTA is “Prequalify now” and it is wrapped in an <a> 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
﻿
Note
The referring_url is only applicable if the prequalification feature is active.