Sending consumption information

This API transmits user consumption information to an app store when an app user requests a refund.

The Consumption Information Transmission API uses server-to-server communication between the Hive server and the app server. The Hive server sends a consumption information request to the app server, and the app server returns the response to the Hive server.

Info

Consumption information transmission supports Apple App Store and Google Play. Because each store has a different trigger and response data specification, select the store you want to integrate from the tabs below.

Apple App StoreGoogle Play

Apple App Store¶

Some consumption information sent to the store exists only on the app server. To send this data to Apple App Store, the app server must provide it to the Hive server.

The app server URL is an API endpoint opened by the app server to provide data to the Hive server. Configure the endpoint according to the specification below and register it as the app server URL. Whenever a user requests a refund, the Hive server sends a POST request to this endpoint and receives the required data from the app server. The Hive server aggregates this data and transmits consumption information to Apple App Store on behalf of the app developer.

The overall process is as follows.

App: Configure an API endpoint according to the specification below and prepare the server URL
App: In Additional Service Settings > Consumption Information Transmission in the Hive Console, enable Apple App Store and register the server URL
App client: While the app is running, obtain consent to transmit in-app product consumption information
App user: Request a refund in the app
Apple: Send a consumption information request (CONSUMPTION_REQUEST) to the Hive server
Hive server: Send a POST API request to the server URL registered by the app and receive consumption information in the response from the app server
Hive server: Transmit consumption information to Apple App Store. Apple responds with HTTP 202 on success

Warning

If the app user does not consent to information transmission in the consent popup, the Hive server does not send the data to the store even if it receives the data from the app server. The app server does not send the user consent status (customerConsented); the Hive server sets it directly.

Disable firewall rules¶

The API endpoint registered as the server URL must retrieve consumption information using the user information (player_id) and transaction information (transaction_id) in the request parameters and return data that conforms to the specification below.

To allow the Hive server to send requests to the app server API endpoint, disable the firewall inbound rules for the following IP addresses on the app server.

Hive server IP
15.165.223.210
3.34.158.195
43.202.20.33
13.209.91.38
3.34.235.15
15.165.134.120

Configure the API request (Hive server to app server)¶

The following is the POST request sent from the Hive server to the app server.

API information	Description
Method	POST
Response Format	JSON
Content-type	application/json

Request body¶

The request body is as follows.

Name	Type	Required (M: Mandatory, O: Optional)	Description
gameindex	Integer	M	App Center Game Index
appid	String	M	App Center App ID
server_id	String	M	App server ID
player_id	String	M	User identifier in the app (the user identification value used for purchase verification). Corresponds to `user_seq` in V1
transaction_id	String	M	Apple original transaction ID (`originalTransactionId`)
hiveiap_transaction_id	String	M	Transaction ID generated for each successfully verified receipt. The `hiveiap_transaction_id` value returned from Hive IAP v4 receipt verification

The following is an example request body.

{
        "gameindex": 539,
        "appid": "com.com2us.hivesdk.normal.freefull.apple.global.ios.universal",
        "server_id": "server_01",
        "player_id": "222333",
        "transaction_id": "2000000123456789",
        "hiveiap_transaction_id": "AP_13"
}

Configure the API response (app server to Hive server)¶

The app server sends the processing result code (code), result message (message), and consumption information (data) to the Hive server.

Response body¶

The Hive server determines success from the code value. If the value is 200, the request is successful and the server uses data. For any other code, the server does not transmit the item and records message as the reason. code is required. If it is omitted, the request is treated as an error and the item is not transmitted.

Name	Type	Required (M: Mandatory, O: Optional)	Description
code	Integer	M	Processing result code. Only 200 indicates success; all other codes are treated as errors
message	String	O	Processing result message. Describes the reason for an error
data	Object	M	Response data (required on success)
┕ delivery_status	String	M	Consumable item delivery status. One of the values in Delivery status below
┕ refund_preference	String	O	Refund preference. One of the values in Refund preference below
┕ consumption_percentage	Integer	O	Consumption percentage. 0-100000 in millipercent (100000 = 100%)
┕ sample_content_provided	Integer	O	Whether sample content was provided. 0 or 1

Response codes¶

Value	Description
200	Success
400	Invalid request value
500	Server error

Delivery status (`delivery_status`)¶

Indicates the consumable item's delivery status. This required field must contain one of the following five values.

Value	Meaning
DELIVERED	The consumable item was delivered and works correctly
UNDELIVERED_QUALITY_ISSUE	The item was not delivered because of a quality issue
UNDELIVERED_WRONG_ITEM	A different or incorrect item was delivered
UNDELIVERED_SERVER_OUTAGE	The item was not delivered because of a server outage
UNDELIVERED_OTHER	The item was not delivered for another reason

Refund preference (`refund_preference`)¶

Sends the app's preferred refund outcome to Apple. If this optional field is sent, it must contain one of the following three values.

Value	Meaning
GRANT_FULL	Prefer a full refund
DECLINE	Prefer to decline the refund
GRANT_PRORATED	Prefer a partial or prorated refund, mainly for subscriptions

Warning

If any of the following values are invalid, the item is excluded and not transmitted to the store.

delivery_status is required and must contain one of the five values above.
If sent, refund_preference must contain one of the three values above.
If sent, consumption_percentage must be an integer from 0 through 100000.

Note

The Hive server automatically adjusts the following values according to Apple's rules.

If delivery_status is not DELIVERED, consumption_percentage is sent as 0.
If refund_preference is GRANT_PRORATED (subscription), consumption_percentage is omitted.

The following is an example response body for a successful request.

{
        "code": 200,
        "message": "OK",
        "data": {
                "delivery_status": "DELIVERED",
                "refund_preference": "GRANT_FULL",
                "consumption_percentage": 100000,
                "sample_content_provided": 0
        }
}

Google Play¶

Some consumption information sent to the store exists only on the app server. To send this data to Google Play, the app server must provide it to the Hive server.

The app server URL is an API endpoint opened by the app server to provide data to the Hive server. Configure the endpoint according to the specification below and register it as the app server URL. Whenever a refund review notification occurs, the Hive server sends a POST request to this endpoint and receives the required data from the app server. The Hive server aggregates this data and sends the refund review information to Google on behalf of the app developer.

The overall process is as follows.

App: Configure an API endpoint according to the specification below and prepare the server URL
App: In Additional Service Settings > Consumption Information Transmission in the Hive Console, enable Google Play and register the server URL
App user: Request a refund (chargeback) for the transaction directly from a financial institution, such as a credit card issuer
Google: Send a refund review notification (pendingRefundReviewNotification) to the Hive server
Hive server: Send a POST API request to the server URL registered by the app and receive data in the response
Hive server: Send refund review information to Google with orders:reviewrefund. Google responds with an empty HTTP 200 body on success

Note

Google Play refund reviews do not require an in-app consent process. When a user requests a refund (chargeback) directly from a financial institution, Google sends a refund review notification to the Hive server for processing.

Disable firewall rules¶

The API endpoint registered as the server URL must retrieve consumption information using the user information (player_id) and transaction information (order_id) in the request parameters and return data that conforms to the specification below.

To allow the Hive server to send requests to the app server API endpoint, disable the firewall inbound rules for the following IP addresses on the app server.

Hive server IP
15.165.223.210
3.34.158.195
43.202.20.33
13.209.91.38
3.34.235.15
15.165.134.120

Configure the API request (Hive server to app server)¶

The following is the POST request sent from the Hive server to the app server.

API information	Description
Method	POST
Response Format	JSON
Content-type	application/json

The request body is as follows.

Name	Type	Required (M: Mandatory, O: Optional)	Description
gameindex	Integer	M	App Center Game Index
appid	String	M	App Center App ID
server_id	String	M	App server ID
player_id	String	M	User identifier in the app (the user identification value used for purchase verification). Corresponds to `user_seq` in V1
order_id	String	M	Google order ID (`orderId`)
hiveiap_transaction_id	String	M	The `hiveiap_transaction_id` value returned from Hive IAP v4 receipt verification

The following is an example request body.

{
        "gameindex": 539,
        "appid": "com.com2us.hivesdk.normal.freefull.google.global.android.universal",
        "server_id": "server_01",
        "player_id": "222333",
        "order_id": "GPA.3300-1234-5678-90123",
        "hiveiap_transaction_id": "GO_13"
}

Configure the API response (app server to Hive server)¶

The app server sends the processing result code (code), result message (message), and consumption information (data) to the Hive server.

The Hive server determines success from the code value. If the value is 200, the request is successful and the server uses data. For any other code, the server does not transmit the item and records message as the reason. code is required. If it is omitted, the request is treated as an error and the item is not transmitted.

Name	Type	Required (M: Mandatory, O: Optional)	Description
code	Integer	M	Processing result code. Only 200 indicates success; all other codes are treated as errors
message	String	O	Processing result message. Describes the reason for an error
data	Object	M	Response data (required on success)
┕ refund_preference	String	M	Refund preference. One of the values in Refund preference below
┕ sample_content_provided	Integer	M	Whether sample content was provided. 0 or 1
┕ consumption_percentage_milliunits	Integer	M	Consumption percentage. 0-100000 in millipercent (100000 = 100%)
┕ consumption_usage_events	Array	O	Consumption event list (up to 1000). See Consumption events below

Response codes¶

Value	Description
200	Success
400	Invalid request value
500	Server error

Refund preference (`refund_preference`)¶

Sends the app's preferred refund outcome to Google. This required field must contain one of the following four values.

Value	Meaning
APPROVE	Prefer to approve the refund
DECLINE	Prefer to decline the refund
NEUTRAL	No preference (neutral)
REFUND_PREFERENCE_UNSPECIFIED	No preference specified

Consumption events (`consumption_usage_events`)¶

Each consumption event contains the following fields. All fields are optional, but if location is sent, location.region_code is required.

Name	Type	Required	Description
obfuscated_account_id	String	O	Obfuscated account identifier
obfuscated_profile_id	String	O	Obfuscated profile identifier
consumption_time	String	O	Consumption time (RFC 3339, for example, `2026-07-20T00:00:00Z`)
ip_address	String	O	IP address at the time of consumption
consumption_item_description	String	O	Description of the consumed item
location	Object	O	Consumption location information
┕ region_code	String	M when `location` is included	Region code (CLDR, for example, `KR`)
┕ administrative_area	String	O	Administrative area
┕ locality	String	O	City
┕ sublocality	String	O	Sublocality

Warning

If any of the following values are invalid, the item is excluded and not transmitted to Google.

refund_preference is required and must contain one of the four values above.
sample_content_provided is required and must be 0 or 1.
consumption_percentage_milliunits is required and must be an integer from 0 through 100000.
If sent, consumption_usage_events can contain up to 1000 events. If an event contains location, location.region_code is required.

The following is an example response body for a successful request.

{
        "code": 200,
        "message": "OK",
        "data": {
                "refund_preference": "APPROVE",
                "sample_content_provided": 0,
                "consumption_percentage_milliunits": 100000,
                "consumption_usage_events": [
                        {
                                "consumption_time": "2026-07-20T00:00:00Z",
                                "ip_address": "203.0.113.10",
                                "consumption_item_description": "Sample consumed item",
                                "location": {
                                        "region_code": "KR"
                                }
                        }
                ]
        }
}

Sending consumption information

Apple App Store¶

Disable firewall rules¶

Configure the API request (Hive server to app server)¶

Request body¶

Configure the API response (app server to Hive server)¶

Response body¶

Response codes¶

Delivery status (delivery_status)¶

Refund preference (refund_preference)¶

Google Play¶

Disable firewall rules¶

Configure the API request (Hive server to app server)¶

Configure the API response (app server to Hive server)¶

Response codes¶

Refund preference (refund_preference)¶

Consumption events (consumption_usage_events)¶

Delivery status (`delivery_status`)¶

Refund preference (`refund_preference`)¶

Refund preference (`refund_preference`)¶

Consumption events (`consumption_usage_events`)¶