sub_products.md

{ title: "Sub-product & DLC Redeem URLs" }

$index

When creating sub-product/DLCs on itch.io you can provide a redeem URL to allow people to claim what they've purchased on your own website. This will enable you to sell digital goods using itch.io's payment infrastructure for products that are offered on your own website or service.

Using the Redeem URL

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

After purchasing a product, the buyer is presented with a button to claim access to what they bought. They are redirected in their browser with a GET request to the URL you provided with a jwt query parameter appended.

This is a JWT-encoded payload object that contains information about what was bought. Use the secret token provided on the Sub-products dashboard page 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
}

purchase_id	The unique ID of the payment on the itch.io server. This can be used to reference the transaction using the itch.io API
sub_product_id	The unique ID of the sub-product that was purchased, provided by itch.io
external_id (optional)	The External ID that you provided when configuring your sub-product. We recommend using this to identify the type of thing purchased in your app.
iat	When the JWT token was issued, Unix timestamp
exp	When the JWT token should be treated as expired, Unix timestamp

Recording a Purchase

When a buyer is redirected to your redeem URL it's your responsibility to credit their account on your service. Before doing this you should verify the authenticity of the JWT token using the secret key provided by the itch.io dashboard. Ignoring this step may lead to people abusing your redeem URL to obtain digital goods without paying.

As part of crediting the account, you should record the purchase_id field in your database, and reject any attempts to redeem purchase_ids that have already been used. Generally you'll only want to grant access to the product if someone hasn't already redeemed it.

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

1. Attempt to record purchase_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've created on the itch.io dashboard you can use the [itch.io JavaScript API]($url_for{"docs", { splat = "api/javascript" }}) to pull information about your project. Using Itch.getGameData() you can retrieve a game object including products 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.