page icon

REST API Specification 0.0.2

This document provides specifications for integrating with the Game8 Store API.
By using this API, publishers can perform actions such as:
  • Checking purchase eligibility for in-game items
  • Registering purchases and granting items
  • Retrieving purchase history
  • Obtaining sales data
We actively consider feedback and feature requests from publishers. If you have any suggestions or additional requirements, please feel free to contact us.
If you already have an existing publisher API, we will adjust our implementation to align with your specifications as much as possible.

API List

API NameEndpointMethodRequiredDescription
Purchase Eligibility CheckRequiredCheck whether a user can purchase a specified item
Register PurchaseRequiredRegister a completed purchase and grant the in-game item
Get Purchase HistoryOptionalRetrieve a user's past purchase history
Get Sales DataOptionalRetrieve sales data within a specified period

1. General Specifications

ItemDescription
Host
ProtocolHTTPS
Character EncodingUTF-8

1.1. Request Specifications

Request Headers

KeyValueDescription
AuthorizationBearer Authentication Information
Content-Typeapplication/jsonContent Type

1.2. Response Specifications

Common Response Headers

KeyValue
Content-Typeapplication/json

Common Response Body

KeyTypeDescription
request_idUnique Request ID
timestampResponse Timestamp
result_codeResult Code
messageMessage

2. API Endpoints

2.1. Item Purchase Availability Check (GET /check)

Overview

Checks whether an in-game item can be purchased, considering age restrictions and purchase limits.

Request Specifications

ItemDescription
MethodGET
Endpoint
ProtocolHTTPS
Content Typeapplication/json

Request Headers

KeyValueDescription
AuthorizationBearer Authentication Information
Content-Typeapplication/jsonContent Type

Request Parameters (Query Parameters)

KeyTypeRequiredDescription
gamestringThe unique game ID assigned within Game8Store
userstringThe unique user ID assigned within the game
itemstringThe unique item ID assigned within the game
priceintegerThe item's sale price in Game8Store (in yen)

Request Example

Response Specifications

KeyTypeDescription
request_idstringUnique Request ID
timestampstring (ISO8601)Response Timestamp
result_codestringResult Code
messagestringMessage
purchasableboolean if purchasable, otherwise
age_categorystringUser Age Category ( / / )
monthly_limitintegerMonthly Purchase Limit (JPY), if no limit
remaining_limitintegerRemaining Purchase Limit (JPY), if no limit
requested_priceintegerRequested Item Price (JPY)

Response Example (Purchasable)

Response Example (Not Purchasable - Age Restriction)

Response Example (Not Purchasable - Limit Exceeded)


2.2. Item Purchase Record Registration (POST /register)

Overview

Processes the increase of in-game items after purchase completion.

Request Specifications

ItemDetails
MethodPOST
Endpoint
ProtocolHTTPS
Content Typeapplication/json

Request Headers

KeyValueDescription
AuthorizationBearer Authentication information
Content-Typeapplication/jsonContent type

Request Body (JSON)

KeyTypeRequiredDescription
gamestringThe unique game ID assigned within Game8Store
userstringThe unique user ID assigned within the game
itemstringThe unique item ID assigned within the game
transaction_idstringTransaction ID of the purchase
item_namestringThe name of the purchased item (e.g., "100 Gem Pack")
priceintegerPurchase amount (in yen)
quantityintegerThe quantity of purchased items (e.g., 100)

Example Request


Response Specifications

Response Body

KeyTypeDescription
request_idstringUnique request ID
timestampstring (ISO8601)Timestamp of the response
result_codestringResult code
messagestringMessage
item_grantedbooleanWhether the in-game item was granted ( / )

Example Response (Success)

Example Response (Failure - Unknown User)


2.3. Retrieve Purchase History (GET /history)

Overview

Retrieves the user's past purchase history.

Request Specifications

ItemDetails
MethodGET
Endpoint
ProtocolHTTPS
Content Typeapplication/json

Request Headers

KeyValueDescription
AuthorizationBearer Authentication information
Content-Typeapplication/jsonContent type

Request Parameters (Query Parameters)

KeyTypeRequiredDescription
gamestringThe unique game ID assigned within Game8Store
userstringThe unique user ID assigned within the game
limitintegerMaximum number of records to retrieve (Default: 10)

Example Request


Response Specifications

Response Body

KeyTypeDescription
request_idstringUnique request ID
timestampstring (ISO8601)Timestamp of the response
result_codestringResult code
messagestringMessage
historyarrayList of purchase history records

Data Structure of the history Array

KeyTypeDescription
transaction_idstringPayment transaction ID
itemstringItem ID
item_namestringThe name of the purchased item (e.g., "100 Gem Pack")
priceintegerPurchase amount (in yen)
quantityintegerThe quantity of purchased items (e.g., 100)
timestampstring (ISO8601)Purchase date and time

Example Response (Success)


 

2.4. Sales Confirmation (GET /sales)

Overview

Retrieves sales information for a specified period.

Request Specifications

ItemDetails
MethodGET
Endpoint
ProtocolHTTPS
Content Typeapplication/json

Request Headers

KeyValueDescription
AuthorizationBearer Authentication Information
Content-Typeapplication/jsonContent Type

Request Parameters (Query Parameters)

KeyTypeRequiredDescription
gamestringThe unique game ID assigned within Game8Store
start_datestring (YYYY-MM-DD)Start date of data retrieval
end_datestring (YYYY-MM-DD)End date of data retrieval

Request Example


Response Specifications

Response Body

KeyTypeDescription
request_idstringUnique request ID
timestampstring (ISO8601)Timestamp of the response
result_codestringResult code
messagestringMessage
total_salesintegerTotal sales amount within the period (in JPY)
total_feesintegerTotal fees within the period (in JPY)
net_salesintegerNet sales amount (sales - fees) within the period
transactionsarrayList of sales transactions

Structure of the transactions Array

KeyTypeDescription
transaction_idstringPayment transaction ID
itemstringItem ID
item_namestringThe name of the purchased item (e.g., "100 Gem Pack")
priceintegerPurchase amount (in JPY)
quantityintegerThe quantity of purchased items (e.g., 100)
feeintegerFee amount (in JPY)
net_amountintegerNet sales (purchase amount - fee)
timestampstring (ISO8601)Purchase date and time

Response Example (Success)


3. Error Handling List

3.1. List of Error Codes

Error CodeDescriptionResolution
Success-
Invalid request formatCheck the request structure and required parameters, and send in the correct format.
Missing authentication informationEnsure the header includes a valid .
Invalid access tokenCheck the token's expiration and reissue if necessary.
Insufficient access permissionsVerify that the API endpoint has the necessary permissions.
Missing required parametersEnsure all required parameters are included and correct the request.
Invalid parameter typeExample: If is sent as a , change it to an integer.
Invalid parameter valueEnsure values are within the allowed range and are not prohibited.
No corresponding data foundVerify that a valid or is specified.
Purchase limit reachedCheck the value to ensure the limit is not exceeded.
Purchase not allowed due to age restrictionsVerify the and ensure compliance with the restriction.
Invalid transaction IDCheck if the is correct.
Specified user does not existVerify the is correct.
Specified item does not existEnsure the is valid and correct.
Internal server errorThe issue may be on the server side; retry after some time.
Temporary system failureRetry after a delay (recommended: retry after 5 seconds).
Unknown errorCheck the detailed error message and contact the development team if necessary.

3.2. Recommended Error Handling Flow

  1. Check
      • If (Success), process normally.
      • Otherwise, determine the type of error.
  1. Check if the error can be resolved on the client side
      • Errors in the and series can usually be resolved by modifying the request.
      • Errors in the series require verifying data integrity.
  1. Check if the error is retryable
      • Errors and may be temporary, so retry after a few seconds.
  1. Log and notify errors
      • For unknown errors (), log the details and report to the development team.

3.3. Retry Policy

Error CodeRetry IntervalMax Retry AttemptsNotes
After 5 seconds3 timesSince this is a server-side issue, it may be resolved in a short time.
After 10 seconds5 timesA temporary system failure; use longer retry intervals.
None0 timesImmediately report unknown errors.
Refer to this error handling list to implement appropriate error handling in your system.