The Redemption API enables you to expend (or "burn") end-user asset (called an Award in the user and admin dashboards), while logging what they were redeemed for, such as a discount on a purchase. Functional use cases include:
Redeeming store credits during the check out flow
Redeeming loyalty points for perks, like an upgrade to a first-class seat
Although the Master Award Control -> Burn API also offers the option to effectively delete assets from the Village Ledger, the Redemption API is the preferred method for use cases in which users are trading their assets for something else, because it allows you to log what they were redeeming those asset for.
To see more about real-world Redemption use cases, check out our Guides->.
Important: in order to be redeemed using the Redemption API, awards need to be created as 'non-monetary award' types. Status & Badges cannot be burned/redeemed.
Endpoint
POST/networks/YOUR_NETWORK_ID/redemption
Where 'YOUR_NETWORK_ID' is replaced with your actual Network ID.
# Remember to replace 'Bearer YOUR_API_KEY' and 'YOUR_NETWORK_ID' with your actual API key and Network IDimport requestsimport jsonurl ="https://api-ledger.villagelabs.net/networks/YOUR_NETWORK_ID/redemption"headers ={"Content-Type":"application/json","Accept":"application/json","Authorization":"Bearer YOUR_API_KEY"}data ={"user":"johnny.redemption@villagelabs.co","asset_short_name":"POINT","amount":"100.00","metadata":{"reference_id":"dpi_Ylo2Cfr8US8u1JIdAl2eZvKB","redemption_timestamp":1664900628,"redeemed_for":"discount","redeemed_for_amount":"15%","description":"Standard 100 token for 15% discount redemption."}}response = requests.post(url, headers=headers, data=json.dumps(data))print(response.json())
// Remember to replace 'Bearer YOUR_API_KEY' and 'YOUR_NETWORK_ID' with your actual API key and Network IDconstaxios=require('axios');consturl="https://api-ledger.villagelabs.net/networks/YOUR_NETWORK_ID/redemption";constheaders= {"Content-Type":"application/json","Accept":"application/json","Authorization":"Bearer YOUR_API_KEY"};constdata= { user:"johnny.redemption@villagelabs.co", asset_short_name:"POINT", amount:"100.00", metadata: { reference_id:"dpi_Ylo2Cfr8US8u1JIdAl2eZvKB", redemption_timestamp:1664900628, redeemed_for:"discount", redeemed_for_amount:"15%", description:"Standard 100 token for 15% discount redemption." }};axios.post(url, data, {headers: headers}).then((response) => {console.log(response.data); }).catch((error) => {console.error(error); });
# Remember to replace 'Bearer YOUR_API_KEY' and 'YOUR_NETWORK_ID' with your actual API key and Network IDcurl -X POST 'https://api-ledger.villagelabs.net/networks/YOUR_NETWORK_ID/redemption' \-H 'Content-Type: application/json' \-H 'Accept: application/json' \-H 'Authorization: Bearer YOUR_API_KEY' \-d '{"user":"johnny.redemption@villagelabs.co","asset_short_name":"POINT","amount":"100.00","metadata": {"reference_id":"dpi_Ylo2Cfr8US8u1JIdAl2eZvKB","redemption_timestamp":1664900628,"redeemed_for":"discount","redeemed_for_amount":"15%","description":"Standard 100 token for 15% discount redemption." }}'
# Remember to replace 'Bearer YOUR_API_KEY' and 'YOUR_NETWORK_ID' with your actual API key and Network IDrequire'net/http'require'uri'require'json'uri =URI.parse("https://api-ledger.villagelabs.net/networks/YOUR_NETWORK_ID/redemption")http =Net::HTTP.new(uri.host, uri.port)request =Net::HTTP::Post.new(uri.request_uri,'Content-Type'=>'application/json','Accept'=>'application/json','Authorization'=>'Bearer YOUR_API_KEY')request.body = { user: "johnny.redemption@villagelabs.co", asset_short_name: "POINT", amount: "100.00", metadata: { reference_id: "dpi_Ylo2Cfr8US8u1JIdAl2eZvKB", redemption_timestamp: 1664900628, redeemed_for: "discount", redeemed_for_amount: "15%", description: "Standard 100 token for 15% discount redemption." }}.to_jsonresponse = http.request(request)puts response.body
importorg.json.JSONObject;importorg.json.HTTP;importjava.net.http.HttpRequest;importjava.net.http.HttpHeaders;importjava.net.URI;importjava.net.http.HttpClient;importjava.net.http.HttpResponse;importjava.net.http.HttpRequest.BodyPublishers;publicclassMain {publicstaticvoidmain(String[] args) throwsException {HttpClient client =HttpClient.newHttpClient();// Create metadata JSONObjectJSONObject metadata =newJSONObject();metadata.put("reference_id","dpi_Ylo2Cfr8US8u1JIdAl2eZvKB");metadata.put("redemption_timestamp",1664900628);metadata.put("redeemed_for","discount");metadata.put("redeemed_for_amount","15%");metadata.put("description","Standard 100 token for 15% discount redemption.");// Create main JSONObjectJSONObject redemption =newJSONObject();redemption.put("user","johnny.redemption@villagelabs.co");redemption.put("asset_short_name","POINT");redemption.put("amount","100.00");redemption.put("metadata", metadata);// Create requestHttpRequest request =HttpRequest.newBuilder().uri(newURI("https://api-ledger.villagelabs.net/networks/YOUR_NETWORK_ID/redemption")).header("Content-Type","application/json").header("Accept","application/json") .header("Authorization", "Bearer YOUR_API_KEY") // Remember to replace 'Bearer YOUR_API_KEY' and 'YOUR_NETWORK_ID' with your actual API key and Network ID
.POST(BodyPublishers.ofString(redemption.toString())).build();HttpResponse<String> response =client.send(request,HttpResponse.BodyHandlers.ofString());System.out.println(response.body()); }}
// Remember to replace 'Bearer YOUR_API_KEY' and 'YOUR_NETWORK_ID' with your actual API key and Network IDpackagemainimport ("bytes""net/http""fmt")funcmain() { url :="https://api-ledger.villagelabs.net/networks/YOUR_NETWORK_ID/redemption"var jsonData = []byte(`{ "user": "johnny.redemption@villagelabs.co", "asset_short_name": "POINT", "amount": "100.00", "metadata": { "reference_id": "dpi_Ylo2Cfr8US8u1JIdAl2eZvKB", "redemption_timestamp": 1664900628, "redeemed_for": "discount", "redeemed_for_amount": "15%", "description": "Standard 100 token for 15% discount redemption." } }`) req, err := http.NewRequest("POST", url, bytes.NewBuffer(jsonData)) req.Header.Set("Content-Type", "application/json") req.Header.Set("Accept", "application/json") req.Header.Set("Authorization", "Bearer YOUR_API_KEY") client :=&http.Client{} resp, err := client.Do(req)if err !=nil {panic(err) }defer resp.Body.Close() fmt.Println("response Status:", resp.Status)}
Short Name of the asset to be redeemed. This is the same Short Name created and viewable on the Village admin dashboard.
Yes
Amount
amount
string
Amount to be redeemed.
Yes
Metadata
metadata
object
Additional metadata. See Metadata fields for options.
No
Reference ID
reference_id
string
An optional identifier that can be used for reporting purposes.
No
Redemption Timestamp
redemption_timestamp
integer
The Unix timestamp of when the redemption occurred. If this is blank, Village will use the timestamp the activity was received via the Village API as the Redemption Timestamp.
No
Redeemed For
redeemed_for
string
An optional descriptor that can be used to record what the user received in return for the redeemed asset.
No
Redeemed For Amount
redeemed_for_amount
string
An optional descriptor that can be used to record the amount of something the user received in return for the redeemed asset.