Why does itch.io need an email to match a purchase?

Because the API has no list of all purchases. The purchases endpoint returns the completed purchases of one email address or one itch.io user ID for a game. The download keys endpoint does the same for keys. So to connect a sale to a player, you must ask with something you already know about the player.

Sources: itch.io Serverside API reference.

Why must the email come from my server?

Because a client can write any address. itch.io says you are responsible for verifying the email address first, since people could otherwise enter another address to claim a purchase. So Manalens uses only an email that your server sent with the Secret key, in an identify event. An email that a website or a game sets is never sent to itch.io.

Verify the address before you send it, for example with a confirmation link or a sign-in provider that gives a verified address.

Send a verified email from your server

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' } },
    ],
  }),
});

Sources: itch.io Serverside API reference; Manalens itch.io documentation.

How do I set up email matching?

Connect an API key, choose the game, and send verified emails. You need the owner or admin role and a verified MFA session.

  1. Create an API key in your itch.io account settings, under API keys.
  2. In Manalens, open Settings, Integrations, itch.io, paste the key and select Connect itch.io.
  3. Choose the game. One project connects to one game.
  4. Check that Match purchases by email is on. It is on by default after you choose a game.
  5. From your server, send an identify event with the verified email for each player.
  6. Select Sync now. After that the sync runs once a day.

Sources: Manalens itch.io documentation.

What happens when a purchase matches?

It becomes a revenue event on the player's profile. The event is purchase, with the channel itch. When itch.io marks the payment as a donation, the event has the property donation. A player with a download key but no purchase gets no event; only payments are recorded.

The event joins every browser and game install linked to the player. So attribution can credit the website visit or short link that brought the player, with purchase as the goal.

FieldValue
AmountThe gross price the buyer paid, before the itch.io share and payment fees
CurrencyThe purchase currency, converted to the project currency in reports
DateThe purchase date on itch.io
sourceThe payment source that itch.io reports, for example paypal
sale_rateThe sale discount that itch.io reports
purchase_typegame, bundle or sub_product

Sources: Manalens itch.io documentation.

How does the sync protect against a false address?

With three fixed rules. Only a server email is used. If your server sent the same address for more than one player, none of them is matched and nothing is sent to itch.io for them. And a purchase that is recorded for one player is never recorded for a different player.

The sync checks a player again at most once in 24 hours, and only if the player was active after the last check, or the email changed.

Sources: Manalens itch.io documentation.

What should I tell players about privacy?

That you send their email address to itch.io to find their purchases. An email is personal data, and itch.io receives it also for players who bought nothing there. Mention it in your privacy policy, or turn matching off. When it is off, no email is sent to itch.io. Manalens stores a keyed hash of the address for the check, never the address a second time, and never a download key.

Sources: Manalens itch.io documentation.

What are the limits?

A purchase matches only when your server's email is the email of the itch.io purchase. itch.io also matches verified emails linked to the buyer's account. Amounts are gross. Refunds are not imported. For a bundle, itch.io reports the full bundle price. A purchase with a price that cannot be read is skipped, not guessed.

If a player says a purchase is missing, check that the email from your server is the email of the itch.io purchase. Upper case and lower case count as the same address.

Sources: itch.io Serverside API reference; Manalens itch.io documentation.

How long until matched purchases show?

Usually after the next daily sync. The sync runs once a day, and Sync now starts it at once. Each run does a limited amount of work, so a large project needs more than one run to check every player. Sync now continues where the last run stopped. If itch.io is slow or refuses requests, the sync waits and tries again later.

Sources: Manalens itch.io documentation.

Can I match by itch.io user ID instead of email?

The itch.io API can, but this integration uses email. itch.io can look up purchases by user ID, and says a user ID from the itch.io app manifest is impossible for users to spoof. For players who sign in with itch.io OAuth, the ownership endpoint checks ownership from their token.

Manalens matches by the email that your server sent. If you already use itch.io sign-in, check ownership in your own game server too.

Email matching also works for players who never signed in with itch.io in your game. They only need to buy with the same email address that your server verified.

Sources: itch.io Serverside API reference; Manalens itch.io documentation.

Which players does the sync check?

Only players with a server email who were recently active. The sync checks a player again at most once in 24 hours, and only if the player was active after the last check, or the server sent a new email. A player whose email you set to null from your server is removed from matching.

Sources: Manalens itch.io documentation.

How do I start matching purchases?

Manalens is the analytics and growth engine built for games. Connect the itch.io API, send verified emails from your server, and run the first sync. Then open Attribution with purchase as the goal to see which channels and campaigns sell the game.

Sources: Manalens product documentation.

Frequently asked questions

Can I see all itch.io purchases through the API?

No. The itch.io API does not list all purchases. It answers per email address or per itch.io user ID. That is why the sync asks about each player whose verified email your server sent. The total count of purchases is available, without buyer details.

Why can my game not send the email itself?

A game or a website can send any address, so a player could type the address of another person and get the purchases of that person. itch.io says you must verify the address first. Manalens only uses an email that your server sent with the Secret key.

Are refunds removed from matched purchases?

No. itch.io returns completed purchases only, and refunds are not imported. Amounts are gross: the itch.io share and payment fees are not subtracted. Use the itch.io payouts page for net amounts after the itch.io share, the payment fees and any refunds.

What happens when I disconnect itch.io?

The API key and the list of checked players are deleted. Purchases and key claims that were recorded stay in your reports. The list of purchase IDs and their players also stays, so that a purchase cannot go to a different player if you connect again later.

Sources and implementation