---
url: https://docs.dataflair.ai/dataflair/wordpress-plugin.md
description: >-
  Install the DataFlair Toplists plugin, connect it to your tenant with a bearer
  token, sync toplists and brands, and place them with a block or a shortcode.
---

# WordPress plugin

The DataFlair Toplists plugin is a working client of the [Toplist API](/dataflair/toplist-api/). It fetches your toplists and brands from DataFlair, stores them in your WordPress database, and renders them with a block or a shortcode. It makes no call to DataFlair when a visitor loads a page.

This is the fetch-ahead pattern described in the [Integration model](/dataflair/toplist-api/integration-model). The plugin also applies the geo rules in [Geo-targeting and compliance](/dataflair/toplist-api/geo-targeting) when it renders.

## Requirements

* WordPress 6.3 or later
* PHP 8.1 or later
* MySQL 5.7 or later, or MariaDB 10.3 or later, for JSON columns

## Install

1. Upload the `dataflair-toplists` folder to `/wp-content/plugins/`.
2. Activate the plugin in **Plugins**, then **Installed Plugins**.
3. Connect it to your tenant. See the next section.

The plugin includes its dependencies, so you do not run `composer install` on the server.

## Connect

Go to **DataFlair**, then **Settings**, then the **API Connection** tab.

| Field | What to enter |
| --- | --- |
| **API Bearer Token** | Your DataFlair API bearer token. Use the static token. See [Authentication](/dataflair/toplist-api/authentication). |
| **API Base URL** | Your tenant URL with the API path, for example `https://tenant.dataflair.ai/api/v1`. Leave it empty to let the plugin detect it from the token. |
| **Brands API Version** | `v1` or `v2` of the brands endpoint. |

Click **Test Connection**. It checks the toplists endpoint, which always uses `v1`. It does not exercise the Brands API Version you chose.

A wrong token gives `401`. A token without the `toplist:read` scope gives `403`. See [Error handling](/guide/error-handling).

## Sync

The plugin copies data from DataFlair into three tables in your database: `wp_dataflair_toplists`, `wp_dataflair_brands` and `wp_dataflair_alternative_toplists`.

Start a sync in one of two ways:

* **In WordPress.** On **DataFlair**, then **Dashboard**, click **Sync Brands** and **Sync Toplists**.
* **With WP-CLI.**

  ```bash
  wp dataflair sync                    # everything
  wp dataflair sync --only=toplists    # toplists only
  wp dataflair sync --only=brands      # brands only
  ```

  The command exits with a non-zero code when it fails, so a real cron job can react. It backs off on API rate limits.

The plugin has **no automatic WP-Cron schedule**. To sync on a schedule, add the WP-CLI command to your server crontab. The **Sync Schedule** tab in Settings shows an example, and it holds a retry count and an alert email.

### Webhook sync

On the **API Connection** tab, tick **Enable webhook sync**. DataFlair then pushes changes to your site as they happen, instead of waiting for the next sync. The plugin registers your site with DataFlair, and it reuses your API token. A delivery is signed with HMAC-SHA256 and verified before anything else runs. A repeated delivery does nothing.

## Place a toplist

**Block.** Add the **DataFlair Toplist** block to a page or post. In the block settings, choose a toplist and set an item limit.

**Shortcode.**

```text
[dataflair_toplist id="123" limit="10"]
```

| Attribute | Required | Meaning |
| --- | --- | --- |
| `id` | yes, unless you use `slug` | The DataFlair toplist ID. |
| `slug` | no | Look the toplist up by its slug instead of its ID. |
| `title` | no | Replaces the display title of the toplist. |
| `limit` | no | The most brands to show. The default, `0`, shows all. |

The shortcode also accepts `layout`, `ctaMode`, `template` and `auto_geo`.

## Test this

Add a toplist to a page and view it while logged out. The plugin reads from your database, so a missing toplist means the sync did not run or did not finish. Check **DataFlair**, then **Dashboard**, for the last sync time, and **Tools** for the **API Contract Check** diagnostic.