# Modules

### Module Placement in Template

To incorporate any module into your webstore template:

```
{{ modules | raw }}
```

This placeholder auto-populates with modules you’ve configured in the module section.

***

## 🎁 Gift Card Balance Module

**File Name:** `module.giftcard_balance.html`\
**Directory:** Root

#### Fields

| Name              | Type                     | Description                        |
| ----------------- | ------------------------ | ---------------------------------- |
| `settings.header` | `string`                 | Header of the module               |
| `error`           | `string`                 | Error text if something went wrong |
| `giftCard`        | `giftcard lookup object` | Gift card data object              |

#### Giftcard Lookup Object

| Name               | Type   | Description           |
| ------------------ | ------ | --------------------- |
| `code`             | string | Code of the gift card |
| `balance`          | int64  | Current balance       |
| `starting_balance` | int64  | Starting balance      |
| `expires_at`       | string | Expiration date       |

***

## 💳 Recent Payments Module

**File Name:** `module.recent_payments.html`\
**Directory:** Root

#### Fields

| Name                               | Type     | Description                       |
| ---------------------------------- | -------- | --------------------------------- |
| `settings.header`                  | string   | Header of the module              |
| `settings.displayLimit`            | int64    | Number of payments to display     |
| `settings.displayFreePayments`     | bool     | Display free payments             |
| `settings.displayTimeOfPurchase`   | bool     | Display time of payment           |
| `settings.displayPriceOfPurchase`  | bool     | Display price of purchase         |
| `settings.displayPurchasedProduct` | bool     | Display purchased product details |
| `orders`                           | order\[] | List of recent orders             |

#### Order Object

| Name           | Type     | Description                              |
| -------------- | -------- | ---------------------------------------- |
| `total_amount` | number   | Total amount of the order                |
| `completed_at` | string   | Completion date of the order             |
| `customer`     | customer | Customer who made the payment            |
| `lines`        | line\[]  | Order lines (if product display enabled) |

#### Customer Object

| Name               | Type   | Description      |
| ------------------ | ------ | ---------------- |
| `id`               | flake  | Customer ID      |
| `steam.name`       | string | Steam name       |
| `steam.avatar_url` | string | Steam avatar URL |
| `name`             | string | Customer name    |

#### Order Line Object

| Name                | Type   | Description          |
| ------------------- | ------ | -------------------- |
| `product_id`        | flake  | Product ID           |
| `product_name`      | string | Product name         |
| `product_image_url` | string | Product image URL    |
| `gift`              | bool   | Was it a gift?       |
| `price`             | int64  | Price of the product |
| `total_amount`      | int64  | Total paid amount    |
| `quantity`          | int64  | Quantity ordered     |

***

## 📝 Text Box Module

**File Name:** `module.text_box.html`\
**Directory:** Root

#### Fields

| Name              | Type   | Description             |
| ----------------- | ------ | ----------------------- |
| `settings.header` | string | Header of the module    |
| `content`         | string | HTML content of the box |

***

## 🎯 Payment Goal Module

**File Name:** `module.payment_goal.html`\
**Directory:** Root

#### Fields

| Name                                 | Type    | Description                             |
| ------------------------------------ | ------- | --------------------------------------- |
| `settings.header`                    | string  | Header of the module                    |
| `settings.period`                    | string  | Time period for the goal                |
| `settings.goalTarget`                | int64   | Goal amount in store’s default currency |
| `settings.displayAbsoluteGoalAmount` | boolean | Display the absolute goal amount        |
| `settings.allowPercentageOverflow`   | boolean | Allow % to go above 100%                |
| `settings.animateGoalBar`            | boolean | Animate the progress bar                |
| `settings.barStyle`                  | string  | `striped` or `normal`                   |
| `revenue`                            | string  | Current revenue value toward the goal   |

***

## 🏆 Top Customer Module

**File Name:** `module.top_customers.html`\
**Directory:** Root

#### Fields

| Name                                  | Type        | Description                                 |
| ------------------------------------- | ----------- | ------------------------------------------- |
| `settings.header`                     | string      | Header of the module                        |
| `settings.period`                     | string      | Time period used to calculate top customers |
| `settings.field`                      | enum        | Field to sort customers by                  |
| `settings.limit`                      | int64       | Max number of customers to display          |
| `settings.displayCustomerSpendAmount` | bool        | Show spend amount per customer              |
| `customers`                           | customer\[] | List of top customers                       |

**Allowed Enum Values**

* `total_spend_amount_gross`
* `total_spend_amount_net`
* `average_spend_amount_gross`
* `average_spend_amount_net`
* `total_payments`

#### Top Customer Object

| Name                               | Type   | Description              |
| ---------------------------------- | ------ | ------------------------ |
| `id`                               | flake  | Customer ID              |
| `steam.name`                       | string | Steam name               |
| `steam.avatar_url`                 | string | Steam avatar             |
| `name`                             | string | Customer name            |
| `stats.total_spend_amount_gross`   | int64  | Total gross spend amount |
| `stats.total_spend_amount_net`     | int64  | Total net spend amount   |
| `stats.average_spend_amount_gross` | int64  | Average gross spend      |
| `stats.average_spend_amount_net`   | int64  | Average net spend        |
| `stats.total_payments`             | int64  | Total number of payments |

## 📦 Featured Product Module

**File Name:** `module.featured_product.html`\
**Directory:** Root

#### Fields

| Name              | Type                                                                  | Description                 |
| ----------------- | --------------------------------------------------------------------- | --------------------------- |
| `settings.header` | string                                                                | Header of the module        |
| `product`         | [StorefrontProductDto](/storefront-headless/storefront-api/models.md) | The featured product object |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.paynow.gg/hosted-webstores/modules.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.