What you need
- The owner or admin role and a verified MFA 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.
Send the email from your server
Email matching uses only an email that your server sent with the secret key, in anidentify event with channel: 'server'. Use the email address that the player uses on itch.io.
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.
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
identifyevent that has anemailtrait. A lateridentifyfrom a website or a game does not change it. To remove a user from matching, sendemail: nullfrom 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.
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.
Where the data shows
Each purchase is a revenue event with the provideritch. 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 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.
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: nullfrom 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 to tag your links.