Use-case tutorial: Rewards

In this tutorial, you demonstrate how a publisher can reward a user with tokens. This ability can be added to most market and other in-app economy applications.

Allow about 10 minutes to complete this tutorial.

The following diagram shows the process to award tokens to users by using the balance transfer operation.

API operations in this tutorial

To complete this tutorial

This tutorial uses the Explore Tilia transactions collection from the shared workspace.

To complete this tutorial successfully:

1. Make sure the software described in Get started with the tutorials has been installed on your system and configured.
2. Make sure that you have initialized the Tilia Client Info environment variables by running the User account tutorials .
3. In Postman:
   1. Open the Tilia tutorial workspace you created in Get started with the tutorials for this tutorial.
   2. Make sure you have the Manage user accounts and Explore Tilia transactions collections forked to your Tilia tutorial workspace .
   3. Make sure that you've selected the Tilia Client Info environment and confirmed that it has:
      1. Your Tilia developer credentials.
      2. All of the user-related environment variables with Current values defined.
   4. In your Tilia tutorial workspace , open the list of Collections .
   5. In the list of Collections , expand the Explore Tilia transactions collection.
   6. If it's been more than an hour since you last got an access token for this collection, get a new one as described in Tutorial: Transactions overview , and then return to continue here.

Give rewards to recipient

These requests process and view the token transfer from the publisher to the recipient.

Process account-credit balance transfer

This request transfers tokens from the publisher to the recipient.

To process the account credit balance transfer in Postman:

1. In the Explore Tilia transactions collection, in the Account credits folder, open the Perform account credit balance transfer request.
2. In the Body tab:
   1. Review the content of the request body, shown here.
      Copy

      Copied

      {
          "destination_wallet_id": "{{recipients_wallet_id}}",
          "amount": 250,
          "currency": "TIL",
          "reason": "goodwill",
          "reference_type": "RefType",
          "reference_id": "RefID",
          "metadata": {"data": {"value1": 1, "value2": "Value2"}}
      }

   2. Notice the destination_wallet_id property uses the recipients_wallet_id collection variable.
   3. Review the values of the other properties. For more information about the properties in the request body, see Account credit balance transfer .
3. In the Perform account credit balance transfer request, choose Send .
4. After the response returns, open the response Body tab below the request to see the response body details.

A successful request returns a response body similar to the following:

{
    "status": "Success",
    "message": [],
    "codes": [],
    "payload": {
        "balance_transfer_id": "bt_2ZRs46RxWrTuX5fnqs9eyowYQ0v"
    }
}

The script that runs after the request saves the balance_transfer_id from the payload in the  last_balance_transfer_invoice_id collection variable to use in the next request.

Get info about last balance transfer

This request gets more information about a balance transfer than the previous request returned.

To get more details about a balance transfer, in Postman:

1. In the Explore Tilia transactions collection, in the Account credits folder, open the Get info about last balance transfer request.
2. In the URL field, notice the balance_transfer_id parameter uses the last_balance_transfer_id collection value that was saved in the previous request.
3. In the Get info about last balance transfer request, choose Send .
4. After the response returns, open the response Body tab below the request to see the response body details.

A successful request returns a response body similar to the following. Notice that this response contains much more information about the request than the one from the previous request.

{
    "status": "Success",
    "message": [],
    "codes": [],
    "payload": {
        "balance_transfer_id": "bt_2ZRs46RxWrTuX5fnqs9eyowYQ0v",
        "balance_transfer_type": "fund_user",
        "integrator": "tilia-test",
        "account_id": "75452177-cad5-42bd-8530-4fb86ecc6fa9",
        "reference_type": "RefType",
        "reference_id": "RefID",
        "status": "EXECUTED",
        "invoice_id": "inv_2ZRs42G4xYkrpuVrC7HiryNyPZ6",
        "metadata": {
            "data": {
                "value1": 1,
                "value2": "Value2"
            },
            "reason": "goodwill"
        },
        "failure_reason": "",
        "created": "2023-12-12T15:47:11.560267Z",
        "updated": "2023-12-12T15:47:11.679086Z"
    }
}

The payload.status value of EXECUTED shows that the tokens were transferred successfully.

Get balance transfer invoice

This exercise recalls the invoice for the balance-transfer transaction.

The preceding exercise recalls information about the transfer, but that information does not contain the transaction's invoice.

To get the invoice from a balance transfer, in Postman:

1. In the Explore Tilia transactions collection, in the Account credits folder, open the Get a balance transfer invoice request.
2. In the URL field, notice the balance_transfer_invoice_id parameter uses the last_balance_transfer_invoice_id collection value that was saved in the previous request.
3. In the Get a balance transfer invoice request, choose Send .
4. After the response returns, open the response Body tab below the request to see the response body details.

{
    "status": "Success",
    "message": [],
    "codes": [],
    "payload": {
        "invoice_id": "inv_2c6XrfIoUoAcmLUneRc41WMCh1C",
        "account_id": "75452177-cad5-42bd-8530-4fb86ecc6fa9",
        "invoice_type": "balance_transfer",
        "reference_type": "invoicing.balance_transfer.balance_transfer_id",
        "reference_id": "bt_2c6Xre6kmzs3lMIuSlU0tVh7NiV",
        "state": "SUCCESS",
        "description": "",
        "metadata": null,
        "summary": {
            "total_amount": 250,
            "total_amount_usd": 250,
            "currency": "",
            "display_amount": "TIL 2.50",
            "subtotal": {
                "total_amount": 250,
                "total_amount_usd": 250,
                "currency": "",
                "display_amount": "TIL 2.50"
            },
            "tax": {
                "total_amount": 0,
                "total_amount_usd": 0,
                "currency": "",
                "display_amount": ""
            },
            "payment_breakdown": [],
            "tax_calculation": "",
            "is_tax_exempt": false
        },
        "failure_code": "",
        "failure_reason": "",
        "created": "2024-02-08T23:00:01Z",
        "updated": "2024-02-08T23:00:01Z",
        "payment_methods": {},
        "line_items": {
            "352f1b0a-e295-4500-97dc-5cd5ae7c69e0": {
                "line_item_id": "352f1b0a-e295-4500-97dc-5cd5ae7c69e0",
                "product_sku": "",
                "product_code": "",
                "amount": 250,
                "currency": "TIL",
                "display_amount": "TIL 2.50",
                "reference_type": "",
                "reference_id": "",
                "transaction_type": "publisher_sourced",
                "description": "",
                "metadata": null,
                "tags": {},
                "sort_order": 0,
                "subitems": {}
            }
        },
        "subitems": {},
        "tags": {}
    }
}

This response contains much more information about the transaction than the one from the previous request.

Conclusion

The exercises in this tutorial walked you through interactions that award tokens to users without a purchase transaction.

You might also consider these options for sharing and splitting income from transactions:

• Royalties
• Commissions
• Patronage