Use-case tutorial: Royalties and commissions

In this tutorial, you demonstrate the interactions that support paying creators of digital goods a royalty for purchases in your marketplace. While this example focuses on the payment of royalties to a creator, the transaction model used in this example can be extended to support many different types of payments. For example, the same process described here can also be used for the payment of commissions, payment to multiple creators, and so on.

Allow about 20 minutes to complete this tutorial.

The following illustration shows how a multi-recipient invoice can be used to pay multiple users in one transaction.

To pay creators a royalty, you divide the transaction value between the creator, or creators, and the seller when you create the invoice. This tutorial demonstrates such a transaction in the context of a marketplace, such as the one used in the Marketplace use-case tutorial.

API operations in this tutorial

To complete this tutorial

This tutorial uses the _Manage user accounts and Explore Tilia transactions collections 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. 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. 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.

Identify the users in the transaction

To demonstrate transactions with royalties, your market must have users in these roles:

• Payer : The user who makes the purchase and pays the invoice. This user receives the good or service being sold.
• Recipient : The user who offers the goods or services for sale in the marketplace. This user is the seller who receives the funds from the sale, less the royalty paid to the Creator .
• Creator : The user who created the good or service for sale in the marketplace. This user receives the royalty from the sale.

These users are created in the User account tutorials. If you recently completed the User account tutorials, you can review those exercises, or continue directly to the next exercise in this tutorial.

If you haven't created these users, or you don't remember their usernames, you can create new users by running the User account tutorials.

When you're ready, continue to the next exercise.

Buy digital goods from another user

In this exercise, you create the transaction that splits the proceeds of the sale between the recipient and the creator. To do this, you create an invoice in which the objects in the line_items array have multiple objects in the recipients array.

In another window, open the Make standard transactions with royalties tutorial to process the transaction with royalties, and then return to continue in this topic. While you are in that tutorial, pay close attention to the recipients property of the line_items in the invoice.

View the transaction details

After completing the previous transaction, you can look at the transaction details to see the record of the transaction.

In another window, open Get transaction details (API) and follow the To use the Tilia API to get the details of the most recent standard transaction procedure to see how the proceeds from the sale were split between the recipient and the creator.

You can also view how the transaction appears to each of the users involved by reviewing the transaction history of each user in the UI simulator. Repeat the procedure described in Get user's transaction history (UI) for each user. From the transaction history UI, you can select a transaction from the list to see its details.

Conclusion

The exercises in this tutorial walked you through the interactions that pay a royalty to a creator during a sale.

You might also enhance your marketplace by considering these features:

• Commissions
• Patronage