Billing API

Voximplant billing operates with 2 types of paid services: subscription-based and usage-based.

Subscription-based services cause one-time installation fee (NRC) and periodic (monthly for now) charges on the customer’s account. This includes phone numbers, SIP registrations, MAU packages, etc.

Usage-based services (calls, SMS, speech synthesis, and recognition) are billed immediately after service is provided and their cost depends on the type of service and its quantity.

Currency conversion

Each service has its price in a specific currency (mostly in USD). If the account currency differs from the service currency, the price is converted to the account’s currency according to the current exchange rate.

Pricing API, in general, consists of 2 API functions: GetSubscriptionPrice and GetResourcePrice, but you can use other methods (for example, GetPhoneNumberRegions) to get pricing information for specific resources as well.

Subscriptions price

Although you can use the GetSubscriptionPrice method to list all the subscriptions available, it is more convenient to obtain the rates via phone numbers-related methods. The GetPhoneNumberCategories and GetPhoneNumberRegions methods return information about available number types in each country along with NRC and MRC. You can get information about all countries via a single API call or even request information about all countries at once.

Here is an example of getting phone number rates for Mexico:

# Initialize the Voximplant API client
voxapi = VoximplantAPI("credentials.json")

# Print rates for Mexican numbers (ISO 3166-1 alpha-2 codes are used)
res = voxapi.get_phone_number_categories(country_code="MX")
for category in res["result"][0]["phone_categories"]:
    print(f"{category['phone_category_name']} - NRC: {category['phone_installation_price']}; MRC: {category['phone_price']}")

Usage-based resource price

Use the GetResourcePrice method to obtain information about current rates for usage-based services. If you call the method without any parameters, it returns all Voximplant rates, so the output is quite massive and needs to be filtered to get the required information.

Outgoing phone calls

Voximplant has up to 3 price lists for calls to specific countries: domestic, EEA, and international pricing. Domestic pricing is applied if a call is made from a phone number in some country to a number in the same country.

Here is an example of how to get rates in account currency for domestic outgoing calls for a specific country:

def print_price(price_info):
    print(f"{price_info['price_group_name']} - {price_info['price']}")

def is_eea_country(country_code):
    return country_code in ["AT","BE","BG","HR","CY","CZ","DK","EE","FI","FR","DE","EL","HU","IE","IT","LV","LT","LU","MT","NL","PL","PT","RO","SK","SI","ES","SE","NO","IS","LI"]

def print_rates_for_country(voxapi, country_code):
    found_rates = False
    # Check domestic rates first
    res = voxapi.get_resource_price(resource_type="PSTN_OUT_INCOUNTRY")
    for price in res["result"][0]["price_groups"]:
        if price ["country_code"] == country_code:
            print_price(price)
            found_rates = True
    if found_rates:
        return

    # Rates not found yet. Check if country is in EEA and try to find EEA rates
    if is_eea_country(country_code):
        res = voxapi.get_resource_price(resource_type="PSTNOUT_EEA")
        for price in res["result"][0]["price_groups"]:
            if price ["country_code"] == country_code:
                print_price(price)
                found_rates = True
        if found_rates:
            return

# Fallback to default international rates    
    res = voxapi.get_resource_price(resource_type="PSTN_INTERNATIONAL")
    for price in res["result"][0]["price_groups"]:
        if "country_code" in price and price ["country_code"] == country_code:
            print_price(price)

# Initialize Voximplant API client
voxapi = VoximplantAPI("credentials.json")

# Print rates for calls within Mexico (ISO 3166-1 alpha-2 codes are used)
print_rates_for_country(voxapi, "MX")

Getting international call rates is similar, but you do not need to check the domestic rates, and two country codes have to be analyzed: the source country code to make an EEA/international call, and the destination country code where the call needs to arrive:

def print_price(price_info):
    print(f"{price_info['price_group_name']} - {price_info['price']}")

def is_eea_country(country_code):
    return country_code in ["AT","BE","BG","HR","CY","CZ","DK","EE","FI","FR","DE","EL","HU","IE","IT","LV","LT","LU","MT","NL","PL","PT","RO","SK","SI","ES","SE","NO","IS","LI"]

def print_rates_for_calls(voxapi, from_country, to_country):
    found_rates = False

    # Check if country is in EEA and try to find EEA rates
    if is_eea_country(from_country):
        res = voxapi.get_resource_price(resource_type="PSTNOUT_EEA")
        for price in res["result"][0]["price_groups"]:
            if price ["country_code"] == to_country:
                print_price(price)
                found_rates = True
        if found_rates:
            return

# Fallback to default international rates    
    res = voxapi.get_resource_price(resource_type="PSTN_INTERNATIONAL")
    for price in res["result"][0]["price_groups"]:
        if "country_code" in price and price ["country_code"] == to_country:
            print_price(price)

# Initialize Voximplant API client
voxapi = VoximplantAPI("credentials.json")

# Print rates for calls from Poland to Germany (ISO 3166-1 alpha-2 codes are used)
print_rates_for_calls(voxapi, "PL", "DE")

Incoming phone calls

Incoming calls to phone numbers are charged according to different rate decks. This happens because the toll-free numbers have different pricing globally and rates may vary depending on caller number type (fixed, mobile, etc.).

That is why to get rates for incoming calls to specific number types, information from the GetPhoneNumberCategories and GetResourcePrice methods needs to be combined. The first method returns information about the billing resource (i.e. service type) that needs to be passed to GetResourcePrice to get the corresponding rates.

Here is an example of receiving rates for incoming calls to Colombian toll-free numbers:

def print_price(price_info):
    print(f"{price_info['price_group_name']} - {price_info['price']}")

#Initialize Voximplant API client
voxapi = VoximplantAPI("credentials.json")

# Print rates for calls to Colombian toll-free numbers (ISO 3166-1 alpha-2 codes are used)
res = voxapi.get_phone_number_categories(country_code="CO")
for category in res["result"][0]["phone_categories"]:
    if category["phone_category_name"] == "TOLLFREE":
        resource_name = category["incoming_calls_resource_name"]

# Get rates for specified resource name
        rates_res = voxapi.get_resource_price(resource_type=resource_name)
        for price in rates_res["result"][0]["price_groups"]:
            print_price(price)