> ## Documentation Index
> Fetch the complete documentation index at: https://docs.manalens.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# itch.io

> Connect an itch.io API key to record purchases of your game as revenue for the users who made them, matched by email.

Many indie games sell on itch.io. This integration finds the itch.io purchases of your identified users and records them as revenue. It uses only an email address that your server sent with the secret key. Then [Revenue](https://docs.manalens.dev/features/revenue.md) and [attribution](https://docs.manalens.dev/attribution/models.md) show which channels and campaigns sell your game.

| Data | How it gets here | What it shows |
| - | - | - |
| Purchases | A sync asks itch.io for the purchases of each user, by the email that your server sent | One revenue record for each purchase, linked to the user |

## What you need

* The owner or admin role and a verified [MFA](https://docs.manalens.dev/security/mfa.md) session.
* An itch.io API key. Create it in your itch.io account settings, under **API keys**.
* The project **Secret key**, to send each user's email from your server. See [server events](https://docs.manalens.dev/sdks/server.md).

## Send the email from your server

Email matching uses only an email that your server sent with the secret key, in an `identify` event with `channel: 'server'`. Use the email address that the player uses on itch.io.

```ts theme={null}
await fetch('https://api.your-domain.com/v0/events', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.ANALYTICS_SECRET_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    events: [
      { channel: 'server', type: 'identify', user_id: 'player_123',
        traits: { email: 'player@example.com' } },
    ],
  }),
});
```

> [!WARNING]
>
> An email that a website or a game sets with `identify` is never sent to itch.io and never matched. A client can write any address, so a user could enter the address of another person and get that person's purchase. Your server must send the address, and only after it verified that the address belongs to the user, for example with a confirmation link or a sign-in provider that gives a verified address. itch.io gives the same advice for its email lookups.

## Connect itch.io

**1. Add the API key**

Open your project's **Settings**, then the **Integrations** tab. In the **itch.io** section, paste the API key and select **Connect itch.io**. We check the key with itch.io. We store it encrypted and never show it again.

**2. Choose your game**

Select the game from the list of games on your itch.io account. One project connects to one game.

**3. Turn on email matching**

Select **Match purchases by email**. Read the next section first.

**4. Run the first sync**

Select **Sync now**. After that, the sync runs one time each day.

## Email matching and privacy

itch.io does not give a list of all purchases. It answers only one question: "Which purchases did this email address make for this game?" So the sync must send email addresses to itch.io.

* **When "Match purchases by email" is on**, we send the email address that your server sent for each user of this project to itch.io (`api.itch.io`). We send nothing else about the user. We never send an email that only a website or a game set.
* **It is on by default.** After you connect a key and choose a game, the sync starts. Nothing is sent before you choose a game.
* **When it is off**, we send no email address to itch.io.
* You can turn it off at any time. The sync then stops. Purchases that are already recorded stay in your reports.

Tell your players about this in your privacy policy, or turn it off. An email address is personal data, and itch.io receives it also for users who bought nothing there.

We do not store the email address a second time for this integration. We keep a list of the user IDs that we checked, with the time of the check, and a list of the purchase IDs with the user ID that each one belongs to. We do not read download keys.

## Protection against a false email address

The sync has three fixed rules:

* **Only a server email is used.** The address comes from the latest server `identify` event that has an `email` trait. A later `identify` from a website or a game does not change it. To remove a user from matching, send `email: null` from your server.
* **A shared address is not matched.** If your server sent the same email address for more than one user of your project, the sync matches none of them. It sends nothing to itch.io for them and records no purchase. Upper case and lower case are the same address.
* **One purchase belongs to one user.** After a purchase is recorded for a user, it is never recorded for a different user of the project. This stays true after a disconnect.

Your server is the source of trust. If it sends an address that it did not verify, the first user who has the address gets its purchases.

## How the sync works

* The sync checks each user who has an email from your server. It checks a user again at most one time in 24 hours, and only if the user was active after the last check.
* When your server sends a new email for a user, the user is checked again with the new address.
* The work is limited in each run. A large project needs more than one run to check every user. **Sync now** continues where the last run stopped.
* If itch.io is slow or refuses requests, the sync waits and tries again later.

## The itch.io view on Overview

On the **Overview** page, open the source picker (left of the live visitor count) and choose **itch.io**.

* **Views, downloads, payments and gross revenue** for each day of the date range, with the all-time totals. These numbers come from itch.io.
* **Channels and sources** of the payments that matched your users, with the website visit that brought each buyer.
* **Game events** from a build with `storefront: itch`.
* **Release marks.** A dashed line on the chart for each day that a new build of your game went up (the version of each channel, for example `web-demo`). Use it to see if a build moved the numbers.

itch.io gives only totals since the game was made. So we keep the totals of each day (UTC) and show the difference. Daily numbers start on the day after you connect; a day before that shows 0. If we miss a day, its numbers count on the next day that we read. Referrers, browser plays and impressions are not in the itch.io API.

## Where the data shows

Each purchase is a revenue event with the provider `itch`. Its event name is `purchase` and its channel is `itch`, the same pattern as Stripe and Paddle payments. When itch.io marks the payment as a donation (a payment on a browser game that gives no download key), the event has the property `donation: true`. It shows in the same places as Stripe and Paddle revenue: the revenue report, the user's profile, and [attribution](https://docs.manalens.dev/attribution/models.md) with `purchase` as the goal.

A website or a game can send its own `purchase` event, but it cannot send the channel `itch`. So a payment record with that channel is always a verified record. When a user has a payment record, the reports leave out that user's own `purchase` events, so one sale is counted once.

The event belongs to the user whose email matched. So it joins that user's profile and every browser and game install that is linked to the user, and attribution credits the user's earlier website visits.

| Field | Value |
| - | - |
| Amount | The price that the buyer paid, from itch.io. This is gross revenue: itch.io's share and payment fees are not subtracted |
| Currency | The currency of the purchase. Reports convert it to your project's currency |
| Date | The date of the purchase on itch.io |
| `source` | The payment source that itch.io reports, for example `paypal` |
| `sale_rate` | The sale discount that itch.io reports for the purchase |
| `purchase_type` | `game`, `bundle` or `sub_product` |

## Limits

* A purchase matches only when the email from your server is the email address of the itch.io purchase.
* An email from the web SDK, a game SDK, or a trait edit in the dashboard or the API is not used.
* itch.io returns completed purchases only. Refunds are not imported.
* For a bundle purchase, itch.io reports the price of the full bundle. That full price is recorded.
* If two or more users have the same email address, none of them is matched. Send `email: null` from your server for the wrong user to match the right one.
* A purchase with a price that we cannot read is skipped, not guessed.
* Short links with UTMs for itch.io pages are not part of this integration. Use [short links](https://docs.manalens.dev/features/short-links.md) to tag your links.

## Disconnect

Select **Disconnect** to delete the API key and the list of checked users. Recorded purchases stay in your reports. The list of purchase IDs and their users also stays, so that a purchase cannot go to a different user later.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.