API docs by Redocly

IsThereAnyDeal API (2.9.0)

Download OpenAPI specification:

General API contact: api@isthereanydeal.com Terms of Service

Changelog

IsThereAnyDeal API provides programmatic access to features found at IsThereAnyDeal.

Terms of Service

API is provided in good faith. We trust you won't misuse the API to damage IsThereAnyDeal, its users or its reputation.

  • You MAY use this API for commercial purposes IF the resulting app is available to public. If you want to use this API privately contact us.
  • You SHOULD provide a link to IsThereAnyDeal.com or mention IsThereAnyDeal API.
  • You MUST NOT make an impression that you are affiliated with IsThereAnyDeal, unless agreed otherwise. If you are interested in making an official app, please contact us.
  • You MUST NOT change provided data in any way. This means that you can't remove affiliate tags from the URLs, change prices and so on. You MAY use only part of data provided and enrich them from your own sources.
  • You MUST NOT make an app that could be considered a competition to IsThereAnyDeal or IsThereAnyDeal projects.
  • You MUST NOT use this API to directly or indirectly help the competition of IsThereAnyDeal.

All data are provided as-is. We reserve the right to deny you access to the API at any point without notice. If you are not sure about any of the points, please contact us.

Access

Most of the endpoints will be restricted by either API key or OAuth. In order to get neccessary keys, you have to register your app. Upon registration, api keys and OAuth credentials will be generated for you.

For endpoints protected with api key, you can either add key as the query parameter key, or as ITAD-API-Key header˙. Refer to endpoint's Authorizations section.

For some endpoints you might need explicit approval for use. In such cases, contact us.

OAuth

We support authorization code flow with PKCE extension.

You can find PKCE step-through tutorial at OAuth 2.0 PKCE Flow

Do not set hard limits for token lengths. Server will return access token as JWT of variable length. To authorize your endpoint access use Authorization header.

At the moment implicit flow is also enabled, but its usage is discouraged and support may be removed in the future

Rate Limiting

Access to API is rate limited. We implement a window-based throttling. By default, if your account has verified email, you can make 1000 requests in a 5 minute window. You will see your current limits and usage in the app setup page.

We are about to lower the limits for accounts without verified email, but for a transitional period the limits are kept the same. Even though for now the limits are the same, you will still get a warning in the app setup that you can increase your limits by verifying your email.

The limits are meant to give you some leeway and allow you to handle short bursts of higher activity. You should not be constantly maxing out your usage, implement proper caching.

If you get rate-limited, you will get a 429 Too Many Requests response with a Retry-After header.

If you need higher limits, reach out to us with your use case.

Limits may change in the future. Attempts to work around the limits will cause ban. Further limits and restrictions may be added if we detect misuse.

Unstable and Internal Endpoints

Some endpoints are marked as unstable or internal. Unstable endpoints are publicly available, but the API may not be completely finalized yet - either the way the endpoint is called or the response may change at any time.

Internal APIs are available only for our own services. They are documented here for the sake of completeness.

Unofficial SDKs

Source

You can find source files for this documentation over at GitHub. Feel free to help us improve it.

Webhooks

Webhooks provide a simpler wait to get data from IsThereAnyDeal, if you don't required full API access.

User can register a webhook in their settings and choose which events they wish to listen to. Once the event is triggered on IsThereAnyDeal, a request will be sent to registered webhook.

Each request will include ITAD-Hook-ID header with a unique ID of a registered webhook and ITAD-Event-ID headers which identify the event.

Ping event Webhook

Event you can use to test if the webhook is set up correctly. Can be triggered manually from settings.

header Parameters
User-Agent
required
string
Value: "ITAD-Webhooks/1.0 (+https://isthereanydeal.com)"
Content-Type
required
string
Value: "application/json"
ITAD-Hook-ID
required
string <uuid>

ID of the Webhook

ITAD-Event
required
string

Event that generated the request

Value: "ping"
Request Body schema: application/json
string

Ping even will always send "pong" string in a body

Responses

Request samples

Content type
application/json
"pong"

Waitlist notification event Webhook

This event is trigger on new Waitlist notifications

Event's payload is a list of games and their deals that passed user's notification settings, similar to the Waitlist email notification you may receive.

header Parameters
User-Agent
required
string
Value: "ITAD-Webhooks/1.0 (+https://isthereanydeal.com)"
Content-Type
required
string
Value: "application/json"
ITAD-Hook-ID
required
string <uuid>

ID of the Webhook

ITAD-Event
required
string

Event that generated the request

Value: "notification-waitlist"
Request Body schema: application/json
Array
id
required
string <uuid>
slug
required
string
title
required
string
required
Game Type (string) or Game Type (null) (obj.game-type)
mature
required
boolean
required
Price (object) or Price (null) (obj.price-nullable)
required
Price (object) or Price (null) (obj.price-nullable)
required
Array of objects (Waitlist Notification Deal)

Responses

Request samples

Content type
application/json

Payload

[
  • {
    }
]

Add webhook

Register a webhook for the user. All webhooks should implicitly support ping event. You don't have to specify ping event in the list of supported ones, it will be added automatically. Upon successful registration, the response will include webhook's ID that can be used to remove the webhook.

Authorizations:
OAuth2
Request Body schema: application/json
url
required
string <uri>
events
required
Array of strings non-empty
Items Value: "notification-waitlist"

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Remove webhook

Remove previously registered webhook

Authorizations:
OAuth2
Request Body schema: application/json
id
required
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Response samples

Content type
application/json
{
  • "status_code": 0,
  • "reason_phrase": "string"
}

Lookup

Endpoints for looking up things on IsThereAnyDeal.

Endpoints in /lookup/ namespace will follow this URL structure: /lookup/{lookup-what}/{by-what}/

Endpoints from other namespaces that are related to lookup in any way may also be included in this category.

Lookup ITAD game IDs by title

Lookup IsThereAnyDeal's game IDs by title This is not a full fledged search. Some title preprocessing will happen, but the lookup will only return IDs for titles, that match precisely. Typos or variations in title may not give you expected result.

Authorizations:
NoneApiKeyParamAuthApiKeyHeaderAuth
Request Body schema: application/json

List of titles

Array (non-empty)
string

Responses

Request samples

Content type
application/json
[
  • "Baldurs Gate 3",
  • "Half-Life 2",
  • "Unknown game"
]

Response samples

Content type
application/json
{
  • "Baldurs Gate 3": "018d9584-24d6-7010-b82b-df1f0b154cc7",
  • "Half-Life 2": "018d937f-012f-73b8-ab2c-898516969e6a",
  • "Unknown game": null
}

Lookup ITAD game IDs by IDs on shop

Lookup IsThereAnyDeal's game IDs by shop's game IDs

Authorizations:
NoneApiKeyParamAuthApiKeyHeaderAuth
path Parameters
shopId
required
number
Request Body schema: application/json

List of shop's game IDs

Array (non-empty)
string

Responses

Request samples

Content type
application/json
[
  • "app/220"
]

Response samples

Content type
application/json
{
  • "bundle/27508": "018d95bc-fe96-73e6-a9f7-10afc28c0c03",
  • "bundle/28796": "018d937f-6671-7056-b419-aac8a69a625e",
  • "sub/467072": "018d937f-42c6-70a5-a29b-9d8c2e0f7b84",
  • "sub/752476": "018d937f-6128-7151-8d2e-b4a9ad2e1ce8",
  • "sub/137730": "018d937f-6ee4-73f5-858c-2fde3407462f",
  • "app/137730": null,
  • "bundle/33608": "018d937f-7596-706f-b75d-834d76172237"
}

Lookup game IDs on shop by ITAD game IDs

Lookup shop's game IDs by IsThereAnyDeal game IDs

Authorizations:
NoneApiKeyParamAuthApiKeyHeaderAuth
path Parameters
shopId
required
number
Request Body schema: application/json

List of game IDs

Array (non-empty)
string <uuid>

Responses

Request samples

Content type
application/json
[
  • "497f6eca-6276-4993-bfeb-53cbbbba6f08"
]

Response samples

Content type
application/json
{
  • "018d95bc-fe96-73e6-a9f7-10afc28c0c03": [
    ],
  • "018d937f-6671-7056-b419-aac8a69a625e": [
    ],
  • "018d937f-42c6-70a5-a29b-9d8c2e0f7b84": [
    ],
  • "018d937f-6128-7151-8d2e-b4a9ad2e1ce8": [
    ]
}

Search

Search for games by title

Authorizations:
ApiKeyParamAuthApiKeyHeaderAuth
query Parameters
title
required
string

Find games by name

results
number [ 1 .. 100 ]
Default: 20

Maximum number of results to return

Responses

Response samples

Content type
application/json

Europa Universalis IV search

[]

Lookup Game

Lookup game based on title or Steam appid

Authorizations:
ApiKeyParamAuthApiKeyHeaderAuth
query Parameters
title
string

Find game by it's name

appid
number

Find game by Steam appid

Responses

Response samples

Content type
application/json
Example

Game

Search

Search for games by title

Authorizations:
ApiKeyParamAuthApiKeyHeaderAuth
query Parameters
title
required
string

Find games by name

results
number [ 1 .. 100 ]
Default: 20

Maximum number of results to return

Responses

Response samples

Content type
application/json

Europa Universalis IV search

[]

Lookup Game

Lookup game based on title or Steam appid

Authorizations:
ApiKeyParamAuthApiKeyHeaderAuth
query Parameters
title
string

Find game by it's name

appid
number

Find game by Steam appid

Responses

Response samples

Content type
application/json
Example

Game Info

Get basic game information

Authorizations:
ApiKeyParamAuthApiKeyHeaderAuth
query Parameters
id
required
string <uuid>

Game ID

Responses

Response samples

Content type
application/json

Europa Universalis IV info

{}

Prices

Prices

Get games' prices

Authorizations:
ApiKeyParamAuthApiKeyHeaderAuth
query Parameters
country
string = 2 characters
Default: "US"

Two letter country code (ISO 3166-1 alpha-2)

deals
boolean

Only load deals, omit prices that have no price cut

vouchers
boolean

Allow vouchers in prices

capacity
integer >= 0

How many prices to load per each game, 0 or omit for no limit

shops
Array of integers
Example: shops=65,35

List of shop IDs for which you want to load prices

Request Body schema: application/json

List of Game IDs for which to load prices

Array ([ 1 .. 200 ] items)
string <uuid>

Responses

Request samples

Content type
application/json
[
  • "01849783-6a26-7147-ab32-71804ca47e8e",
  • "01849782-1017-7389-8de4-c97c587fd7e3"
]

Response samples

Content type
application/json

Successful response

[
  • {
    }
]

Price Overview

Get basic price overview for selected games.

For each game current best price will be loaded (optionally, only from selected shops), historical low price (among all covered shops).

Furthermore, result will also contain list of currently active bundles, which contain at least one of the queried games.

Authorizations:
ApiKeyParamAuthApiKeyHeaderAuth
query Parameters
country
string = 2 characters
Default: "US"

Two letter country code (ISO 3166-1 alpha-2)

shops
Array of integers
Example: shops=65,35

List of shop IDs

vouchers
boolean
Default: true

Allow vouchers in prices

Request Body schema: application/json

List of Game IDs

Array ([ 1 .. 200 ] items)
string <uuid>

Responses

Request samples

Content type
application/json
[
  • "01849783-6a26-7147-ab32-71804ca47e8e",
  • "01849782-1017-7389-8de4-c97c587fd7e3"
]

Response samples

Content type
application/json

Successful response

{}

History

History Low

Get historically lowest prices

Authorizations:
ApiKeyParamAuthApiKeyHeaderAuth
query Parameters
country
string = 2 characters
Default: "US"

Two letter country code (ISO 3166-1 alpha-2)

Request Body schema: application/json

List of Game IDs for which to load historical lows

Array ([ 1 .. 200 ] items)
string <uuid>

Responses

Request samples

Content type
application/json
[
  • "01849783-6a26-7147-ab32-71804ca47e8e",
  • "01849782-1017-7389-8de4-c97c587fd7e3"
]

Response samples

Content type
application/json

Successful response

[
  • {
    },
  • {
    }
]

Store Low

Get historically lowest prices for individual stores

Authorizations:
ApiKeyParamAuthApiKeyHeaderAuth
query Parameters
country
string = 2 characters
Default: "US"

Two letter country code (ISO 3166-1 alpha-2)

shops
Array of integers
Example: shops=65,35

List of shop IDs

Request Body schema: application/json

List of Game IDs for which to load store lows

Array ([ 1 .. 200 ] items)
string <uuid>

Responses

Request samples

Content type
application/json
[
  • "01849783-6a26-7147-ab32-71804ca47e8e",
  • "01849782-1017-7389-8de4-c97c587fd7e3"
]

Response samples

Content type
application/json

Successful response

[
  • {
    },
  • {
    }
]

History log

Get log of historical prices

Authorizations:
ApiKeyParamAuthApiKeyHeaderAuth
query Parameters
id
required
string <uuid>

Game ID

country
string = 2 characters
Default: "US"

Two letter country code (ISO 3166-1 alpha-2)

shops
Array of integers
Example: shops=65,35

List of shop IDs

since
string <date-time>

Load only price changes after this date.
By default, only last 3 months are loaded

Responses

Response samples

Content type
application/json

Successful response

[
  • {
    },
  • {
    }
]

Bundles

Bundle List

Get bundles

Authorizations:
ApiKeyParamAuthApiKeyHeaderAuth
query Parameters
country
string = 2 characters
Default: "US"

Two letter country code (ISO 3166-1 alpha-2)

offset
number >= 0
Default: 0
limit
number [ 1 .. 50 ]
Default: 20
mature
boolean
Default: false

Include bundles marked as mature

expired
boolean
Default: false

Include expired bundles

sort
string
Default: "-publish"

Sort value, same as on website

Responses

Response samples

Content type
application/json
[]

Bundles with Game

Get all bundles which contain the game

Authorizations:
ApiKeyParamAuthApiKeyHeaderAuth
query Parameters
id
required
string <uuid>

Game ID

country
string = 2 characters
Default: "US"

Two letter country code (ISO 3166-1 alpha-2)

expired
boolean

Include expired bundles

Responses

Response samples

Content type
application/json

Successful response

[]

Deals List

Deals List

Get current deals. Follows the same rules as deals list displayed on the website, which means that you will not get one game more than once in the list.

For each game, the best price is displayed, ignoring stores that currently don't have game on sale, even if they currently have a better price. If you want to included non-sale prices, use nondeals parameter.

You can define parameters either in a query part of a URL, or you can sent them in a request body. Since the specification for GET requests with body is unclear, we also provide more standard POST endpoint as a fallback.

You can authorize with either api key, or OAuth. If you use OAuth, the user data filters will work, e.g. in Waitlist filter.

Authorizations:
ApiKeyParamAuthApiKeyHeaderAuthOAuth2
query Parameters
country
string = 2 characters
Default: "US"

Two letter country code (ISO 3166-1 alpha-2)

offset
integer >= 0
Default: 0

Deals list offset

limit
integer [ 1 .. 200 ]
Default: 20

How many deals to return

sort
string
Examples:
  • sort=-cut - Highest cut
  • sort=price - Lowest price

Sorting values, same as in deals list on the website

nondeals
boolean
Default: false

Load non-sale prices

mature
boolean
Default: false

Load deals for mature prices

shops
Array of numbers
Examples:
  • shops=61,35 - Only Steam (61) and GOG (35)

List of shop IDs separated by comma

filter
string
Examples:
  • filter=N4IgxgrgLiBcoFsCWA7OBWADAGhAghgB5wCMmmAvhUA= - At least 50% off, base64 lz string
  • filter={"cut":{"min":50,"max":null}} - At least 50% off, json

There are two ways how you can supply filters.

  • A base64 encoded lz compressed filter json - this is what ITAD uses, you can copy and paste filters from the URL
  • Filter JSON (see request body for specification). Examples are omitting URL encoding for clarity, but make sure to URL encode these.
Request Body schema: application/json

You can use either request body or query parameters, but not both at the same time. If you use request body, you must include Content-Type: application/json header in your request.

country
string = 2 characters
Default: "US"

Two letter country code (ISO 3166-1 alpha-2)

offset
integer >= 0
Default: 0

Deals list offset

limit
integer [ 1 .. 200 ]
Default: 20

How many deals to return

sort
string

Sorting values, same as in deals list on the website

nondeals
boolean
Default: false

Load non-sale prices

mature
boolean
Default: false

Load games marked as mature

shops
Array of numbers

List of shop IDs

object

Deal Filters

Responses

Request samples

Content type
application/json
{
  • "country": "US",
  • "offset": 0,
  • "limit": 20,
  • "sort": "string",
  • "nondeals": false,
  • "mature": false,
  • "shops": [
    ],
  • "filter": {
    }
}

Response samples

Content type
application/json
{}

Deals List

Get current deals. Fallback method if you want to use request body to provide parameters and for whatever reason you can't use GET request. See GET request documentation for more details.

This endpoint does not support query parameters.

Authorizations:
ApiKeyParamAuthApiKeyHeaderAuthOAuth2
Request Body schema: application/json
country
string = 2 characters
Default: "US"

Two letter country code (ISO 3166-1 alpha-2)

offset
integer >= 0
Default: 0

Deals list offset

limit
integer [ 1 .. 200 ]
Default: 20

How many deals to return

sort
string

Sorting values, same as in deals list on the website

nondeals
boolean
Default: false

Load non-sale prices

mature
boolean
Default: false

Load games marked as mature

shops
Array of numbers

List of shop IDs

object

Deal Filters

Responses

Request samples

Content type
application/json
{
  • "country": "US",
  • "offset": 0,
  • "limit": 20,
  • "sort": "string",
  • "nondeals": false,
  • "mature": false,
  • "shops": [
    ],
  • "filter": {
    }
}

Response samples

Content type
application/json
{}

Subscriptions

Game Subscriptions

Get list of subscriptions the game is listed in.

Authorizations:
ApiKeyParamAuthApiKeyHeaderAuth
query Parameters
country
string = 2 characters
Default: "US"

Two letter country code (ISO 3166-1 alpha-2)

Request Body schema: application/json

List of Game IDs

Array ([ 1 .. 200 ] items)
string <uuid>

Responses

Request samples

Content type
application/json
[
  • "01849783-6a26-7147-ab32-71804ca47e8e",
  • "01849782-1017-7389-8de4-c97c587fd7e3"
]

Response samples

Content type
application/json

Successful response

[
  • {
    },
  • {
    }
]

Games

Games in Waitlist

Get games in user's Waitlist

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json

Successful response

[]

Add to Waitlist

Add games to user's Waitlist

Authorizations:
OAuth2
Request Body schema: application/json

List of Game IDs

Array (non-empty)
string <uuid>

Responses

Request samples

Content type
application/json
[
  • "01849783-6a26-7147-ab32-71804ca47e8e",
  • "01849782-1017-7389-8de4-c97c587fd7e3"
]

Response samples

Content type
application/json
{
  • "status_code": 0,
  • "reason_phrase": "string"
}

Delete from Waitlist

Delete games from user's Waitlist

Authorizations:
OAuth2
Request Body schema: application/json

List of Game IDs

Array (non-empty)
string <uuid>

Responses

Request samples

Content type
application/json
[
  • "01849783-6a26-7147-ab32-71804ca47e8e",
  • "01849782-1017-7389-8de4-c97c587fd7e3"
]

Response samples

Content type
application/json
{
  • "status_code": 0,
  • "reason_phrase": "string"
}

Stats

Waitlist Stats

Get Waitlist statistics for a game

Note: stats do not take into consideration users' regions. If they have set their price limit to be a historical low, stats will be computed for all users as if they were in the region you specify

Authorizations:
ApiKeyParamAuthApiKeyHeaderAuth
query Parameters
id
required
string <uuid>

Game ID

country
string = 2 characters
Default: "US"

Two letter country code (ISO 3166-1 alpha-2)

bucket_price
integer >= 0
Default: 5

Price bucket size

bucket_cut
integer >= 0
Default: 5

Cut bucket size

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "price": {
    },
  • "cut": {
    }
}

Most Waitlisted

Get list of most Waitlisted games

Authorizations:
ApiKeyParamAuthApiKeyHeaderAuth
query Parameters
offset
integer >= 0
Default: 0
limit
integer [ 1 .. 500 ]
Default: 20

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Notifications

Waitlist notification event Webhook

This event is trigger on new Waitlist notifications

Event's payload is a list of games and their deals that passed user's notification settings, similar to the Waitlist email notification you may receive.

header Parameters
User-Agent
required
string
Value: "ITAD-Webhooks/1.0 (+https://isthereanydeal.com)"
Content-Type
required
string
Value: "application/json"
ITAD-Hook-ID
required
string <uuid>

ID of the Webhook

ITAD-Event
required
string

Event that generated the request

Value: "notification-waitlist"
Request Body schema: application/json
Array
id
required
string <uuid>
slug
required
string
title
required
string
required
Game Type (string) or Game Type (null) (obj.game-type)
mature
required
boolean
required
Price (object) or Price (null) (obj.price-nullable)
required
Price (object) or Price (null) (obj.price-nullable)
required
Array of objects (Waitlist Notification Deal)

Responses

Request samples

Content type
application/json

Payload

[
  • {
    }
]

Waitlist notification detail

Get details of Waitlist notification

Authorizations:
OAuth2
query Parameters
id
required
string <uuid>

Notification ID

Responses

Response samples

Content type
application/json

Successful response

{
  • "id": "01921bab-b582-73bc-8473-9f125837107b",
  • "timestamp": "2024-09-24T02:43:04+02:00",
  • "read": "2024-10-06T16:06:47+02:00",
  • "games": [
    ]
}

Games

Basic Collection operations when you only need to track games, without additional details.

Games in Collection

Get games in user's Collection

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json

Successful response

[]

Add to Collection

Add games to user's Collection

Authorizations:
OAuth2
Request Body schema: application/json

List of Game IDs

Array (non-empty)
string <uuid>

Responses

Request samples

Content type
application/json
[
  • "01849783-6a26-7147-ab32-71804ca47e8e",
  • "01849782-1017-7389-8de4-c97c587fd7e3"
]

Response samples

Content type
application/json
{
  • "status_code": 0,
  • "reason_phrase": "string"
}

Delete from Collection

Delete games from user's Collection

Authorizations:
OAuth2
Request Body schema: application/json

List of Game IDs

Array (non-empty)
string <uuid>

Responses

Request samples

Content type
application/json
[
  • "01849783-6a26-7147-ab32-71804ca47e8e",
  • "01849782-1017-7389-8de4-c97c587fd7e3"
]

Response samples

Content type
application/json
{
  • "status_code": 0,
  • "reason_phrase": "string"
}

Copies

Operations on Collection copies. These allow more detailed tracking of owned games.

List Copies

Get all copies user has in their Collection. Copies are returned as a simple list.

It is not necessary to have copy for each game in Collection, so you should not rely on this endpoint if you need to know about all games in user's Collection.

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json

Successful response

[
  • {
    },
  • {
    }
]

Add Copies

Add new copies. If the game is not already in a Collection, it will be added. Similarly, new tags will also be created.

Same copies may exist multiple times for a single game, ITAD does not check for duplicates.

This operation is atomic, either all copies are added or none.

Authorizations:
OAuth2
Request Body schema: application/json

Copies to add

Array
gameId
required
string <uuid>
redeemed
required
boolean
number or null
object or null
string or null
Array of strings or null

Responses

Request samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
{
  • "status_code": 400,
  • "reason_phrase": "Bad Request",
  • "details": [
    ]
}

Update Copies

Update one or more copies.

You can issue partial updates on copy, only properties that are included for a copy will be updated.

This operation is atomic, either all copies are updated or none.

Authorizations:
OAuth2
Request Body schema: application/json
Array
id
required
number
redeemed
boolean
number or null
object or null
string or null
Array of strings or null

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "status_code": 400,
  • "reason_phrase": "Bad Request",
  • "details": [
    ]
}

Delete Copies

Delete Collection copies.

Copies that do not exist or don't belong to user will be silently ignored.

Operation is atomic. Either all copies are deleted or none.

Authorizations:
OAuth2
Request Body schema: application/json

List of copy IDs

Array
integer

Responses

Request samples

Content type
application/json
[
  • 123,
  • 124,
  • 125
]

Response samples

Content type
application/json
{
  • "status_code": 0,
  • "reason_phrase": "string"
}

Categories

Collection category endpoints. Category and group may be used interchangably. Default category has ID 0.

Get all Categories

Get all Collection categories, both the user created ones and default one. Default category has id 0 and will always be listed last. User set order of categories is respected in the response.

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json

Successful response

[
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Create new Category

Create Collection category. Categories with same name may exist.

Successful response will return the created category.

Authorizations:
OAuth2
Request Body schema: application/json

Category to create

title
required
string
public
required
boolean

Responses

Request samples

Content type
application/json
{
  • "title": "New Collection Category",
  • "public": true
}

Response samples

Content type
application/json
{
  • "id": 5669,
  • "title": "New Collection Category",
  • "public": true
}

Update Categories

Update one or more categories.

For each category that you are going to update, only id is required. Fields that you do not want to update may be set to null or omitted fully. Categories that do not exist or user does not own will be ignored.

Default category (id: 0) may have only public property updated. Other properties will be ignored.

This operation is atomic, either all categories update or none. Successful response is the full category list, including categories that were not updated.

Authorizations:
OAuth2
Request Body schema: application/json
Array
id
required
integer
string or null
boolean or null
integer or null

Responses

Request samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json

Successful response

[
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Delete Categories

Delete Collection categories.

Default category or categories that do not exist or user does not own will be silently ignored.

Authorizations:
OAuth2
Request Body schema: application/json

List of category IDs

Array
integer

Responses

Request samples

Content type
application/json
[
  • 123,
  • 124,
  • 125
]

Response samples

Content type
application/json
{
  • "status_code": 0,
  • "reason_phrase": "string"
}

Stats

Most Collected

Get list of most Collected games

Authorizations:
ApiKeyParamAuthApiKeyHeaderAuth
query Parameters
offset
integer >= 0
Default: 0
limit
integer [ 1 .. 500 ]
Default: 20

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Stats

Waitlist Stats

Get Waitlist statistics for a game

Note: stats do not take into consideration users' regions. If they have set their price limit to be a historical low, stats will be computed for all users as if they were in the region you specify

Authorizations:
ApiKeyParamAuthApiKeyHeaderAuth
query Parameters
id
required
string <uuid>

Game ID

country
string = 2 characters
Default: "US"

Two letter country code (ISO 3166-1 alpha-2)

bucket_price
integer >= 0
Default: 5

Price bucket size

bucket_cut
integer >= 0
Default: 5

Cut bucket size

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "price": {
    },
  • "cut": {
    }
}

Most Waitlisted

Get list of most Waitlisted games

Authorizations:
ApiKeyParamAuthApiKeyHeaderAuth
query Parameters
offset
integer >= 0
Default: 0
limit
integer [ 1 .. 500 ]
Default: 20

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Most Collected

Get list of most Collected games

Authorizations:
ApiKeyParamAuthApiKeyHeaderAuth
query Parameters
offset
integer >= 0
Default: 0
limit
integer [ 1 .. 500 ]
Default: 20

Responses

Response samples

Content type
application/json
[
  • {
    }
]

User

User Info

Get user info, currently just a username

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
{
  • "username": "string"
}

Notes

Endpoints for managing notes, that user can create for individual games.

Get notes

Get user's game notes

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add or edit notes

Add or edit game notes. This operation is atomic and idempotent.

Authorizations:
OAuth2
Request Body schema: application/json
required

List of notes

Array
gid
required
string <uuid>

Game ID

note
required
string

Non-empty string

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "status_code": 0,
  • "reason_phrase": "string"
}

Delete notes

Delete game notes. This operation is atomic.

Authorizations:
OAuth2
Request Body schema: application/json
required

List of game IDs

Array
string <uuid>

Responses

Request samples

Content type
application/json
[
  • "497f6eca-6276-4993-bfeb-53cbbbba6f08"
]

Response samples

Content type
application/json
{
  • "status_code": 0,
  • "reason_phrase": "string"
}

Profiles

You can create a link between your app's users' accounts and ITAD, and use that link to sync games into Waitlist and Collection in the similar fashion as natively supported profiles on IsThereAnyDeal.

Sync

Sync endpoints provide easier way to add or remove games from Waitlist and Collection.

Sync via API works in the same way as natively supported sync of remote profiles, but instead of ITAD pulling data, you will have to push data. Behavior of sync'd games is the same as for natively supported profiles.

It is useful when you can create a list of all games for user, and don't want to handle game identification, deduplication, additions and removals via regular API endpoints.

Sync Waitlist

Sync Waitlist with IsThereAnyDeal. User can set category for your profile and default notification rules in their settings, same as with natively supported profiles.

Authorizations:
OAuth2
header Parameters
ITAD-Profile
required
string

Profile token

Request Body schema: application/json
required

Games to sync with IsThereAnyDeal

Array
shop
required
number

Shop ID

id
required
string

ID can be any string that will identify the game. It should be stable and not change in the future.

ID can also used to identify the game, if you use same IDs that we use for tracking shops. If a game is not identified with shop and id, we will use title.

For Steam we use full ids, i.e. app/{id}, sub/{id} or bundle/{id}.

title
required
string

Title of the game.

Responses

Request samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
{
  • "total": 0,
  • "added": 0,
  • "removed": 0
}

Sync Collection

Sync Collection with IsThereAnyDeal. User can set category for your profile in their settings, same as with natively supported profiles.

Games are synced as redeemed copies. If there already is a redemeed copy with the same shop in user's Collection, new copy will not be added.

Authorizations:
OAuth2
header Parameters
ITAD-Profile
required
string

Profile token

Request Body schema: application/json
required

Games to sync with IsThereAnyDeal

Array
shop
required
number

Shop ID

id
required
string

ID can be any string that will identify the game. It should be stable and not change in the future.

ID can also used to identify the game, if you use same IDs that we use for tracking shops. If a game is not identified with shop and id, we will use title.

For Steam we use full ids, i.e. app/{id}, sub/{id} or bundle/{id}.

title
required
string

Title of the game.

number or null

Play time in minutes

string or null

Responses

Request samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
{
  • "total": 0,
  • "added": 0,
  • "removed": 0
}

Notifications

List notifications

Get user's notifications

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json

Successful response

[
  • {
    },
  • {
    },
  • {
    }
]

Waitlist notification detail

Get details of Waitlist notification

Authorizations:
OAuth2
query Parameters
id
required
string <uuid>

Notification ID

Responses

Response samples

Content type
application/json

Successful response

{
  • "id": "01921bab-b582-73bc-8473-9f125837107b",
  • "timestamp": "2024-09-24T02:43:04+02:00",
  • "read": "2024-10-06T16:06:47+02:00",
  • "games": [
    ]
}

Mark notification read

Mark single notification as read

Authorizations:
OAuth2
query Parameters
id
required
string <uuid>

Notification ID

Responses

Response samples

Content type
application/json
{
  • "status_code": 0,
  • "reason_phrase": "string"
}

Mark all notifications read

Mark all notifications as read

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
{
  • "status_code": 0,
  • "reason_phrase": "string"
}

Shops

Active shops

Return active shops for specified country, with basic information about number of games and shop's last update.

query Parameters
country
string = 2 characters
Default: "US"

Two letter country code (ISO 3166-1 alpha-2)

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

Shop Map

Get list of all shops that were ever covered by IsThereAnyDeal, including inactive shops. Only id and title of the shop is included in the response, since the shop details may differ by region.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

Unstable

Endpoints that are not yet stable. They may be in development, experimental, or we are not sure about their current definition.

Game List

We are looking for a feedback for this endpoint. Please let us know whether you find this useful or not, or suggest changes. If we won't hear any feedback, we will assume this endpoint is useless and will be removed in the future.

Get list of currently recognized active games.

One of the biggest hurdles to communicate with the ITAD API is to get game IDs that are needed by our endpoints. Usually, you will get these IDs by doing a lookup or search when you are trying to get to specific game, or they will be a part of the response of other endpoints, e.g. Deals list.

With this endpoint we are experimenting with returning a list of all currently active games, which could be used to bootstrap your application.

However, this is not a load once and forget solution. Each game on IsThereAnyDeal has associated products, which are basically entries from shops that we cover. Think about "game" on ITAD as a container, that includes products and has some other associated information or metadata.

Once a game loses its products, it will become inactive. This can happen for example if the game is renamed. In such cases, new game entry will be created, and products will be reassigned to the new game. This can happen automatically by a system, or manually.

The automatic product to game assignment is not perfect, and sometimes needs to be fixed manually. This may happen because of various sitations, for example:

  • developer changes the game's name, but some of the shops don't reflect the change and keep using the old name
  • shop lists a game in a slightly different way that our system can't manage automatically
  • remaster of the game is released with the same name as the old entry
  • a different game with the same name exists and products needs to be split to correct entries

To make things even more complicated, the shop may change their product ID, or may use different product IDs for different regions, based on their internal structure. To get a better understanding of this, you can check any game on ITAD for its products. As an example, here's Red Dead Redemption 2.

The game IDs are ensured to be ascending. You can check for new entries by using your last known game ID to get only new entries. However, there may be a case, where an old inactive game becomes active again

  • it stopped being sold, but has since returned and is being sold again.

We are looking for a feedback about this endpoint. You can currently use it to bootstrap your application, but it should not be relied upon for 100% coverage all the time. At the very least, if you end up relying on this map and omit doing lookups, you should check for new entries, and periodically (e.g. once a week) recheck the entire list.

There is a possiblity to return all known game entries, including the inactive ones, but this would include a lot of dead entries that will never be used again, like when a shop listed a game with typo and such.

The maximum number of games you will get is 10000. Use last parameter to get more entries.

This endpoint is supposed to be used in concert with Game Changes endpoint.

Authorizations:
ApiKeyParamAuthApiKeyHeaderAuth
query Parameters
last
string <uuid>

Last known game ID, use to get newer entries

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Game Changes

We are looking for a feedback for this endpoint. Please let us know whether you find this useful or not, or suggest changes. If we won't hear any feedback, we will assume this endpoint is useless and will be removed in the future.

Get list of product assignment changes.

As explained in the Games List endpoint, game on IsThereAnyDeal is a container that has products assigned, and products may move between game entries.

This endpoint will return these products changes. The intention is that if you use Games List endpoint to get the game map, you will also use this endpoint in concert, and recheck games that had their products reassigned.

Number of entries returned is limited to 1000. You can use last parameter to get newer entries since your last known id, or since parameter to get newer entries since supplied unix timestamp. If none are used, you will get the newest 1000 entries.

This endpoint is supposed to be used in concert with Game List endpoint.

Authorizations:
ApiKeyParamAuthApiKeyHeaderAuth
query Parameters
last
number

Last known change ID, use to get newer entries

since
integer

Unix timestamp, to return newer entries than supplied timestamp

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Internal

Endpoints available for our own services. They are documented here for the sake of completeness.

Early Access Games

Returns list of Steam appids, which are currently considered to be early in early access

Authorizations:
ApiKeyParamAuthApiKeyHeaderAuth

Responses

Response samples

Content type
application/json
[
  • 0
]

Number of Players Statistics

Authorizations:
ApiKeyParamAuthApiKeyHeaderAuth
query Parameters
appid
required
number

Responses

Response samples

Content type
application/json
{
  • "current": 0,
  • "day": 0,
  • "peak": 0
}

HowLongToBeat Overview

Authorizations:
ApiKeyParamAuthApiKeyHeaderAuth
query Parameters
appid
required
number

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "main": { },
  • "extra": { },
  • "complete": { }
}

WSGF Overview

Authorizations:
ApiKeyParamAuthApiKeyHeaderAuth
query Parameters
appid
required
number

Responses

Response samples

Content type
application/json
{
  • "url": "string",
  • "wide": "A",
  • "ultrawide": "A",
  • "multi_monitor": "A",
  • "4k": "A"
}

Reviews Score

Returns Metacritic user reviews overview and OpenCritic overview for a given game

Authorizations:
ApiKeyParamAuthApiKeyHeaderAuth
query Parameters
appid
required
number

Responses

Response samples

Content type
application/json
{}

Conversion Rates

Authorizations:
ApiKeyParamAuthApiKeyHeaderAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Excluded from Family Sharing

Authorizations:
ApiKeyParamAuthApiKeyHeaderAuth
Request Body schema: application/json
required

List of appids

Array
integer

Responses

Request samples

Content type
application/json
[
  • 0
]

Response samples

Content type
application/json
{
  • "appid1": true,
  • "appid2": true
}

Current stream of Twitch channel

Authorizations:
ApiKeyParamAuthApiKeyHeaderAuth
query Parameters
channel
required
string

Responses

Response samples

Content type
application/json
Example
{
  • "user_name": "string",
  • "title": "string",
  • "thumbnail_url": "string",
  • "viewer_count": 0,
  • "game": "string"
}