Steamworks Documentation
GrantPromoItem/v0001
This is an optional API to implement and it is only needed when your game is included into the Loot Drop system. The GrantPromoItem API is called by Steam to grant an item to a user during a Steam sale event that is participating in a Loot Drop program.

The purpose is to grant a user a promotional item as a reward for participating in the event.


Called by: Loot Drop System

HTTP Method: POST

Parameters:

NameTypeRequiredDescription
owneruint64The 64-bit steam ID of the user that should receive the item.
promoiduint64A 64-bit number that identifies the type of item to be granted. These are arbitrary. The partner must communicate the list of accepted values to their Valve contact.
audit_referenceuint64A unique 64-bit number used to identify the request.
request_repeatedboolIf this is true, the asset server should check whether or not it has handled the given audit_reference before. If it has previously successfully handled the request, the asset server should return the result it returned previously with the new asset ID and context ID filled in.

Returns

The output from this method should be encoded in the JSON format.

Response:
  • result
    • success - True if the method was successful. If the asset server is returning false, it should set error to a string that explains why.
    • error - a string describing why this call failed. This message will be recorded in the error log, which is available under the Economy tab on the Steamworks site.
    • should_retry - Required if success is false. Set should_retry to true if Steam should retry later. For example, this should be true if the failure is transient, like a SQL failure or other temporary backend issue on the asset server. Set to false if the error is permanent and Steam should give up.
    • new_assetid - The 64-bit asset ID that was granted to the user.
    • new_contextid - The 64-bit context ID the asset that was granted to the user is in.

Example Output

This is an example of the return output we would expect from your implementation.

Example 1

{ "result": { "success": true, "new_assetid": 131363189, "new_contextid": 2, } }

Example 2

{ "result": { "success": false, "should_retry": true, "error": "An internal failure occurred", } }