When creating sub-product/DLCs on itch.io you can provide aredeem URL toallow people to claim what they've purchased on your own website. This willenable you to sell digital goods using itch.io’s payment infrastructure forproducts that are offered on your own website or service.

Initiating the purchase

Use your project’s purchase URL, likehttps://leafo.itch.io/x-moon/purchase,and append a product ID to the URL. You can use eithersub_product_id tospecify the ID shown on your dashboard, or you can useexternal_product_idto use theexternal ID that you provided when creating the sub-product.

Using the Redeem URL

You can provide a redeem URL on the bottom of the Sub-products & DLC dashboardpage. When you first set a redeem URL, a secret token is generated for thatproject page.Treat this token as a password, you will use it to verify theauthenticity of requests from itch.io.

After purchasing a product, the buyer is presented with a button to claimaccess to what they bought. They are redirected in their browser with a GETrequest to the URL you provided with ajwt query parameter appended.

This is aJWT-encoded payload object that contains information aboutwhat was bought. Use thesecret token provided on the Sub-products dashboardpage to verify the integrity of the JWT payload.

Payload Structure

The structure of the payload after being decoded is:

{"purchase_id":100,"sub_product_id":101,"external_id":"my_product","iat":1554207516,"exp":1554208126}

Recording a Purchase

When a buyer is redirected to your redeem URL it’s your responsibility to credittheir account on your service. Before doing this you should verify theauthenticity of the JWT token using the secret key provided by the itch.iodashboard. Ignoring this step may lead to people abusing your redeem URL toobtain digital goods without paying.

As part of crediting the account, you should record thepurchase_id field inyour database, and reject any attempts to redeempurchase_ids that havealready been used. Generally you'll only want to grant access to the product ifsomeone hasn’t already redeemed it.

Note: Be careful about how you record the purchase ID and grant access tothe product. We recommend using atomic operations in the following order:

1. Attempt to recordpurchase_id, halt if it already exists (e.g.insert on conflict ignore)
2. Grant access to product

Failure to follow this pattern may enable malicious users to “double claim”products on your service by submitting multiple requests at the same time.

Dynamically Pulling Products

If you want to dynamically populate your website with the products you'vecreated on the itch.io dashboard you can use theitch.io JavaScriptAPI to pull information aboutyour project. UsingItch.getGameData() you can retrieve a game object includingproducts in the following format:

{"id":134,"title":"Botster Land","price":"$0.00","sale":false,"sub_products":[{"id":201,"name":"100 Gold Coins","price":"$5.00",},{"id":202,"name":"200 Gold Coins","price":"$8.00",}]}

Note: Any unpublished or archived products will not be returned.

Metadata

You can store your own data alongside a purchase on itch.io by providing ametadata parameter to the purchase URL.

Example use-cases of metadata include:

• Associating an account ID from your own service to an itch.io purchase
• Attributing a source where a purchase came from by generating unique URLs for each location
• Storing a product configuration so the correct good can be granted after purchase

Themetadata parameter must be a signed JWT object to prevent unauthorizedusers from tampering with the stored data.

JWT encode an object using theRedeem URL secret key described above and passit in as the query parametermetadata to the purchase URL. You can verify themetadata by viewing the purchase URL while logged into an account that can editthat project. A validmetadata parameter will show the contents of themetadata to you above the payment field. An invalidmetadata will display anerror message describing what the issue is.

The entire length of the encoded metadata payload must be less than 1024characters. Additionally, any JWTstandard fields (i.e.iat) will bestripped from the provided object. Fields with the valuenull will be strippedentirely. Any other regular JSON values are supported.

Reading the metadata

The metadata is made available to the seller in the following places:

• On the payments section in your dashboard, the details dialog will show any metadata you provided
• The JWT payload sent to your return URL will contain a metadata field with all the metadata you provided

Note: In the future, the itch.io API will also return this data