TradeSetUnowned/v0001 (Steamworks Documentation)

Steamworks Documentation

TradeSetUnowned/v0001

Steamworks Documentation > Features > Steam Inventory Service > Steam Economy > TradeSetUnowned/v0001

This is called when the Steam Economy Server needs to remove an asset or chunk of currency from a user and change it to an unowned state. It is up to the asset server to verify that this is a legal change to make to this asset or currency type. It should check asset ownership matches the specified owner, that the asset or currency is tradable, and that the requested amount is present.

Called by: Trading System

HTTP Method: POST

Parameters:

Name	Type	Required	Description
key	string	✔	This is the "Asset Server Key" that you provided in your app's Steam Economy Settings on the partner site.
appid	uint32	✔	32bit App ID of the application associated with the assets.
owner	uint64	✔	The 64-bit Steam ID of the current owner of the asset or currency.
contextid	uint64	✔	The 64-bit ID of the context in which this asset or currency can be found.
assetid	uint64		The 64-bit asset ID being removed. Either assetid or currencyid will be set to indicate which kind of object should be set to unowned.
currencyid	uint32		The 32-bit currency ID being removed. Either assetid or currencyid will be set to indicate which kind of object should be set to unowned.
amount	uint32		The number of the asset or currency to remove. This number will always be 1 for non-stackable assets. It will always be less or equal to the amount that the Steam Economy server believes is present for this asset/currency in this context. Defaults to 1.
trade_start_time	uint32	✔	The time the trade session responsible for this action started, expressed in seconds from Jan. 1, 1970.
audit_action	uint32	✔	A 32-bit number that specifies what kind of action is causing this asset or currency to be set unowned.
audit_reference	uint64	✔	A 64-bit number that identifies which event is action is associated with. The asset server may wish to record this number for auditing and debugging purposes.
leave_original	bool	✔	If this boolean parameter is set to 1 (to indicate true), then the asset server is being asked to duplicate the item and create a new unowned item that is a copy of the asset specified. This will only be true for one-sided undos of a trade by a support agent. Defaults to 0 (false).
request_repeated	bool	✔	If this is set to 1 (to indicate true), then the Steam Economy server is indicating that it has made an identical request to this one at some point in the past but did not receive a clear success or failure. If it appears that the asset or currency has already been set to Unowned for the same audit_action and audit_reference, the asset server should return success and set new_assetid and new_contextid to whatever was returned on the first request.
is_market	bool	✔	If this is set to 1 (to indicate true), then the request is being performed in response to some activity on the Steam Community Market.

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.
  
  NOTE: If success is set to false or if the response is invalid or times out, Steam will retry the TradeSetUnowned request until it succeeds. If the error is a permanent failure (e.g. the item no longer exists), you should set should_retry to 0.
- should_retry - By default, Steam will retry TradeSetUnowned calls until the request succeeds. It does this to make sure the item is a consistent state before deciding what to do next. However, for a permanent failure where you know that retries will not change the response (for example, if the item no longer exists), you can set the value of this field to 0.
  
  You may also set this value to 1 if you wish to explicitly communicate to Steam that the error is a transient error (for example, you were unable to check/modify your database).
  
  This field is required because there are scenarios where the asset server might receive two different TradeSetUnowned requests for the same assetid, but with different audit_reference values. For example, a user may try to trade an item while simultaneously trying to list the item on the Community Market.
  The asset server should accept the first TradeSetUnowned request, but then reject the second request since the item is no longer owned by the user. In this example, the response for the second request should set have should_retry set to 0 since that request will never succeed and has not ever succeeded.
  
  Important: When this value is 0, Steam assumes your asset server has never made any modification to this asset in response to the TradeSetUnowned request.
  Thus, it is important that this field only be set to 0 when you are completely certain that the TradeSetUnowned request was not and never has been handled. Getting this wrong could lead to users losing items.
  For example, if you have logic to handle a duplicate request and you have logic to check that the asset still exists, you'll want the duplicate request handling to occur first. Otherwise, on a repeated request, your asset server would return that the item no longer exists and tell Steam not to retry instead of properly returning the results of the previous call.
- 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.
- new_assetid (optional) - The 64-bit asset ID of the unowned version of this asset. This is only set for asset transfers. This could be a new asset ID or be the same as the asset id specified in the request depending on how the implementation of the asset server.
  Defaults to being the same as the asset ID that was passed in.
- new_contextid (optional) - The 64-bit context ID of the unowned version of this asset or currency. This could be a different context ID or be the same as the context id specified in the request depending on how the implementation of the asset server. Defaults to being the same as the context ID that was passed in.

Audit Actions

This is the current list of audit actions that could be passed with this method. New audit types could be added to this list at any time, so asset servers should be ready to deal with any unsigned 32-bit number as an audit action.

101 - Trade Commit - The request is part of committing a trade. audit_reference is a trade ID.
102 - Trade Rollback - The request is part of rolling back a trade. audit_reference is a trade ID.