Get Available Shop Items

Warning

Testing Phase: This endpoint is currently in testing and not ready for production. API structure and responses may change.

This method retrieves shop items available for a specific player, filtered by player context (VIP level, country, balance, date/time) and game availability. Use gateway.[msdomain]

This endpoint is used to display the shop UI to players, showing only items they are eligible to redeem.

Request (GET)

`/gateway/coins/shop/available/{version}/{brand_id}`

Parameters:

Name	In	Type	Required	Description
version	path	string	true	The API version to use.
brand_id	path	int	true	Brand identifier
x-auth-token	header	string	false	Player authentication token (optional - if not provided, returns all active items)

Note:

If x-auth-token is provided, the player_id is extracted and added as a query parameter (?player_id=123) when forwarding to the marketing service
If no token is provided, the endpoint returns all active shop items without eligibility filtering (useful for anonymous/preview mode)
Player IP address is automatically extracted from the request for geo-location filtering

Response

Status 200 - With Authentication

{
  "status": "success",
  "data": {
    "items": [
      {
        "item": {
          "id": "507f1f77bcf86cd799439011",
          "brand_id": 1001,
          "name": "cash_bonus_10_usd",
          "display_name": "10 USD Cash Bonus",
          "description": "Get $10 cash bonus added to your account",
          "status": "active",
          "segmentation_filters": [
            {
              "field": "vip_level",
              "filter_type": "enum",
              "operator": "in",
              "comparison_val": [3, 4, 5]
            }
          ],
          "eligibility_filters": [
            {
              "field": "balance",
              "filter_type": "numeric",
              "operator": "greater_than_or_equals",
              "comparison_val": 50.0
            }
          ],
          "type": "CASH_BONUS",
          "data": [
            {
              "currency": "USD",
              "amount": "10.00",
              "coins_cost": "100.00"
            },
            {
              "currency": "EUR",
              "amount": "8.50",
              "coins_cost": "100.00"
            }
          ],
          "purchase_stats": {
            "past_week_count": 5,
            "lifetime_count": 127
          },
          "created_at": "2024-12-01T10:00:00Z",
          "created_by": "admin@casino.com",
          "updated_at": "2025-01-05T14:30:00Z",
          "updated_by": "admin@casino.com"
        },
        "is_eligible": true,
        "ineligible_reasons": []
      },
      {
        "item": {
          "id": "507f1f77bcf86cd799439012",
          "brand_id": 1001,
          "name": "frb_starburst_50",
          "display_name": "50 Free Rounds on Starburst",
          "description": "Get 50 free spins on Starburst slot",
          "status": "active",
          "segmentation_filters": [
            {
              "field": "country",
              "filter_type": "string",
              "operator": "in",
              "comparison_val": ["US", "CA", "GB"]
            },
            {
              "field": "day_of_week",
              "filter_type": "enum",
              "operator": "in",
              "comparison_val": [6, 7]
            }
          ],
          "eligibility_filters": [
            {
              "field": "balance",
              "filter_type": "numeric",
              "operator": "greater_than_or_equals",
              "comparison_val": 75.0
            }
          ],
          "type": "FRB",
          "data": {
            "game_id": "starburst",
            "provider_id": "netent",
            "rounds_conf": [
              {
                "rounds": 20,
                "coins_cost": "50.00",
                "duration": 30,
                "conf": [
                  {
                    "currency": "USD",
                    "wagering_multiplier": "10.00",
                    "max_winning": "100.00"
                  },
                  {
                    "currency": "EUR",
                    "wagering_multiplier": "10.00",
                    "max_winning": "85.00"
                  }
                ]
              },
              {
                "rounds": 50,
                "coins_cost": "100.00",
                "duration": 60,
                "conf": [
                  {
                    "currency": "USD",
                    "wagering_multiplier": "15.00",
                    "max_winning": "250.00"
                  }
                ]
              }
            ]
          },
          "purchase_stats": {
            "past_week_count": 12,
            "lifetime_count": 342
          },
          "created_at": "2024-11-15T10:00:00Z",
          "created_by": "admin@casino.com",
          "updated_at": "2025-01-01T12:00:00Z",
          "updated_by": "admin@casino.com"
        },
        "is_eligible": false,
        "ineligible_reasons": [
          "balance: requires 75.00, player has 50.00",
          "day_of_week: requires [6,7], today is 3"
        ]
      },
      {
        "item": {
          "id": "507f1f77bcf86cd799439013",
          "brand_id": 1001,
          "name": "tshirt_limited_edition",
          "display_name": "Limited Edition T-Shirt",
          "description": "Get an exclusive casino branded t-shirt",
          "status": "active",
          "segmentation_filters": [
            {
              "field": "vip_level",
              "filter_type": "enum",
              "operator": "in",
              "comparison_val": [5]
            }
          ],
          "eligibility_filters": [],
          "type": "PHYSICAL",
          "data": {
            "name": "Limited Edition T-Shirt",
            "description": "Casino branded t-shirt, size L",
            "coins_cost": "500.00"
          },
          "purchase_stats": {
            "past_week_count": 2,
            "lifetime_count": 45
          },
          "created_at": "2024-10-01T10:00:00Z",
          "created_by": "admin@casino.com",
          "updated_at": "2024-12-20T16:00:00Z",
          "updated_by": "admin@casino.com"
        },
        "is_eligible": true,
        "ineligible_reasons": []
      }
    ]
  },
  "message": "Successfully retrieved available shop items"
}

Status 200 - Without Authentication (Anonymous/Preview Mode)

{
  "status": "success",
  "data": {
    "items": [
      {
        "item": {
          "id": "507f1f77bcf86cd799439011",
          "brand_id": 1001,
          "name": "cash_bonus_10_usd",
          "display_name": "10 USD Cash Bonus",
          "description": "Get $10 cash bonus added to your account",
          "status": "active",
          "type": "CASH_BONUS",
          "data": [...],
          "purchase_stats": {
            "past_week_count": 5,
            "lifetime_count": 127
          }
        },
        "is_eligible": false,
        "ineligible_reasons": []
      }
    ]
  },
  "message": "Successfully retrieved available shop items"
}

Response Fields:

ShopItemAvailability Object:

Field	Type	Description
item	object	Shop item details (see ShopItem below)
is_eligible	boolean	Whether the player is eligible to redeem this item
ineligible_reasons	string[]	List of reasons why the player is not eligible (empty if eligible)

ShopItem Object:

Field	Type	Description
id	string	Shop item MongoDB ObjectID
brand_id	int	Brand identifier
name	string	Internal item name
display_name	string	User-facing display name
description	string	Item description
status	string	Item status: “active” or “inactive”
segmentation_filters	Filter[]	Player segmentation filters (VIP level, country, day of week, date)
eligibility_filters	Filter[]	Player eligibility filters (balance, etc.)
type	string	Item type: “CASH_BONUS”, “FRB”, or “PHYSICAL”
data	object	Type-specific data (see examples below)
purchase_stats	object	Purchase statistics (past_week_count, lifetime_count)
created_at	string	Creation timestamp (ISO 8601)
created_by	string	Creator email
updated_at	string	Last update timestamp (ISO 8601)
updated_by	string	Last updater email

Filter Object:

Field	Type	Description
field	string	Filter field: “vip_level”, “country”, “day_of_week”, “date”, “balance”
filter_type	string	Filter type: “numeric”, “string”, “enum”, “regex”, “date”
operator	string	Comparison operator: “in”, “equals”, “greater_than”, “less_than”, etc.
comparison_val	any	Value(s) to compare against (type depends on filter_type)

Data Types by Item Type:

CASH_BONUS:

[
  {
    "currency": "USD",
    "amount": "10.00",
    "coins_cost": "100.00"
  }
]

FRB (Free Rounds Bonus):

{
  "game_id": "starburst",
  "provider_id": "netent",
  "rounds_conf": [
    {
      "rounds": 50,
      "coins_cost": "100.00",
      "duration": 30,
      "conf": [
        {
          "currency": "USD",
          "wagering_multiplier": "15.00",
          "max_winning": "250.00"
        }
      ]
    }
  ]
}

PHYSICAL:

{
  "name": "Limited Edition T-Shirt",
  "description": "Casino branded t-shirt, size L",
  "coins_cost": "500.00"
}

Status 500

{
  "status": "error",
  "data": null,
  "message": "Failed to get available shop items"
}

Filtering Logic

The endpoint applies multiple layers of filtering:

Status Filter: Only “active” shop items are returned
Segmentation Filters (if player is authenticated):
- VIP Level: Player’s VIP level must match filter criteria
- Country: Player’s country (from IP) must match filter criteria
- Day of Week: Current day must match filter criteria (1=Monday, 7=Sunday)
- Date: Current date/time must match filter criteria
Eligibility Filters (if player is authenticated):
- Balance: Player’s coins balance must meet threshold
Game Availability (for FRB items, if player is authenticated):
- Game must be available for the player based on their token
- Filtered rounds configurations based on player’s currency

Notes

Anonymous Access: If no x-auth-token is provided, all active items are returned with is_eligible: false and empty ineligible_reasons
Player Context: Player IP, token, VIP level, balance, and country are automatically extracted for filtering
FRB Filtering: For FRB items, the data.rounds_conf array is filtered to include only configurations matching the player’s currency
Purchase Stats: Statistics show popularity (past 7 days and lifetime)
Ineligible Reasons: Clear human-readable explanations for why a player cannot redeem an item
Multi-Currency: CASH_BONUS and FRB items can have configurations for multiple currencies