Using the Subaccounts API

Overview

This topic describes a use case where a partner uses the Subaccounts API to successfully manage end customers.

Prerequisites

You should be familiar with the main concepts associated with the Subaccounts API.

Creating a subaccount

A Partner decides to create a subaccount for each end customer and is therefore able to use distinct API credentials for each of the end customers and see their spending. This is illustrated in the following diagram:

To create a subaccount the following code can be used:

curl -X POST -u $VONAGE_API_KEY:$VONAGE_API_SECRET https://api.nexmo.com/accounts/$VONAGE_API_KEY/subaccounts  \
     -H "Content-Type: application/json"  \
     -d $'{"name":"'$NEW_SUBACCOUNT_NAME'", "secret":"'$NEW_SUBACCOUNT_SECRET'"}'

bash create-subaccount.sh

Transferring credit

The Partner could not control spending among its end customers because they all shared the same balance. One end customer used to occasionally consume all shared balance effectively blocking access to the Vonage APIs for other Partner’s end customers. The Partner decided to set individual balance and allocate a credit limit to that end customer.

Each subaccount can be allocated an individual balance, and a credit limit, as show in the following diagram:

The following code snippet illustrates allocating a specified amount of credit to a subaccount:

curl -X POST -u $VONAGE_API_KEY:$VONAGE_API_SECRET https://api.nexmo.com/accounts/$VONAGE_API_KEY/credit-transfers  \
     -H "Content-Type: application/json"  \
     -d $'{"from":"'$VONAGE_API_KEY'", "to":"'$SUBACCOUNT_KEY'", "amount": '$AMOUNT'}'

bash transfer-credit.sh

Checking the balance of all subaccounts

The Partner decides to put monitoring in place. It is possible to periodically check the balance of all of subaccounts using the following code snippet:

curl -X GET -u $VONAGE_API_KEY:$VONAGE_API_SECRET https://api.nexmo.com/accounts/$VONAGE_API_KEY/subaccounts

bash get-subaccounts.sh

Additional credit allocation

After some time, the Partner noticed that the end customer 1 (subaccount1) used up all of its credit (40 out of 40) and could not make any more API calls. The Partner had a choice of either waiting for the end customer 1 to pay them (and then in turn making a payment to Vonage and transferring a corresponding balance to the subaccount) or increasing the end customer’s credit limit immediately so that end customer 1 can continue using the Vonage API. The Partner decided to allocate additional credit. The Partner has 40 = |-60| - |-20| available credit, and decides to allocate 20 to the subaccount. This is illustrated in the following diagram:

End of month balance transfers

At the end of the month the Partner received a |-20| + |-50| = €70 invoice from Vonage (for all spending from all its accounts). End customer 1 (subaccount1) covered 45 out of €50 that it had spent. Thus, the Partner transferred €45 to subaccount1's balance. This is illustrated in the following diagram:

The following code shows how to transfer balance to a subaccount:

curl -X POST -u $VONAGE_API_KEY:$VONAGE_API_SECRET https://api.nexmo.com/accounts/$VONAGE_API_KEY/balance-transfers  \
     -H "Content-Type: application/json"  \
     -d $'{"from":"'$VONAGE_API_KEY'", "to":"'$SUBACCOUNT_KEY'", "amount": '$AMOUNT'}'

bash transfer-balance.sh

Suspending a subaccount

The Partner liked the ability to control the spending of the subaccount and decided to assign individual balance and €30 credit to the end customer 2 (subaccount2). The Partner, who was monitoring the spending of its subaccounts spending, noticed that subaccount2 consumed €25 of its balance. Alarmed by subaccount2's spending rate, the Partner decided to temporarily suspend subaccount2. The code to suspend a subaccount is shown here:

curl -X PATCH -u $VONAGE_API_KEY:$VONAGE_API_SECRET https://api.nexmo.com/accounts/$VONAGE_API_KEY/subaccounts/$SUBACCOUNT_KEY  \
     -H "Content-Type: application/json"  \
     -d $'{"suspended":true}'

bash suspend-subaccount.sh

Reactivating a subaccount

After discussions with subaccount2, the Partner decides to reactivate subaccount2's account. This can be achieved using the following code:

curl -X PATCH -u $VONAGE_API_KEY:$VONAGE_API_SECRET https://api.nexmo.com/accounts/$VONAGE_API_KEY/subaccounts/$SUBACCOUNT_KEY  \
     -H "Content-Type: application/json"  \
     -d $'{"suspended":false}'

bash reactivate-subaccount.sh

Summary

In this topic you have seen how to use the Subaccounts API to manage end customers in typical scenarios.

Further resources

• Concepts
• Code Snippets
• API Reference