Avalara Developer Network Developer blog

AvaTax Communications

Now that you have learned how to make a Sales And Use AvaTax call, you want to extend your ability of making diverse types tax transactions, for example: Telecommunications. The good news is AvaTax is now supporting the Telecoms tax calculation. With a few setups, you can easily use your regular AvaTax account for making Telecoms transactions.

Required setups

There are a few things you need to pre-configure before making a successful AvaTax Communications transaction:

  • Have an AvaTax account subscribed to AvaComms service
  • Have at least one company added to the account
  • Have your company configured with a ClientId (and ClientProfileId) provided by your Communications account manager, by posting a request to our REST API as below:
    CreateCommsConfig - POST /api/v2/companies/{id}/configuration
    [
        {
            "companyId": 12345,
            "category": "AvaCommsConfig",
            "name": "ClientId",
            "value": "536"
        },
        {
            "companyId": 12345,
            "category": "AvaCommsConfig",
            "name": "ClientProfileId",
            "value": "1"
        }
    ]
                            
  • Ready to make a transaction

How to make an AvaTax Communications call

A Communications tax call is largely the same with regular AvaTax calls, with exception of a few extra parameters, as:

  • AvaTax.Communications.TransactionType
  • AvaTax.Communications.ServiceType
  • AvaTax.Communications.Lines
  • AvaTax.Communications.Minutes
  • AvaTax.Communications.CustomerType

For example, a Communications transaction looks something as below:

AvaTax Communications transaction example - POST /api/v2/transactions/create
{
    "type": "SalesInvoice",
    "companyCode": "DEFAULT",
    "date": "2017-05-26",
    "customerCode": "RestSample",
    "purchaseOrderNo": "2017-05-26-001",
    "addresses": {
        "singleLocation": {
            "line1": "8675 W 96th Street Suite 220",
            "city": "Overland Park",
            "region": "KS",
            "country": "US",
            "postalCode": "66212",
        }
    },
    "lines": [
        {
            "number": "1",
            "quantity": 1,
            "amount": 100,
            "taxCode": "P0000000",
            "description": "Yarn",
            "parameters": {
                "AvaTax.Communications.TransactionType": "Cellular",
                "AvaTax.Communications.ServiceType": "Access Charge",
                "AvaTax.Communications.Lines": 10,
                "AvaTax.Communications.Minutes": 60
            }
        }
    ],
    "commit": true,
    "currencyCode": "USD",
    "description": "Yarn",
    "parameters": {
            "AvaTax.Communications.CustomerType": "Business",
            "AvaTax.Communications.BusinessClass": "CLEC",
            "AvaTax.Communications.Sale": true,
             "AvaTax.Communications.ServiceClass": "Primary Long Distance",
    },
    "debugLevel": "Diagnostic"
}
                        

And the calculation response for above request is:

Communications calculation response
{
  "code": "b08190bc-d449-4643-b34c-caf2cf6cfa68",
  "companyId": 0,
  "date": "2017-05-26",
  "paymentDate": "2017-05-26",
  "status": "Temporary",
  "type": "SalesInvoice",
  "currencyCode": "USD",
  "customerVendorCode": "RestSample",
  "reconciled": false,
  "purchaseOrderNo": "2017-05-26-001",
  "totalAmount": 100,
  "totalExempt": 0,
  "totalTax": 22.427061,
  "totalTaxable": 111.032317,
  "totalTaxCalculated": 22.427061,
  "adjustmentReason": "NotAdjusted",
  "locked": false,
  "version": 1,
  "exchangeRateEffectiveDate": "2017-05-26",
  "exchangeRate": 1,
  "isSellerImporterOfRecord": false,
  "description": "Yarn",
  "modifiedDate": "2017-07-24T21:53:30.6139926Z",
  "modifiedUserId": 30581,
  "taxDate": "0001-01-01T00:00:00",
  "lines": [
    {
      "lineNumber": 1,
      "description": "",
      "discountAmount": 0,
      "exemptAmount": 0,
      "exemptCertId": 0,
      "isItemTaxable": true,
      "lineAmount": 111.032317,
      "quantity": 1,
      "reportingDate": "1900-01-01",
      "tax": 22.427061,
      "taxableAmount": 111.032317,
      "taxCalculated": 22.427061,
      "taxCode": "Cellular - Access Charge",
      "taxDate": "2017-07-24",
      "taxIncluded": false,
      "details": [
          {
          "country": "USA",
          "region": "",
          "exemptAmount": 37.1,
          "jurisCode": "",
          "jurisName": "",
          "stateAssignedNo": "",
          "jurisType": "STA",
          "nonTaxableAmount": 37.1,
          "rate": 0.0725,
          "tax": 4.56025,
          "taxableAmount": 62.9,
          "taxType": "Sales",
          "taxName": "CONNECTIVITY CHARGES - Universal Service Fund (Wireless)",
          "taxAuthorityTypeId": 0,
          "taxCalculated": 4.56025,
          "rateType": "General",
          "rateTypeCode": "General"
        },
        {
          "country": "USA",
          "region": "",
          "exemptAmount": 0,
          "jurisCode": "",
          "jurisName": "",
          "stateAssignedNo": "",
          "jurisType": "STA",
          "nonTaxableAmount": 100,
          "rate": 0.6,
          "tax": 0.6,
          "taxableAmount": 0,
          "taxType": "Sales",
          "taxName": "E-911 CHARGES - E911 (Wireless)",
          "taxAuthorityTypeId": 0,
          "taxCalculated": 0.6,
          "rateType": "General",
          "rateTypeCode": "General"
        },
        {
          "country": "USA",
          "region": "",
          "exemptAmount": 0,
          "jurisCode": "",
          "jurisName": "",
          "stateAssignedNo": "",
          "jurisType": "CIT",
          "nonTaxableAmount": -11.032317,
          "rate": 0.01125,
          "tax": 1.249114,
          "taxableAmount": 111.032317,
          "taxType": "Sales",
          "taxName": "SALES AND USE TAXES - Sales Tax",
          "taxAuthorityTypeId": 0,
          "taxCalculated": 1.249114,
          "rateType": "General",
          "rateTypeCode": "General"
        },
        {
          "country": "USA",
          "region": "",
          "exemptAmount": 0,
          "jurisCode": "",
          "jurisName": "",
          "stateAssignedNo": "",
          "jurisType": "CTY",
          "nonTaxableAmount": -11.032317,
          "rate": 0.01475,
          "tax": 1.637727,
          "taxableAmount": 111.032317,
          "taxType": "Sales",
          "taxName": "SALES AND USE TAXES - Sales Tax",
          "taxAuthorityTypeId": 0,
          "taxCalculated": 1.637727,
          "rateType": "General",
          "rateTypeCode": "General"
        },
        {
          "country": "USA",
          "region": "",
          "exemptAmount": 0,
          "jurisCode": "",
          "jurisName": "",
          "stateAssignedNo": "",
          "jurisType": "STA",
          "nonTaxableAmount": -11.032317,
          "rate": 0.065,
          "tax": 7.217101,
          "taxableAmount": 111.032317,
          "taxType": "Sales",
          "taxName": "SALES AND USE TAXES - Sales Tax",
          "taxAuthorityTypeId": 0,
          "taxCalculated": 7.217101,
          "rateType": "General",
          "rateTypeCode": "General"
        },
        {
          "country": "USA",
          "region": "",
          "exemptAmount": 62.9,
          "jurisCode": "",
          "jurisName": "",
          "stateAssignedNo": "",
          "jurisType": "CNT",
          "nonTaxableAmount": 62.9,
          "rate": 0.174,
          "tax": 6.4554,
          "taxableAmount": 37.1,
          "taxType": "Sales",
          "taxName": "CONNECTIVITY CHARGES - Fed USF Cellular",
          "taxAuthorityTypeId": 0,
          "taxCalculated": 6.4554,
          "rateType": "General",
          "rateTypeCode": "General"
        },
        {
          "country": "USA",
          "region": "",
          "exemptAmount": 0,
          "jurisCode": "",
          "jurisName": "",
          "stateAssignedNo": "",
          "jurisType": "CNT",
          "nonTaxableAmount": 0,
          "rate": 0.016667,
          "tax": 0.016667,
          "taxableAmount": 100,
          "taxType": "Sales",
          "taxName": "REGULATORY CHARGES - FCC Regulatory Fee (Wireless)",
          "taxAuthorityTypeId": 0,
          "taxCalculated": 0.016667,
          "rateType": "General",
          "rateTypeCode": "General"
        },
        {
          "country": "USA",
          "region": "",
          "exemptAmount": 62.9,
          "jurisCode": "",
          "jurisName": "",
          "stateAssignedNo": "",
          "jurisType": "CNT",
          "nonTaxableAmount": 62.9,
          "rate": 0.01862,
          "tax": 0.690802,
          "taxableAmount": 37.1,
          "taxType": "Sales",
          "taxName": "CONNECTIVITY CHARGES - Telecommunications Relay Surcharge (Cellular)",
          "taxAuthorityTypeId": 0,
          "taxCalculated": 0.690802,
          "rateType": "General",
          "rateTypeCode": "General"
        }
      ],
       "parameters": {
        "AvaTax.Communications.TransactionType": "Cellular",
        "AvaTax.Communications.ServiceType": "Access Charge",
        "AvaTax.Communications.Lines": "10",
        "AvaTax.Communications.Minutes": "60"
      }
    }
  ],
  "addresses"[],
  "summary"[],
  "parameters": {
    "AvaTax.Communications.CustomerType": "Business",
    "AvaTax.Communications.BusinessClass": "CLEC",
    "AvaTax.Communications.Sale": "true",
    "AvaTax.Communications.ServiceClass": "Primary Long Distance"
  }
}
                        

Note that the “AvaTax.Communications.TransactionType” and “AvaTax.Communications.ServiceType” are two parameters required in order to make a Communications transaction. The other parameters are required or optional depending on distinctive use cases. For example, “AvaTax.Communications.Minutes” and “AvaTax.Communications.Lines” are only required for certain T/S (Transaction/Service) pairs. You can use the /api/v2/communications/tspairs API to look up whether Minutes or Lines are required for the T/S pair your business is operating.

What are allowed T/S pairs and parameters

There are 4 APIs we provided in the REST API suite for you to look up available T/S pairs and parameters:

  • GET /api/v2/communications/tspairs to look up complete list of T/S pairs.
  • GET /api/v2/communications/transactiontypes to look up all transaction types accepted.
  • GET /api/v2/communications/transactiontypes/{id}/servicetypes to look up all service types allowed of a transaction type.
  • GET /api/v2/parameters/parameters to look up all parameters allowed when making a transaction call.

To make your transactions easier

If most of your transactions look the same, with only changes on one or two parameters. You can facilitate your transaction calls by setting the AvaCommsConfig in the way that it records the common parameter values you use. So that they will be used as default values if you don’t explicitly pass them in your transactions. Of course, if you pass a value in your transaction for a parameter already exists in the config, the transaction value always takes priority.

Below is how you configure default parameters. Make sure you pass a valid JSON for the Parameters value. You can always do the same POST operation again to update the default parameters.

Configuring default parameters - POST /api/v2/companies/{id}/configuration
[
    {
        "companyId": 12345,
        "category": "AvaCommsConfig",
        "name": "Parameters",
        "value": "{
            \"AvaTax.Communications.IsPrivateLine\": false,
            \"AvaTax.Communications.PrivateLineSplit\": 0.0,
            \"AvaTax.Communications.CustomerType\": \"Business\",
            \"AvaTax.Communications.BusinessClass\": \"CLEC\",
            \"AvaTax.Communications.Sale\": true,
            \"AvaTax.Communications.ServiceClass\": \"Primary Long Distance\",
            \"AvaTax.Communications.CustomerNumber\": \"RestSample\",
            \"AvaTax.Communications.CompanyIdentifier\": \"TST\",
            \"AvaTax.Communications.AdjustmentMethod\": 0,
            \"AvaTax.Communications.Debit\": false,
            \"AvaTax.Communications.FacilitiesBased\": true,
            \"AvaTax.Communications.Franchise\": true,
            \"AvaTax.Communications.Lifeline\": false,
            \"AvaTax.Communications.Regulated\": true,
            \"AvaTax.Communications.ServiceLevelNumber\": 3456
        }"
    }
]
                        

Back to posts