# Marketplace Integration

PteroCA includes a built-in integration with the [PteroCA Marketplace](https://marketplace.pteroca.com), allowing administrators to browse and discover plugins directly from within the admin panel.

> **Added in:** v0.6.4

## Overview

The Marketplace Integration provides the following features:

* Browse plugins published on the official PteroCA Marketplace
* Filter plugins by tags and categories
* Sort by newest, most popular, or highest rated
* View plugin details, ratings, and links to the marketplace listing
* Follow download links to [marketplace.pteroca.com](https://marketplace.pteroca.com) to obtain plugin ZIP files

## Requirements

To use the Marketplace Integration, the following conditions must be met:

* The administrator must have the `access_plugins` permission assigned to their role (see [Access Control](/access-and-permissions/access-control.md))
* The PteroCA server must have outbound network access to `marketplace.pteroca.com` on port 443 (HTTPS)

## Accessing the Marketplace

1. Log in to the **Admin Panel**.
2. Navigate to **Plugins** in the sidebar.
3. Click the **Marketplace** tab at the top of the page.

The marketplace browser will load, displaying available plugins from the PteroCA Marketplace.

## Browsing and Filtering

### Sorting Options

| Sort Option       | Description                                   |
| ----------------- | --------------------------------------------- |
| **Newest**        | Most recently published plugins first         |
| **Most Popular**  | Plugins with the highest download count first |
| **Highest Rated** | Plugins with the best community rating first  |

### Tag Filters

Use the tag filter buttons at the top of the marketplace browser to narrow results by category (e.g., billing, integration, game support, utility).

### Pagination

Results are paginated with a maximum of **30 plugins per page**. Use the pagination controls at the bottom of the list to navigate between pages.

## Installing a Plugin from the Marketplace

1. Browse or search for the desired plugin in the **Marketplace** tab inside the admin panel.
2. Click the **Download** button on the plugin listing — this opens the plugin's page on [marketplace.pteroca.com](https://marketplace.pteroca.com).
3. Download the plugin ZIP file from the marketplace website.
4. Return to the admin panel and navigate to the **Upload** tab (or the plugin upload form).
5. Upload the downloaded ZIP file.
6. Once uploaded, activate the plugin from the plugin list.

For detailed installation instructions, see [Managing Plugins](/using-pteroca/admin-panel/managing-plugins.md).

## Technical Details

### API Endpoint

The in-panel marketplace browser fetches data from:

```
/panel/marketplace-api/products
```

This is a server-side proxy endpoint that forwards requests to `marketplace.pteroca.com` and returns the results to the panel frontend.

**Supported query parameters:**

| Parameter | Type    | Description                               |
| --------- | ------- | ----------------------------------------- |
| `page`    | integer | Page number (default: 1)                  |
| `sort`    | string  | Sort order: `newest`, `popular`, `rating` |
| `tag`     | string  | Filter by tag slug                        |

### Caching

Marketplace responses are cached for **6 hours** on the server side. This reduces latency and external API calls. To force a refresh, clear the application cache:

```bash
docker exec -it pteroca_web_dev bin/console cache:clear
```

### Timeout

If the marketplace API does not respond within **5 seconds**, the request times out and an error message is displayed in the browser.

## Troubleshooting

### Marketplace Does Not Load

If the Marketplace tab shows an error or blank content:

1. Verify outbound connectivity from your server:

   ```bash
   docker exec -it pteroca_web_dev curl -I https://marketplace.pteroca.com
   ```
2. Confirm the response is `HTTP/2 200`. If you receive a connection error, check your server's firewall rules and DNS configuration.
3. Clear the application cache and reload:

   ```bash
   docker exec -it pteroca_web_dev bin/console cache:clear
   ```

### "Access Denied" or Marketplace Tab Not Visible

If the Marketplace tab is not visible or you see an access denied error:

* Ensure your administrator role has the `access_plugins` permission.
* See [Access Control](/access-and-permissions/access-control.md) for instructions on managing role permissions.

## Related Documentation

* [Managing Plugins](/using-pteroca/admin-panel/managing-plugins.md)
* [Access Control](/access-and-permissions/access-control.md)
* [Plugin Development — Plugin Manifest](/for-developers/plugins/plugin-manifest.md)


---

# 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.pteroca.com/core-configuration/marketplace-integration.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.