---
title: Customize Offer Unit Timing
slug: customize-offer-unit-timing
icon: ⏰
docTags: 
createdAt: 2025-07-29T11:34:34.970Z
---

:::hint{type="info"}
**Who is this for:** Developers using the MomentPerks JavaScript SDK who need to control exactly when offers are fetched and displayed in single-page applications or multi-step flows.

**Outcome:** Configure autoLoad and autoShow options-and use refresh() and reload()-to precisely control offer timing based on user context or application state.
:::

# Overview

By default, the MomentScience JavaScript SDK automatically fetches and displays the Moments Offer Unit when initialized. This behavior is controlled using two configuration options: `autoLoad`and `autoShow`.

You can modify these options to delay when offers are fetched or shown, for example, in single-page applications or multi-step checkout flows where user data isn’t immediately available.

This guide explains how to:

- Configure `autoLoad`to delay fetching Offers
- Configure `autoShow`to delay displaying the Offer Unit
- Use `refresh()` to fetch a new set of Offers
- Use `reload()` to redisplay a previously fetched Offer Unit
- Understand how different configuration combinations affect SDK behavior

## Default behavior

If no configuration changes are made:

- **Offers are fetched** **automatically **when the SDK loads (`autoLoad: true`).
- **Offers are displayed** **immediately **after being fetched (`autoShow: true`).

This behavior is suitable for most use cases, especially when no conditional logic is required to determine when offers appear.

```mermaid
flowchart TD
    A[SDK Initialization] --> B{autoLoad?}
    
    B -- Yes --> C[Fetch Offers Automatically]
    B -- No --> D[Wait for Adpx.refresh]

    C --> E{autoShow?}
    D --> F{autoShow?}

    E -- Yes --> G[Display Offers Automatically]
    E -- No --> H[Wait for Adpx.reload]

    F -- Yes --> G
    F -- No --> H

    G --> I[User Closes Offer Unit]
    I --> J[User Reopens via Adpx.reload]

    D --> K[Optional: setPayload before refresh]

    %% Node styles
    style A fill:#233D71,stroke:#233D71,stroke-width:2px,color:#ffffff
    style B fill:#F3F3F3,stroke:#6E6D7A,color:#1A2B49
    style C fill:#3B82F6,stroke:#233D71,color:#ffffff
    style D fill:#FE4215,stroke:#FE4215,color:#ffffff
    style E fill:#F3F3F3,stroke:#6E6D7A,color:#1A2B49
    style F fill:#F3F3F3,stroke:#6E6D7A,color:#1A2B49
    style G fill:#3B82F6,stroke:#233D71,color:#ffffff
    style H fill:#FE4215,stroke:#FE4215,color:#ffffff
    style I fill:#F9F9F9,stroke:#6E6D7A,color:#6E6D7A
    style J fill:#3B82F6,stroke:#233D71,color:#ffffff
    style K fill:#F3F3F3,stroke:#6E6D7A,color:#1A2B49
```

# Controlling Display Behavior

To take control over when offers are retrieved or shown, use the `autoLoad`and `autoShow`configuration options.

## Delay Fetching Offers (`autoLoad `)

To delay the initial API call for fetching offers, set `autoLoad`to `false`in your configuration object:

:::CodeblockTabs
Disable Auto Loading

```javascript
window.AdpxConfig = {
  accountId: 'YOUR_SDK_ID',
  autoLoad: false
};
```
:::

With `autoLoad: false`, the SDK will not request offers when initialized. Instead, you must manually trigger the fetch using `window.Adpx.refresh()`.

### Manually Fetching Offers (`refresh()`)

To retrieve offers at a specific time, call the `refresh()` method, this allows you to:

- Fetch new offers based on updated session or user state
- Control when offers are retrieved within your app flow

:::CodeblockTabs
Manually Fetch Offers

```javascript
window.Adpx.refresh();
```
:::

:::hint{type="warning"}
If you’ve updated the payload, make sure to call `setPayload()` before `refresh()` so the new data is included in the request.
:::

### Updating the Payload (`setPayload()`)

Use`setPayload()` to define or update the values passed to the offer API. This is especially useful in scenarios where user context or transaction data changes before fetching offers.

:::CodeblockTabs
setPayload()

```javascript
window.Adpx.setPayload({
  user_id: '1234',
  category: 'electronics'
});
window.Adpx.refresh();
```
:::

***

## Preventing Automatic Display (`autoShow` )

By default, offers are displayed immediately after they’re fetched. To delay this behavior, set `autoShow`to `false`:

:::CodeblockTabs
Auto Show = False

```javascript
window.AdpxConfig = {
  accountId: 'YOUR_SDK_ID',
  autoLoad: true,
  autoShow: false
};

```
:::

With `autoShow: false`, offers will be fetched but not shown automatically. You must explicitly call `reload()` to display the Offer Unit.

### Manually Display Offers(`reload()`)

Use the `reload()` function to show the Offers Unit after offers have been fetched:

```javascript
window.Adpx.reload();
```

This displays the current set of fetched offers. It’s useful when:

- A user previously closed the Offers Unit
- You want to re-display existing offers without re-fetching them

:::hint{type="info"}
`reload()` does not fetch new offers. Use `refresh()` for that purpose.
:::

## Combined Configuration Scenarios

This table summarizes how the SDK behaves under different autoLoad and autoShow settings:

| **autoLoad** | **autoShow** | **SDK behavior**                                                                                     |
| ------------ | ------------ | ---------------------------------------------------------------------------------------------------- |
| true         | true         | Offers are fetched and displayed automatically. *(Default)*                                          |
| false        | true         | Offers must be fetched manually using refresh(). Once fetched, the Offer Unit appears automatically. |
| false        | false        | Offers must be fetched manually using refresh(), and displayed manually using reload().              |
| true         | false        | Offers are fetched automatically, but you must call reload() to display them.                        |

# Re-Displaying and Re-Fetching Offers

## Redisplaying Previously Fetched Offers (`reload()`)

Use the `reload()` method to redisplay the current set of Offers without making a new request to the backend.

:::CodeblockTabs
Redisplaying Previously Fetched Offers (reload())

```javascript
window.Adpx.reload();
```
:::

This is helpful in cases where:

- A user previously dismissed the Moments Offer Unit and wants to see the Offers again
- You want to show the same Offers on a new screen or state change in your app

:::hint{type="info"}
`reload()` does not fetch new Offers. It redisplays the last fetched set, starting from the first Offer.
:::

## Fetching a New Set of Offers (`refresh()`)

To fetch a new set of Offers, especially after user data or app context has changed, use the `refresh()` method:

:::CodeblockTabs
Fetching a New Set of Offers (refresh())

```javascript
window.Adpx.refresh();
```
:::

If the payload has changed (e.g., new user\_id, category, or location), call `setPayload()` before calling `refresh()`:

```javascript
window.Adpx.setPayload({
  user_id: '5678',
  category: 'home-goods'
});

window.Adpx.refresh();

```

Use this method when:

- New user attributes should influence the Offers shown
- Offers should reflect updated application context or session state
- You want to dynamically rotate the content of the Offer Unit

***

 If you're running into any issues while going through the integration process, feel free to contact us at [help@momentscience.com](mailto\:help@Momentscience.com)