Redemption API

Is this page helpful? Give us feedback on our docs ->

About Redemption

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:

1. Redeeming store credits during the check out flow

2. 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.

API Field Overview

Body Fields

Field Name	JSON Key	Type	Description	Required
User	user	string	The user. May be email or user_id.	Yes
Asset Short Name	asset_short_name	string	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

Metadata

Field Name	JSON Key	Type	Description	Required
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.	No
Description	description	string	A description of the redemption.	No

Examples

Body

// Example Redemption Body
{
    "user": "[e-mail]",
    "asset_short_id": "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."
    }
}

By Language

Python

# Remember to replace 'Bearer YOUR_API_KEY' and 'YOUR_NETWORK_ID' with your actual API key and Network ID

import requests
import json

url = "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": "[e-mail]",
    "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())

Javascript

// Remember to replace 'Bearer YOUR_API_KEY' and 'YOUR_NETWORK_ID' with your actual API key and Network ID

const axios = require('axios');

const url = "https://api-ledger.villagelabs.net/networks/YOUR_NETWORK_ID/redemption";

const headers = {
  "Content-Type": "application/json",
  "Accept": "application/json",
  "Authorization": "Bearer YOUR_API_KEY"
};

const data = {
  user: "[e-mail]",
  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);
  });

cURL

# Remember to replace 'Bearer YOUR_API_KEY' and 'YOUR_NETWORK_ID' with your actual API key and Network ID

curl -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": "[e-mail]",
    "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."
    }
}'

Ruby

# Remember to replace 'Bearer YOUR_API_KEY' and 'YOUR_NETWORK_ID' with your actual API key and Network ID

require '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: "[e-mail]",
  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_json

response = http.request(request)

puts response.body

Java

import org.json.JSONObject;
import org.json.HTTP;
import java.net.http.HttpRequest;
import java.net.http.HttpHeaders;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpResponse;
import java.net.http.HttpRequest.BodyPublishers;

public class Main {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();

        // Create metadata JSONObject
        JSONObject metadata = new JSONObject();
        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 JSONObject
        JSONObject redemption = new JSONObject();
        redemption.put("user", "[e-mail]");
        redemption.put("asset_short_name", "POINT");
        redemption.put("amount", "100.00");
        redemption.put("metadata", metadata);

        // Create request
        HttpRequest request = HttpRequest.newBuilder()
                .uri(new URI("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());
    }
}

Go

// Remember to replace 'Bearer YOUR_API_KEY' and 'YOUR_NETWORK_ID' with your actual API key and Network ID

package main

import (
	"bytes"
	"net/http"
	"fmt"
)

func main() {
	url := "https://api-ledger.villagelabs.net/networks/YOUR_NETWORK_ID/redemption"
	var jsonData = []byte(`{
		"user": "[e-mail]",
		"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)
}

Is this page helpful? Give us feedback on our docs ->