> For the complete documentation index, see [llms.txt](https://docs.idosgames.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.idosgames.com/api/api-v1/marketplace.md).

# Marketplace

This documentation covers the various endpoints and actions available for the Marketplace API. The API allows for operations such as creating, updating, deleting, and buying offers on the marketplace, as well as handling user sessions and royalty calculations.

**Base URL**

```
https://api.idosgames.com/api/[titleTemplateId]/[titleId]/Client/Marketplace/  
```

## CreateOffer

**Purpose:** To create a new offer on the marketplace.

**URL:**

```
https://api.idosgames.com/api/[titleTemplateId]/[titleId]/Client/Marketplace/CreateOffer  
```

**Method:** POST

**Request Parameters (JSON body):**

* `ItemID` (string): The ID of the item.
* `VirtualCurrencyID` (string): The ID of the virtual currency.
* `Price` (string): The price of the item.

**Responses:**

* `200 OK`: Operation successful. Returns a success message.
* `400 Bad Request`: Incorrect request parameters. Possible messages: "INVALID\_INPUT\_DATA", "ITEM\_NOT\_EXISTS\_IN\_INVENTORY", "INCORRECT\_VIRTUAL\_CURRENCY\_ID", "FAILED\_TO\_SAVE\_TO\_DATABASE", etc.

**Example Usage:**

**Request:**

```javascript
fetch('https://api.idosgames.com/api/[titleTemplateId]/[titleId]/Client/Marketplace/CreateOffer', {  
    method: 'POST',  
    headers: {  
        'Content-Type': 'application/json'  
    },  
    body: JSON.stringify({  
        ItemID: 'item-id-example',  
        VirtualCurrencyID: 'currency-id-example',  
        Price: '100'  
    })  
})  
.then(response => response.json())  
.then(data => console.log(data))  
.catch(error => console.error('Error:', error));  
```

**Response:**

```json
{  
    "Message": "SUCCESS"  
}  
```

## DeleteOffer

**Purpose:** To delete an offer from the marketplace.

**URL:**

```
https://api.idosgames.com/api/[titleTemplateId]/[titleId]/Client/Marketplace/DeleteOffer  
```

**Method:** POST

**Request Parameters (JSON body):**

* `ID` (string): The ID of the offer to delete.

**Responses:**

* `200 OK`: Operation successful. Returns a success message.
* `400 Bad Request`: Incorrect request parameters. Possible messages: "INVALID\_INPUT\_DATA", "ITEM\_NOT\_EXISTS\_IN\_DB", "ITEM\_OWNED\_BY\_ANOTHER\_USER", "FAILED\_TO\_UPDATE\_ITEM\_IN\_DB", etc.

**Example Usage:**

**Request:**

```javascript
fetch('https://api.idosgames.com/api/[titleTemplateId]/[titleId]/Client/Marketplace/DeleteOffer', {  
    method: 'POST',  
    headers: {  
        'Content-Type': 'application/json'  
    },  
    body: JSON.stringify({  
        ID: 'offer-id-example'  
    })  
})  
.then(response => response.json())  
.then(data => console.log(data))  
.catch(error => console.error('Error:', error));  
```

**Response:**

```json
{  
    "Message": "SUCCESS"  
}  
```

## UpdateOffer

**Purpose:** To update an existing offer on the marketplace.

**URL:**

```
https://api.idosgames.com/api/[titleTemplateId]/[titleId]/Client/Marketplace/UpdateOffer  
```

**Method:** POST

**Request Parameters (JSON body):**

* `ID` (string): The ID of the offer to update.
* `VirtualCurrencyID` (string): The new virtual currency ID.
* `Price` (string): The new price for the item.

**Responses:**

* `200 OK`: Operation successful. Returns a success message.
* `400 Bad Request`: Incorrect request parameters. Possible messages: "INVALID\_INPUT\_DATA", "ITEM\_NOT\_EXISTS\_IN\_DB", "ITEM\_OWNED\_BY\_ANOTHER\_USER", "NOTHING\_TO\_UPDATE", "FAILED\_TO\_UPDATE\_ITEM\_IN\_DB", etc.

**Example Usage:**

**Request:**

```javascript
fetch('https://api.idosgames.com/api/[titleTemplateId]/[titleId]/Client/Marketplace/UpdateOffer', {  
    method: 'POST',  
    headers: {  
        'Content-Type': 'application/json'  
    },  
    body: JSON.stringify({  
        ID: 'offer-id-example',  
        VirtualCurrencyID: 'new-currency-id',  
        Price: '150'  
    })  
})  
.then(response => response.json())  
.then(data => console.log(data))  
.catch(error => console.error('Error:', error));  
```

**Response:**

```json
{  
    "Message": "SUCCESS"  
}  
```

## BuyOffer

**Purpose:** To buy an offer on the marketplace.

**URL:**

```
https://api.idosgames.com/api/[titleTemplateId]/[titleId]/Client/Marketplace/BuyOffer  
```

**Method:** POST

**Request Parameters (JSON body):**

* `ID` (string): The ID of the offer to buy.

**Responses:**

* `200 OK`: Successful operation. Returns a success message.
* `400 Bad Request`: Incorrect request parameters or error in the buying process. Possible messages: "INVALID\_INPUT\_DATA", "ITEM\_NOT\_EXISTS\_IN\_DB", "CANT\_BUY\_YOUR\_ITEM", "NOT\_ENOUGH\_FUNDS", "FAILED\_TO\_MODIFY\_VIRTUAL\_CURRENCY", "FAILED\_TO\_GRANT\_ITEMS", "FAILED\_TO\_UPDATE\_ITEM\_IN\_DB", etc.

**Example Usage:**

**Request:**

```javascript
fetch('https://api.idosgames.com/api/[titleTemplateId]/[titleId]/Client/Marketplace/BuyOffer', {  
    method: 'POST',  
    headers: {  
        'Content-Type': 'application/json'  
    },  
    body: JSON.stringify({  
        ID: 'offer-id-example'  
    })  
})  
.then(response => response.json())  
.then(data => console.log(data))  
.catch(error => console.error('Error:', error));  
```

**Response:**

```json
{  
    "Message": "SUCCESS"  
}  
```

***

## **GetGroupedActiveOffers**

Retrieves grouped active offers for the specified title.

**Action**: `GroupedOffers`

**Purpose**: Retrieves grouped active offers based on ItemID.

**Example Usage**

Request:

```javascript
fetch('https://api.example.com/api/1234/5678/Client/MarketplaceData/GroupedOffers', {    
    method: 'POST',    
    headers: {    
        'Content-Type': 'application/json'    
    },    
    body: JSON.stringify({    
        WebAppLink: 'https://example.com',  
        UserID: 'example-user-id',    
        ClientSessionTicket: 'valid-session-ticket',    
        EntityToken: 'example-token',    
        UsageTime: 120  
    })    
})    
.then(response => response.json())    
.then(data => console.log(data))    
.catch(error => console.error('Error:', error));  
```

Response:

```json
{  
    "Items": [  
        {"ItemID": "item1", "OfferCount": 5},  
        {"ItemID": "item2", "OfferCount": 3}  
    ]  
}  
```

## **GetActiveOffersByItemID**

Retrieves active offers for a specific item ID.

**Action**: `ActiveOffersByItemID`

**Purpose**: Retrieves active offers based on ItemID, with optional filtering and sorting.

**Example Usage**

Request:

```javascript
fetch('https://api.example.com/api/1234/5678/Client/MarketplaceData/ActiveOffersByItemID', {    
    method: 'POST',    
    headers: {    
        'Content-Type': 'application/json'    
    },    
    body: JSON.stringify({    
        ItemID: 'example-item-id',    
        VirtualCurrencyID: 'USD',  
        PriceFrom: '1.00',  
        PriceTo: '10.00',  
        SortOrder: 'Ascending',    
        OrderBy: 'Price',    
        MaxItemCount: 10  
    })    
})    
.then(response => response.json())    
.then(data => console.log(data))    
.catch(error => console.error('Error:', error));  
```

Response:

```json
{  
    "Items": [  
        {"ID": "offer1", "ItemID": "example-item-id", "SellerID": "seller1", "CurrencyID": "USD", "Price": 5.00},  
        {"ID": "offer2", "ItemID": "example-item-id", "SellerID": "seller2", "CurrencyID": "USD", "Price": 8.00}  
    ],  
    "ContinuationToken": "next-token-id"  
}  
```

## **GetPlayerHistory**

Retrieves player transaction history.

**Action**: `PlayerHistory`

**Purpose**: Retrieves the transaction history for a player based on their UserID.

**Example Usage**

Request:

```javascript
fetch('https://api.example.com/api/1234/5678/Client/MarketplaceData/PlayerHistory', {    
    method: 'POST',    
    headers: {    
        'Content-Type': 'application/json'    
    },    
    body: JSON.stringify({    
        UserID: 'example-user-id',    
        MaxItemCount: 10    
    })    
})    
.then(response => response.json())    
.then(data => console.log(data))    
.catch(error => console.error('Error:', error));  
```

Response:

```json
{  
    "Items": [  
        {"ID": "history1", "ItemID": "item1", "SellerID": "seller1", "BuyerID": "example-user-id", "CurrencyID": "USD", "Price": 10.00},  
        {"ID": "history2", "ItemID": "item2", "SellerID": "seller2", "BuyerID": "example-user-id", "CurrencyID": "USD", "Price": 15.00}  
    ],  
    "ContinuationToken": "next-token-id"  
}  
```

## **GetPlayerActiveOffers**

Retrieves active offers by a player.

**Action**: `PlayerActiveOffers`

**Purpose**: Retrieves the active offers for a player based on their UserID.

**Example Usage**

Request:

```javascript
fetch('https://api.example.com/api/1234/5678/Client/MarketplaceData/PlayerActiveOffers', {    
    method: 'POST',    
    headers: {    
        'Content-Type': 'application/json'    
    },    
    body: JSON.stringify({    
        UserID: 'example-user-id',    
        MaxItemCount: 10    
    })    
})    
.then(response => response.json())    
.then(data => console.log(data))    
.catch(error => console.error('Error:', error));  
```

Response:

```json
{  
    "Items": [  
        {"ID": "offer1", "ItemID": "item1", "SellerID": "example-user-id", "CurrencyID": "USD", "Price": 10.00},  
        {"ID": "offer2", "ItemID": "item2", "SellerID": "example-user-id", "CurrencyID": "USD", "Price": 15.00}  
    ],  
    "ContinuationToken": "next-token-id"  
}  
```