> This page is for Afterpay Online Developer, version Main (default).
> For other versions, use one of these documentation indexes:
> - Main (default): https://developers.afterpay.com/afterpay-online-developer/main/llms.txt
> - v1: https://developers.afterpay.com/afterpay-online-developer/v-1/llms.txt
> - Chinese: https://developers.afterpay.com/afterpay-online-developer/chinese/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.afterpay.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.afterpay.com/_mcp/server.

# Afterpay.js Reference

> **HTML Dataset Attributes**
>
> The `<afterpay-placement>` web component is configurable via a set of  [data attributes](https://developer.mozilla.org/en-US/docs/Learn/HTML/Howto/Use_data_attributes)
>
> For Placements initialized through JavaScript, all attributes should be provided in camel-case.
>
> See Mozillas [reference](https://developer.mozilla.org/en-US/docs/Web/API/HTMLOrForeignElement/dataset#name_conversion) on dataset naming conversion for more information.

| **Environment** | **URL**                                           |
| --------------- | ------------------------------------------------- |
| Sandbox         | `https://portal.sandbox.afterpay.com/afterpay.js` |
| Production      | `https://portal.afterpay.com/afterpay.js`         |

## Attribute List

| Attribute                  | Accepted Values                                                                                                              |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `amount`                   | A Number - see the [Definition](#amount).                                                                                    |
| `amount-selector`          | A CSS Selector in the DOM - see the [Definition](#amount-selector).                                                          |
| `amount-mutation-selector` | Any CSS Selector in the DOM - see the [Definition](#amount-mutation-selector).                                               |
| `badge-theme`              | Black-on-white, white-on-black, mint-on-black, and black-on-mint. See the [Definition](#badge-theme).                        |
| `cart-is-eligible`         | True or false. See the [Definition](#cart-is-eligible).                                                                      |
| `cbt-enabled`              | True or false. See the [Definition](#cbt-enabled).                                                                           |
| `currency`                 | AUD, CAD, EUR, GBP, NZD and USD - see the [Definition](#currency).                                                           |
| `data-amount-range`        | JSON stringified array of numbers/strings. See the [Definition](#data-amount-range).                                         |
| `decimal-separator`        | . (period) and , (comma) - see the [Definition](#decimal-separator).                                                         |
| `intro-text`               | Pay, pay, In, in, Or, or, Pay in, pay in. See the [Definition](#intro-text).                                                 |
| `is-eligible`              | True or false. See the [Definition](#is-eligible).                                                                           |
| `locale`                   | en_AU, en_CA, en_GB, en_NZ, en_US, fr_CA. See the [Definition](#locale)                                                      |
| `logo-type`                | compact-badge, badge, or lockup. See the [Definition](#logo-type).                                                           |
| `lockup-theme`             | black, white, mint - see the [Definition](#lockup-theme).                                                                    |
| `mobile-view-layout`       | two-by-two or four-by-one - see the [Definition](#mobile-view-layout)                                                        |
| `modal-id`                 | Provided by Afterpay - see the [Definition](#modal-id).                                                                      |
| `modal-link-style`         | learn-more-text, more-info-text, circled-info-icon, circled-question-icon, or none. See the [Definition](#modal-link-style). |
| `modal-theme`              | mint or white. See the [Definition](#modal-theme).                                                                           |
| `payment-amount-is-bold`   | true or false. See the [Definition](#payment-amount-is-bold).                                                                |
| `price-table-theme`        | black or white - see the [Definition](#price-table-theme).                                                                   |
| `show-interest-free`       | True or false. See the [Definition](#show-interest-free).                                                                    |
| `show-lower-limit`         | True or false. See the [Definition](#show-lower-limit).                                                                      |
| `show-upper-limit`         | True or false. See the [Definition](#show-upper-limit).                                                                      |
| `show-with`                | True or false. See the [Definition](#show-with).                                                                             |
| `size`                     | xs - 12px, sm - 14px, md - 16px, lg - 18px. See the [Definition](#size).                                                     |
| `thousands-separator`      | . (period) and , (comma) - see the [Definition](#thousands-separator).                                                       |
| `type`                     | price-table, or price-paragraph - see the [Definition](#type).                                                               |

## Amount

The value provided to the AfterpayPlacement through the `amount` attribute reflects the full price displayed to the customer on the page. The library calculates the installments and displays the messaging appropriately.

On a product page, the amount should be the product price.
On the cart page, the amount should be the *total*.

| Accepted Values                                                                        |
| -------------------------------------------------------------------------------------- |
| Any Integer, or Double with at most 2 significant figures after the decimal separator. |

The Afterpay Messaging will automatically calculate the new instalment price when the amount attribute changes.

**HTML**

```json
<afterpay-placement data-amount="400"></afterpay-placement>
```

**JavaScript**

```js
const AfterpayPlacement = new Afterpay.AfterpayPlacement()
AfterpayPlacement.amount = 400;
```

## amount-selector

Accepts the [CSS selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) corresponding to the price element on the page. The AfterpayPlacement element reads the price text from the page and sets the `amount` attribute on the component.

This attribute takes the second highest precedence after `amount`, and if neither are specified the default amount is set to zero.

**HTML**

```html
<div class="pdp-wrapper">
   <span id="productPrice">59.99</span>
 </div>

<afterpay-placement
   data-amount-selector ="#productPrice">
</afterpay-placement>
```

Configuring the placement with `data-amount-selector` enables the placement to track updates to the price element. When a change is detected, the installment messaging automatically updates with the new calculated installment amount.

## amount-mutation-selector

Accepts any [CSS selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) corresponding to the "target" element on the page to watch for changes.

When `amount-mutation-selector` is defined, an attribute to retrieve the current amount on the page must also be defined. There are two ways to achieve this:

1. Setting `data-amount` .

2. Retrieving the price text from `data-amount-selector`.

**HTML**

```html
<afterpay-placement
     data-amount-mutation-selector = "#targetElement"
     data-amount-selector ="#productPrice">
</afterpay-placement>
```

*Useful for eCommerce platforms like Shopify and BigCommerce where the product price is available to template pages*.

**HTML**

```html
<afterpay-placement
     data-amount-mutation-selector = "#targetElement"
     data-amount ="{{product.price}}">
</afterpay-placement>
```

## badge-theme

Themes specific to `data-logo-type = "badge"` and `data-logo-type="compact-badge"`\
See the [logo-type](#logo-type) section for details on switching between logos.

![badge-themes.png](/_fern-img/693dc879a939c96096aba81d76cf0ae9c54c000987d72790f8f7858b6456b10d.webp)

## cart-is-eligible

Accepted values: `true`, `false`\
When true, the price paragraph displays the normal installment messaging.\
When false, the price paragraph renders *Afterpay not available* messaging.

For more information, see [Set Messaging For Unavailable Items](Advanced-Configuration.mdx).

## cbt-enabled

Displays Afterpay cross border trade information in the modal content.

> **Cross Border Trade**
>
> Permitted in the following regions:
>
> * Australia 🇦🇺
>
> * New Zealand 🇳🇿
>
> * United Kingdom 🇬🇧

## currency

When provided, formats the currency for a given locale.

**HTML**

```html
<afterpay-placement
	data-amount="300"
	data-locale="en_CA"
	data-currency="USD">
</afterpay-placement>
```

![currency.png](/_fern-img/662c35cf1898aef3df44acbe5b9959d656ba0e946d8b320204bcbdc260cbd464.webp)

## data-amount-range

When you specify a range of possible prices for a product using the `data-amount-range` attribute and the `data-amount` attribute is set to 0, a new messaging variant appears. This new messaging variant is based on the lowest price within the range that fits the minimum and maximum price thresholds set by the merchant.

**HTML**

```html
<afterpay-placement
 data-amount="0"
 data-locale="en_US"
 data-min="100"
 data-max="1000"
 data-amount-range="[95, 111.11, 222, 333.33, 444, 555.55, 666, 777.777, 888, 999.99, 1111]"             
 data-currency="USD">
</afterpay-placement>
```

In the HTML code example above, the message displayed is:

![data-amount-range.png](/_fern-img/9fc48002d256669d862fad9e1dc7fa73de9080b2ded694b4a313501cd84a48d8.webp)

When the above attributes are set and the `data-amount` is a valid amount, the messaging with the exact instalment amount is displayed.

## decimal-separator

Accepts: `"."`, `","`\
Sets how the component should parse the provided amount.

## intro-text

The first word(s) of the Afterpay Messaging Paragraph.

| Accepted Values (Sentence Case) | Accepted Values (Lowercase) |
| ------------------------------- | --------------------------- |
| Or                              | or                          |
| In                              | in                          |
| Pay                             | pay                         |
| Pay in                          | pay in                      |

**HTML**

```html
<afterpay-placement
	data-amount="300"
	data-intro-text="Pay in"
	data-currency="USD">
</afterpay-placement>
```

## is-eligible

Accepted values: `true`, `false`\
When true, the price paragraph displays the normal installment messaging.\
When false, the price paragraph renders "Afterpay not available" messaging

For more information see [Set Messaging For Unavailable Items](Advanced-Configuration.mdx)

## locale

Accepted values:  `en_US`, `en_AU`, `en_NZ`, ` en_CA`, ` en_GB`, `fr_CA`

| Country        | Locale | Brand - Language   |
| -------------- | ------ | ------------------ |
| United States  | en_US  | Afterpay - English |
| Australia      | en_AU  | Afterpay - English |
| New Zealand    | en_NZ  | Afterpay - English |
| Canada         | en_CA  | Afterpay - English |
| Canada         | fr_CA  | Afterpay - French  |
| United Kingdom | en_GB  | Afterpay - English |

> **Note**
>
> fr_CA is not currently available using the `<square-placement>` tag.

## logo-type

Accepted values: `badge`, `lockup`, `compact-badge`

| Badge                                                                                                                              | Lockup                                                                                                           | Compact Badge                                                                                                      |
| ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| ![green-badge.png](/_fern-img/a9cddd57325a58c1310f75e4d3d06848e07999750fd5704f82a5701493bf9ad8.webp) See [badge themes](#badge-themes) for all variants | !\[black badge.png]\(../../assets/images/black badge.png>) See [lockup themes](#lockup-themes) for all variants. | !\[compact badge.png]\(../../assets/images/compact badge.png>) See [badge themes](#badge-themes) for all variants. |

**Badge HTML**

**Badge:**

```html
<afterpay-placement
	data-amount="55.95"
	data-locale="en_AU"
	data-logo-type="badge">
</afterpay-placement>
```

**Lockup:**

```html
<afterpay-placement
	data-amount="55.95"
	data-locale="en_AU"
	data-logo-type="lockup">
</afterpay-placement>
```

**Compact Badge:**

```html
<afterpay-placement
	data-amount="55.95"
	data-locale="en_AU"
	data-logo-type="compact-badge">
</afterpay-placement>
```

## lockup-theme

Accepted values are: `mint`, `black`, and `white`
**Mint**
![lockup-mint.png](/_fern-img/405a03f4a1d5ab32355ba9dea17924bc0e82323d8465e1956370594e35245d46.webp)

**Black**
![lockup-black.png](/_fern-img/2e41c7d0f7c5edc2a567c70e18c1d7281d16dc2ed4070caa34bded6db18bee4d.webp)

**White**
![lockup-white.png](/_fern-img/56e3d94918760cab07a8363de40ca59f7fc95741b47870a6c56bc377499c8114.webp)

## mobile-view-layout

Changes the price table layout for mobile devices and on smaller screen sizes.

Accepted values: `two-by-two`, `four-by-one`

![mobile-view-layout.png](/_fern-img/54aed75751a5f97770986670e5bc1358719354cd1e1c8b62fe4ca2d61f3bef70.webp)
Above - `two-by-two` layout.

## modal-id

An attribute provided by Afterpay to display custom modal content.

```html
<afterpay-placement
     data-modal-id="en_US-theme-white-lockup"
     data-amount="400">
</afterpay-placement>
```

## modal-link-style

| Value                 | Column Title                                                                        |
| --------------------- | ----------------------------------------------------------------------------------- |
| circled-info-icon     | ⓘ                                                                                   |
| learn-more-text       | Learn More                                                                          |
| more-info-text        | More Info                                                                           |
| circled-question-icon | ![question-mark.png](/_fern-img/dd56c0f84a903d36e6c1908566baf603ff176580c6c5d8747ead531e7acc325b.webp) |
| none                  | No icon or text displayed                                                           |

**HTML**

```html
<afterpay-placement
     data-locale="en_AU"
     data-currency="AUD"
     data-amount="120.00"
     data-modal-link-style="circled-question-icon">
</afterpay-placement>
```

**Fully Customize "learn more link" using Slots**

Provide a child element to `AfterpayPlacement` with the attribute/value pair `slot="learn-more-link"` to render a custom element which opens the Afterpay information modal when clicked.

For example:

```html
<afterpay-placement>
      <img slot="learn-more-link" src="./custom-info-icon.png" >
</afterpay-placement>
```

## `modal-theme`

Configures the modal theme using one of two predefined colors: `mint` and `white`.

```html
<afterpay-placement
     data-locale="en_AU"
     data-currency="AUD"
     data-amount="120.00"
     data-modal-theme="white">
</afterpay-placement>
```

**White and Mint Modal Themes**

![white-modal.png](/_fern-img/8079ebcad585791c2b1892f6d04a63f6d0128d1388ff43cb1942ea8d9047175e.webp)

## payment-amount-is-bold

Accepts a boolean, `true` , or `false`. True = payment amount is in bold.

You can also apply this attribute to the `afterpay-price-table` component:

![afterpay-price-table.png](/_fern-img/c3d4c4bbbcca86f1b1c09daa47e613034e37917014803e6437eac7b30a98bcee.webp)

In the example above, the \$50 prices are all in bold.

## price-table-theme

Configures the modal theme using one of two predefined colors: `mint` (default), and `white`.

**Mint Theme**

![price-table-theme-mint.png](/_fern-img/4e966b6a4a93f19a8fb5d3b8c542b32158f8b858107aedecee9dc6779f5945be.webp)

**Mint Theme HTML**

```html
<afterpay-placement 
    data-type="price-table" 
    data-price-table-theme="mint" 
    data-amount="200">
</afterpay-placement>
```

**White Theme**

![price-table-theme-white.png](/_fern-img/9d0e43a8d3a5f8352b5cdb4674291fc4caf7a2fa0f4eeefd6220ee1f42012f79.webp)

**White Theme HTML**

```html
<afterpay-placement 
    data-type="price-table" 
    data-price-table-theme="white" 
    data-amount="200">
</afterpay-placement>
```

## show-interest-free

Accepts a boolean, `true` , or `false`. If neither are provided, defaults to `true`

**True example**

\*Or 4 interest-free payments of \$10.25 with \*![](/_fern-img/0d02a2461eb55af0db2ba2fcf068662e918f0b87790eeee8102adde560d1ea54.webp)

**False example**

\*Or 4 payments of \$10.25 with \*![](/_fern-img/0d02a2461eb55af0db2ba2fcf068662e918f0b87790eeee8102adde560d1ea54.webp)

## show-lower-limit

Determines whether to show the lower amount e.g) \*\*$1.00** – $1,000 for products outside of the provided minimum/maximum threshold. See [setting a price range](/afterpay-online-developer/main/guides/afterpay-messaging/javascript-library)

Accepts a boolean, `true` , or `false`. If neither are provided, defaults to `true`

**True example**

![](/_fern-img/0d02a2461eb55af0db2ba2fcf068662e918f0b87790eeee8102adde560d1ea54.webp)*available for orders between $1 - $2,000*.

**False example**

![](/_fern-img/0d02a2461eb55af0db2ba2fcf068662e918f0b87790eeee8102adde560d1ea54.webp)*available for orders over \$1*.

## show-upper-limit

Accepts a boolean, `true` , or `false`. If neither are provided, defaults to `true`.

**True example**

![](/_fern-img/0d02a2461eb55af0db2ba2fcf068662e918f0b87790eeee8102adde560d1ea54.webp)*available for orders between $1 - $2,000*.

**False example**
![](/_fern-img/0d02a2461eb55af0db2ba2fcf068662e918f0b87790eeee8102adde560d1ea54.webp)*available for orders over \$1*.

## show-with

Accepts a boolean, `true` , or `false`. If neither are provided, defaults to `true`

**True example**

*or 4 interest-free payments of \$75.00 with* ![](/_fern-img/0d02a2461eb55af0db2ba2fcf068662e918f0b87790eeee8102adde560d1ea54.webp)

**False example**

*or 4 interest-free payments of \$75.00*![](/_fern-img/0d02a2461eb55af0db2ba2fcf068662e918f0b87790eeee8102adde560d1ea54.webp)

## size

Accepted values: `xs`, `sm`, `md`, `lg`\
The default size for an AfterpayPlacement is **md** (medium).

| Placement Size | Size in Pixels |
| -------------- | -------------- |
| xs             | 12px           |
| sm             | 14px           |
| md             | 16px           |
| lg             | 18px           |

## thousands-separator

Accepts: `"."`, `","`\
Sets how the component should parse the provided amount.

By default, US, CA, AU, and NZ use a **comma** to parse the amount in **thousands**.

However, in Europe, the thousands separator is automatically configured to accept amounts formatted with a **decimal** in the thousands place.

## type

Refer to [constants](#constants) for a list of possible values.

| Name            | Value             | Reference                                 |
| --------------- | ----------------- | ----------------------------------------- |
| PRICE_PARAGRAPH | "price-paragraph" | `Afterpay.placementTypes.PRICE_PARAGRAPH` |
| PRICE_TABLE     | "price-table"     | `Afterpay.placementTypes.PRICE_TABLE`     |

### Price Table

```html
<afterpay-placement
  data-type="price-table"
  data-amount="400"
<Info>
</afterpay-placement
</Info>
```

```JavaScript
const priceTable = new Afterpay.AfterpayPlacement()
priceTable.type = Afterpay.placementTypes.PRICE_TABLE
priceTable.amount = 400;
document.body.appendChild(priceTable);
```

### Price Paragraph

> **Note**
>
> If no the `data-type` attribute is not provided, the `AfterpayPlacement` will default to `PRICE_PARAGRAPH`

**`HTML`**

```html HTML
<afterpay-placement
  data-type="price-paragraph"
  data-amount="400"
<Info>
</afterpay-placement
</Info>
```

```JavaScript
const placement = new Afterpay.AfterpayPlacement()
placement.type = Afterpay.placementTypes.PRICE_PARAGRAPH
placement.amount = 400;
document.body.appendChild(placement);
```

## Constants

| `<CONSTANT_NAME>`      | Values                                                                             |
| ---------------------- | ---------------------------------------------------------------------------------- |
| `currency`             | `AUD`, `CAD` ,`GBP`, `NZD`, `USD`                                                  |
| `locale`               | `EN_AU`, `EN_CA`, `EN_GB`, `EN_NZ`, `EN_US`, `ES_ES`, `FR_FR`, `IT_IT`, `FR_CA`    |
| `logoType`             | `BADGE`, `LOCKUP`                                                                  |
| `modalLinkStyle`       | `CIRCLED_INFO_ICON`, `LEARN_MORE_TEXT`, `MORE_INFO_TEXT`, `CIRCLED_QUESTION_ICON`, |
| `NONE`                 |                                                                                    |
| `placementTypes`       | `PRICE_TABLE`, `PRICE_PARAGRAPH`                                                   |
| `size`                 | `XS`, `SM`, `MD`, `LG`                                                             |
| `mobileViewLayout`     | `FOUR_BY_ONE`, `TWO_BY_TWO`                                                        |
| `theme.`**badge**      | `BLACK_ON_MINT`, `BLACK_ON_WHITE`, `MINT_ON_BLACK`, `WHITE_ON_BLACK`               |
| `theme.`**lockup**     | `BLACK`, `WHITE`, `MINT`                                                           |
| `theme.`**modal**      | `WHITE`                                                                            |
| `theme.`**priceTable** | `BLACK`, `WHITE`                                                                   |

> **📘 Using Afterpay Constants**
>
> Constants are exposed to the window via the Afterpay object `Afterpay.<constant_name>`.
>
> See some examples below
>
> ```js
> console.log(Afterpay.locale.EN_US) //  "en_US"
> console.log(Afterpay.theme.lockup) //  "{"BLACK":"black","WHITE":"white","MINT":"mint"}"
> console.log(Afterpay.theme.lockup.BLACK) //  "black"
>
> ```
>
> Constants are available once the `Afterpay.ready` event has been dispatched.

## Functions

| Name                    | Description                                                                                                                                                      |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `createPlacements`      | Add one or more placements to the page using the targetSelector attribute. [More Info](/afterpay-online-developer/main/guides/afterpay-messaging/advanced-usage) |
| `launchModal`           | Dynamically open the Afterpay Modal                                                                                                                              |
| `generatePaymentAmount` | Given a price, returns the payment amount as a float                                                                                                             |

## Window Events

| Name                  | Description                                                                    |
| --------------------- | ------------------------------------------------------------------------------ |
| `ready`               | Custom Window Event dispatched when `Afterpay.js` is successfully initialized. |
| `modalRenderComplete` | Custom Window Event dispatched when the `<afterpay-modal>` finishes rendering  |

## Constructors

| Name                | Description                                                    |
| ------------------- | -------------------------------------------------------------- |
| `AfterpayPlacement` | Creates and returns a new `AfterpayPlacement` class reference. |

Constructors must be instantiated with "new".

`const Placement = new Afterpay.AfterpayPlacement();`

Full example:

```js
// setup event listener for the Afterpay.js initialization function. 

window.addEventListener("Afterpay.ready", function(){
    const Placement = new Afterpay.AfterpayPlacement();
    Placement.locale = "en_AU";
    Placement.amount = 40.00;   

    const parentElement = document.getElementById("#product-price-wrapper")
    parentElement.appendChild(Placement);

});
```