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:

#{alt_text}

To create a subaccount the following code can be used:

  • cURL

    • Write the code

    Add the following to create-subaccount.sh:

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

    View full source

    Run your code

    Save this file to your machine and run it: 

    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 Nexmo APIs for other Partner’s end customers. The Partner decided to set individual balance and allocate a credit limit to that end customer.

    NOTE: The Partner could have made his accounts prepaid.

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

    #{alt_text}

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

  • cURL

    • Write the code

    Add the following to transfer-credit.sh:

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

    View full source

    Run your code

    Save this file to your machine and run it: 

    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

    • Write the code

    Add the following to get-subaccounts.sh:

    Copy to Clipboard 
    curl -X GET -u $NEXMO_API_KEY:$NEXMO_API_SECRET https://api.nexmo.com/accounts/$NEXMO_API_KEY/subaccounts

    View full source

    Run your code

    Save this file to your machine and run it: 

    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 Nexmo 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 Nexmo 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:

    #{alt_text}

    End of month balance transfers

    At the end of the month the Partner received a |-20| + |-50| = €70 invoice from Nexmo (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:

    #{alt_text}

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

  • cURL

    • Write the code

    Add the following to transfer-balance.sh:

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

    View full source

    Run your code

    Save this file to your machine and run it: 

    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

    • Write the code

    Add the following to suspend-subaccount.sh:

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

    View full source

    Run your code

    Save this file to your machine and run it: 

    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

    • Write the code

    Add the following to reactivate-subaccount.sh:

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

    View full source

    Run your code

    Save this file to your machine and run it: 

    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