{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["openapiLink"]},"type":"markdown"},"seo":{"title":"Use-case tutorial: Rewards","description":"Tilia Wallet Developer Documentation","siteUrl":"https://thunes-tilia-docs.redocly.app/","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"use-case-tutorial-rewards","__idx":0},"children":["Use-case tutorial: Rewards"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Allow about 10 minutes to complete this tutorial."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following diagram shows the process to award tokens to users by using the balance transfer operation."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/use-case-tutorial-reward.738778c7479ab7cc0557b3d084390b3c55c5f1cc1fef841e8100a65a53231de0.9c1bb791.png","alt":"Diagram of award use case interactions"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"api-operations-in-this-tutorial","__idx":1},"children":["API operations in this tutorial"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Tutorial interaction"},"children":["Tutorial interaction"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Tilia APIs used"},"children":["Tilia APIs used"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"#process-account-credit-balance-transfer"},"children":["Process account-credit balance transfer"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"OpenapiLink","attributes":{"link":"balances/openapi/other/accountcredit","text":"Account credit balance transfer"},"children":[]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"to-complete-this-tutorial","__idx":2},"children":["To complete this tutorial"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This tutorial uses the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Explore Tilia transactions"]}," collection from the"," ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://www.postman.com/tilia-docs-testing/workspace/get-started-using-tilia-services/overview"},"children":["shared workspace"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["To complete this tutorial successfully:"]}]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Make sure the software described in ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/tutorials/tutorial_get_started"},"children":["Get started with the tutorials"]}," ","has been installed on your system and configured."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Make sure that you have initialized the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Tilia Client Info"]}," environment variables by running the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/tutorials/user-accounts"},"children":["User account tutorials"]},"."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In Postman:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Open the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Tilia tutorial workspace"]}," you created in ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/tutorials/tutorial_get_started"},"children":["Get started with the tutorials"]}," for this tutorial."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Make sure you have the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Manage user accounts"]}," and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Explore Tilia transactions"]}," collections"," ","forked to your ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Tilia tutorial workspace"]},"."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Make sure that you've selected the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Tilia Client Info"]}," environment and confirmed that it has:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your Tilia developer credentials."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All of the user-related environment variables with ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Current values"]}," defined."]}]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In your ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Tilia tutorial workspace"]},", open the list of ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Collections"]},"."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In the list of ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Collections"]},", expand the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Explore Tilia transactions"]}," collection."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/tutorials/use-cases#get-an-access-token"},"children":["Tutorial: Transactions overview"]},","," ","and then return to continue here."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"give-rewards-to-recipient","__idx":3},"children":["Give rewards to recipient"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These requests process and view the token transfer from the publisher to the recipient."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"process-account-credit-balance-transfer","__idx":4},"children":["Process account-credit balance transfer"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This request transfers tokens from the publisher to the recipient."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["To process the account credit balance transfer in Postman:"]}]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Explore Tilia transactions"]}," collection, in the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Account credits"]}," folder,"," ","open the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Perform account credit balance transfer"]}," request."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Body"]}," tab:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Review the content of the request body, shown here."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n    \"destination_wallet_id\": \"{{recipients_wallet_id}}\",\n    \"amount\": 250,\n    \"currency\": \"TIL\",\n    \"reason\": \"goodwill\",\n    \"reference_type\": \"RefType\",\n    \"reference_id\": \"RefID\",\n    \"metadata\": {\"data\": {\"value1\": 1, \"value2\": \"Value2\"}}\n}\n","lang":"json"},"children":[]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Notice the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["destination_wallet_id"]}," property uses the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["recipients_wallet_id"]}," collection variable."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Review the values of the other properties."," ","For more information about the properties in the request body,"," ","see ",{"$$mdtype":"Tag","name":"OpenapiLink","attributes":{"link":"balances/openapi/other/accountcredit","text":"Account credit balance transfer"},"children":[]},"."]}]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Perform account credit balance transfer"]}," request, choose ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Send"]},"."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After the response returns, open the response ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Body"]}," tab below the request"," ","to see the response body details."]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A successful request returns a response body similar to the following:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n    \"status\": \"Success\",\n    \"message\": [],\n    \"codes\": [],\n    \"payload\": {\n        \"balance_transfer_id\": \"bt_2ZRs46RxWrTuX5fnqs9eyowYQ0v\"\n    }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The script that runs after the request saves the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["balance_transfer_id"]}," from the payload in the  ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["last_balance_transfer_invoice_id"]}," collection variable to use in the next request."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"get-info-about-last-balance-transfer","__idx":5},"children":["Get info about last balance transfer"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This request gets more information about a balance transfer than the previous request returned."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["To get more details about a balance transfer, in Postman:"]}]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Explore Tilia transactions"]}," collection, in the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Account credits"]}," folder,"," ","open the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Get info about last balance transfer"]}," request."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["URL"]}," field, notice the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["balance_transfer_id"]}," parameter uses the"," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["last_balance_transfer_id"]}," collection value that was saved in the previous request."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Get info about last balance transfer"]}," request, choose ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Send"]},"."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After the response returns, open the response ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Body"]}," tab below the request to see the response body details."]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n    \"status\": \"Success\",\n    \"message\": [],\n    \"codes\": [],\n    \"payload\": {\n        \"balance_transfer_id\": \"bt_2ZRs46RxWrTuX5fnqs9eyowYQ0v\",\n        \"balance_transfer_type\": \"fund_user\",\n        \"integrator\": \"tilia-test\",\n        \"account_id\": \"75452177-cad5-42bd-8530-4fb86ecc6fa9\",\n        \"reference_type\": \"RefType\",\n        \"reference_id\": \"RefID\",\n        \"status\": \"EXECUTED\",\n        \"invoice_id\": \"inv_2ZRs42G4xYkrpuVrC7HiryNyPZ6\",\n        \"metadata\": {\n            \"data\": {\n                \"value1\": 1,\n                \"value2\": \"Value2\"\n            },\n            \"reason\": \"goodwill\"\n        },\n        \"failure_reason\": \"\",\n        \"created\": \"2023-12-12T15:47:11.560267Z\",\n        \"updated\": \"2023-12-12T15:47:11.679086Z\"\n    }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payload.status"]}," value of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["EXECUTED"]}," shows that the tokens were transferred successfully."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"get-balance-transfer-invoice","__idx":6},"children":["Get balance transfer invoice"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This exercise recalls the invoice for the balance-transfer transaction."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The preceding exercise recalls information about the transfer, but that information does not"," ","contain the transaction's invoice."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["To get the invoice from a balance transfer, in Postman:"]}]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Explore Tilia transactions"]}," collection, in the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Account credits"]}," folder,"," ","open the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Get a balance transfer invoice"]}," request."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["URL"]}," field, notice the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["balance_transfer_invoice_id"]}," parameter uses the"," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["last_balance_transfer_invoice_id"]}," collection value that was saved in the previous request."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Get a balance transfer invoice"]}," request, choose ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Send"]},"."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After the response returns, open the response ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Body"]}," tab below the request to see the response body details."]}]}]},{"$$mdtype":"Tag","name":"details","attributes":{},"children":[{"$$mdtype":"Tag","name":"summary","attributes":{},"children":["Show a typical response body with the balance-transfer invoice details."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n    \"status\": \"Success\",\n    \"message\": [],\n    \"codes\": [],\n    \"payload\": {\n        \"invoice_id\": \"inv_2c6XrfIoUoAcmLUneRc41WMCh1C\",\n        \"account_id\": \"75452177-cad5-42bd-8530-4fb86ecc6fa9\",\n        \"invoice_type\": \"balance_transfer\",\n        \"reference_type\": \"invoicing.balance_transfer.balance_transfer_id\",\n        \"reference_id\": \"bt_2c6Xre6kmzs3lMIuSlU0tVh7NiV\",\n        \"state\": \"SUCCESS\",\n        \"description\": \"\",\n        \"metadata\": null,\n        \"summary\": {\n            \"total_amount\": 250,\n            \"total_amount_usd\": 250,\n            \"currency\": \"\",\n            \"display_amount\": \"TIL 2.50\",\n            \"subtotal\": {\n                \"total_amount\": 250,\n                \"total_amount_usd\": 250,\n                \"currency\": \"\",\n                \"display_amount\": \"TIL 2.50\"\n            },\n            \"tax\": {\n                \"total_amount\": 0,\n                \"total_amount_usd\": 0,\n                \"currency\": \"\",\n                \"display_amount\": \"\"\n            },\n            \"payment_breakdown\": [],\n            \"tax_calculation\": \"\",\n            \"is_tax_exempt\": false\n        },\n        \"failure_code\": \"\",\n        \"failure_reason\": \"\",\n        \"created\": \"2024-02-08T23:00:01Z\",\n        \"updated\": \"2024-02-08T23:00:01Z\",\n        \"payment_methods\": {},\n        \"line_items\": {\n            \"352f1b0a-e295-4500-97dc-5cd5ae7c69e0\": {\n                \"line_item_id\": \"352f1b0a-e295-4500-97dc-5cd5ae7c69e0\",\n                \"product_sku\": \"\",\n                \"product_code\": \"\",\n                \"amount\": 250,\n                \"currency\": \"TIL\",\n                \"display_amount\": \"TIL 2.50\",\n                \"reference_type\": \"\",\n                \"reference_id\": \"\",\n                \"transaction_type\": \"publisher_sourced\",\n                \"description\": \"\",\n                \"metadata\": null,\n                \"tags\": {},\n                \"sort_order\": 0,\n                \"subitems\": {}\n            }\n        },\n        \"subitems\": {},\n        \"tags\": {}\n    }\n}\n","lang":"json"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This response contains much more information about the transaction than the one from the previous request."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"conclusion","__idx":7},"children":["Conclusion"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The exercises in this tutorial walked you through interactions that award tokens to users"," ","without a purchase transaction."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You might also consider these options for sharing and splitting income from transactions:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/tutorials/use-cases/tutorial_use_case_royalties"},"children":["Royalties"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"#"},"children":["Commissions"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/tutorials/use-cases/tutorial_use_case_patron"},"children":["Patronage"]}]}]}]},"headings":[{"value":"Use-case tutorial: Rewards","id":"use-case-tutorial-rewards","depth":1},{"value":"API operations in this tutorial","id":"api-operations-in-this-tutorial","depth":3},{"value":"To complete this tutorial","id":"to-complete-this-tutorial","depth":2},{"value":"Give rewards to recipient","id":"give-rewards-to-recipient","depth":2},{"value":"Process account-credit balance transfer","id":"process-account-credit-balance-transfer","depth":3},{"value":"Get info about last balance transfer","id":"get-info-about-last-balance-transfer","depth":3},{"value":"Get balance transfer invoice","id":"get-balance-transfer-invoice","depth":3},{"value":"Conclusion","id":"conclusion","depth":2}],"frontmatter":{"seo":{"title":"Use-case tutorial: Rewards"}},"lastModified":"2026-02-05T18:12:30.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/tutorials/use-cases/tutorial_use_case_reward","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}