Skip to main content
Avalara Help Center

Set a transaction-level Safe Harbor Override in REST v1

Use the Safe Harbor Override (SafeHarborOverrides) to apply traffic study federal-level TAM overrides to a {{{{ACTSPR}} v1 tax calculation request. Provide the following information for a Safe Harbor override:

  • Safe Harbor Type (SafeHarborType)
  • Original Federal TAM (OriginalFederalTam)
  • New Federal TAM (NewFederalTam)

The Original and New Federal TAM values are decimals. For example, a 64.9% Federal TAM value is entered as "0.649".  The State TAM is calculated automatically (State TAM = 1.0 - Federal TAM).

We recommend using a client profile with a custom configuration applied even though a calculate tax or adjustment call gives you the flexibility to input Safe Harbor Override information for each transaction.  This results in better performance from the AFC Tax Engine because your override settings are cached before tax calculation begins.

Steps

  1. Connect to the Communications Customer Portal REST v1 instance via Swagger or through your custom integration.
  2. Set the request header.
  3. Select the appropriate endpoint.  For example, use /api/v1/CalculateTaxes.
  4. Set the request body to this example.  The VoIP safe harbor type (SafeHarborType) is being overridden from the original Federal TAM (OriginalFederalTam) of 0.649 (64.9%) to your calculated Federal TAM (NewFederalTam) of 0.250 (25%).
    {
     "OriginationAddress": {
        "CountryISO": "USA",
        "County": "San Francisco",
        "Locality": "San Francisco",
        "State": "CA",
        "ZipCode": "94102"
      },
     "TerminationAddress": {
        "CountryISO": "USA",
        "County": "San Francisco",
        "Locality": "San Francisco",
        "State": "CA",
        "ZipCode": "94102"
      },
     "BillToAddress": {
        "CountryISO": "USA",
        "County": "San Francisco",
        "Locality": "San Francisco",
        "State": "CA",
        "ZipCode": "94102"
      },
      "CustomerType": 0,
      "BusinessClass": 0,
      "Sale": true,
      "TransactionType": 19,
      "ServiceType": 6,
      "ServiceClass": 0,
      "Date": "2018-04-01T12:00:00Z",
      "Charge": 100,
      "Incorporated": true,
      "CompanyIdentifier": "TEST",
      "Lines": 0,
      "Debit": false,
      "FacilitiesBased": false,
      "Franchise": false,
      "Lifeline": false,
      "Regulated": false,
      "OptionalFields": [
        {
          "OptionalKeyNo": 1,
          "OptionalValue": "VoIP Sample transaction with TAM Traffic Study Override"
        }
      ],
      "TaxInclusive": false,
      "SafeHarborOverrides": [
        {
          "SafeHarborType": 2,
          "OriginalFederalTam": 0.649,
          "NewFederalTam": 0.250
        }
      ],
      "DocumentCode": "TEST VOIP INVOICE",
      "Commit": false
    }
    
  5. Execute the request.

Result

The result of the Safe Harbor override can be seen on Federal-level (TaxLevel 0) Tax Types (TaxType) 162 and 226:

  • Taxable Measure (TaxableMeasure) is 25 based on the requested 100 charge (Taxable Measure is 64.90 without the Safe Harbor override)
  • Exempt Sale Amount (ExemptSaleAmount) is 75 based on the requested 100 charge (Exempt Sale Amount is 35.10 without the Safe Harbor override)

State taxes are automatically updated based on the Federal override. The State level (TaxLevel 1) TAM is 75% (1.0 - new Federal TAM) and can be seen on Tax Types (TaxType) 161, 217, 450, 452, 453, 454:

  • Taxable Measure (TaxableMeasure) is 75 based on the requested 100 charge (Taxable Measure is 35.10 without the Safe Harbor override)
  • Exempt Sale Amount (ExemptSaleAmount) is 25 based on the requested 100 charge (Exempt Sale Amount is 64.9 without the Safe Harbor override)
[
  {
    "AdjustmentType": 0,
    "Billable": true,
    "CalculationType": 1,
    "CategoryDescription": "CONNECTIVITY CHARGES",
    "CategoryID": 5,
    "CompanyIdentifier": "TEST",
    "Compliance": true,
    "CustomerNumber": "",
    "Description": "Universal Lifeline Telephone Service Charge (VoIP)",
    "ExemptionType": 0,
    "ExemptSaleAmount": 25,
    "InvoiceNumber": 0,
    "Optional": 0,
    "OptionalAlpha1": "",
    "Optional4": 0,
    "Optional5": 0,
    "Optional6": 0,
    "Optional7": 0,
    "Optional8": 0,
    "Optional9": 0,
    "Optional10": 0,
    "PCode": 253500,
    "Rate": 0.0475,
    "RefundUncollect": 0,
    "ServiceLevelNumber": 0,
    "Surcharge": true,
    "TaxableMeasure": 75,
    "TaxAmount": 3.5625,
    "TaxLevel": 1,
    "TaxType": 454,
    "Lines": 0,
    "Minutes": 0,
    "OptionalFields": [
      {
        "OptionalKeyNo": 1,
        "OptionalValue": "VoIP Sample transaction with TAM Traffic Study Override"
      }
    ],
    "TransCharge": 100
  },
  {
    "AdjustmentType": 0,
    "Billable": true,
    "CalculationType": 1,
    "CategoryDescription": "CONNECTIVITY CHARGES",
    "CategoryID": 5,
    "CompanyIdentifier": "TEST",
    "Compliance": true,
    "CustomerNumber": "",
    "Description": "CASF (VoIP)",
    "ExemptionType": 0,
    "ExemptSaleAmount": 25,
    "InvoiceNumber": 0,
    "Optional": 0,
    "OptionalAlpha1": "",
    "Optional4": 0,
    "Optional5": 0,
    "Optional6": 0,
    "Optional7": 0,
    "Optional8": 0,
    "Optional9": 0,
    "Optional10": 0,
    "PCode": 253500,
    "Rate": 0.0056,
    "RefundUncollect": 0,
    "ServiceLevelNumber": 0,
    "Surcharge": true,
    "TaxableMeasure": 75,
    "TaxAmount": 0.42,
    "TaxLevel": 1,
    "TaxType": 453,
    "Lines": 0,
    "Minutes": 0,
    "OptionalFields": [
      {
        "OptionalKeyNo": 1,
        "OptionalValue": "VoIP Sample transaction with TAM Traffic Study Override"
      }
    ],
    "TransCharge": 100
  },
  {
    "AdjustmentType": 0,
    "Billable": true,
    "CalculationType": 1,
    "CategoryDescription": "CONNECTIVITY CHARGES",
    "CategoryID": 5,
    "CompanyIdentifier": "TEST",
    "Compliance": true,
    "CustomerNumber": "",
    "Description": "CA Teleconnect Fund (VoIP)",
    "ExemptionType": 0,
    "ExemptSaleAmount": 25,
    "InvoiceNumber": 0,
    "Optional": 0,
    "OptionalAlpha1": "",
    "Optional4": 0,
    "Optional5": 0,
    "Optional6": 0,
    "Optional7": 0,
    "Optional8": 0,
    "Optional9": 0,
    "Optional10": 0,
    "PCode": 253500,
    "Rate": 0.0108,
    "RefundUncollect": 0,
    "ServiceLevelNumber": 0,
    "Surcharge": true,
    "TaxableMeasure": 75,
    "TaxAmount": 0.81,
    "TaxLevel": 1,
    "TaxType": 452,
    "Lines": 0,
    "Minutes": 0,
    "OptionalFields": [
      {
        "OptionalKeyNo": 1,
        "OptionalValue": "VoIP Sample transaction with TAM Traffic Study Override"
      }
    ],
    "TransCharge": 100
  },
  {
    "AdjustmentType": 0,
    "Billable": true,
    "CalculationType": 1,
    "CategoryDescription": "CONNECTIVITY CHARGES",
    "CategoryID": 5,
    "CompanyIdentifier": "TEST",
    "Compliance": true,
    "CustomerNumber": "",
    "Description": "CA High Cost Fund A (VoIP)",
    "ExemptionType": 0,
    "ExemptSaleAmount": 25,
    "InvoiceNumber": 0,
    "Optional": 0,
    "OptionalAlpha1": "",
    "Optional4": 0,
    "Optional5": 0,
    "Optional6": 0,
    "Optional7": 0,
    "Optional8": 0,
    "Optional9": 0,
    "Optional10": 0,
    "PCode": 253500,
    "Rate": 0.0035,
    "RefundUncollect": 0,
    "ServiceLevelNumber": 0,
    "Surcharge": true,
    "TaxableMeasure": 75,
    "TaxAmount": 0.2625,
    "TaxLevel": 1,
    "TaxType": 450,
    "Lines": 0,
    "Minutes": 0,
    "OptionalFields": [
      {
        "OptionalKeyNo": 1,
        "OptionalValue": "VoIP Sample transaction with TAM Traffic Study Override"
      }
    ],
    "TransCharge": 100
  },
  {
    "AdjustmentType": 0,
    "Billable": true,
    "CalculationType": 1,
    "CategoryDescription": "CONNECTIVITY CHARGES",
    "CategoryID": 5,
    "CompanyIdentifier": "TEST",
    "Compliance": true,
    "CustomerNumber": "",
    "Description": "TRS (VoIP)",
    "ExemptionType": 0,
    "ExemptSaleAmount": 25,
    "InvoiceNumber": 0,
    "Optional": 0,
    "OptionalAlpha1": "",
    "Optional4": 0,
    "Optional5": 0,
    "Optional6": 0,
    "Optional7": 0,
    "Optional8": 0,
    "Optional9": 0,
    "Optional10": 0,
    "PCode": 253500,
    "Rate": 0.005,
    "RefundUncollect": 0,
    "ServiceLevelNumber": 0,
    "Surcharge": true,
    "TaxableMeasure": 75,
    "TaxAmount": 0.375,
    "TaxLevel": 1,
    "TaxType": 217,
    "Lines": 0,
    "Minutes": 0,
    "OptionalFields": [
      {
        "OptionalKeyNo": 1,
        "OptionalValue": "VoIP Sample transaction with TAM Traffic Study Override"
      }
    ],
    "TransCharge": 100
  },
  {
    "AdjustmentType": 0,
    "Billable": true,
    "CalculationType": 1,
    "CategoryDescription": "E-911 CHARGES",
    "CategoryID": 7,
    "CompanyIdentifier": "TEST",
    "Compliance": true,
    "CustomerNumber": "",
    "Description": "E911 (VoIP)",
    "ExemptionType": 0,
    "ExemptSaleAmount": 25,
    "InvoiceNumber": 0,
    "Optional": 0,
    "OptionalAlpha1": "",
    "Optional4": 0,
    "Optional5": 0,
    "Optional6": 0,
    "Optional7": 0,
    "Optional8": 0,
    "Optional9": 0,
    "Optional10": 0,
    "PCode": 253500,
    "Rate": 0.0075,
    "RefundUncollect": 0,
    "ServiceLevelNumber": 0,
    "Surcharge": false,
    "TaxableMeasure": 75,
    "TaxAmount": 0.5625,
    "TaxLevel": 1,
    "TaxType": 161,
    "Lines": 0,
    "Minutes": 0,
    "OptionalFields": [
      {
        "OptionalKeyNo": 1,
        "OptionalValue": "VoIP Sample transaction with TAM Traffic Study Override"
      }
    ],
    "TransCharge": 100
  },
  {
    "AdjustmentType": 0,
    "Billable": true,
    "CalculationType": 1,
    "CategoryDescription": "CONNECTIVITY CHARGES",
    "CategoryID": 5,
    "CompanyIdentifier": "TEST",
    "Compliance": true,
    "CustomerNumber": "",
    "Description": "FUSF (VoIP)",
    "ExemptionType": 0,
    "ExemptSaleAmount": 75,
    "InvoiceNumber": 0,
    "Optional": 0,
    "OptionalAlpha1": "",
    "Optional4": 0,
    "Optional5": 0,
    "Optional6": 0,
    "Optional7": 0,
    "Optional8": 0,
    "Optional9": 0,
    "Optional10": 0,
    "PCode": 0,
    "Rate": 0.184,
    "RefundUncollect": 0,
    "ServiceLevelNumber": 0,
    "Surcharge": false,
    "TaxableMeasure": 25,
    "TaxAmount": 4.6,
    "TaxLevel": 0,
    "TaxType": 162,
    "Lines": 0,
    "Minutes": 0,
    "OptionalFields": [
      {
        "OptionalKeyNo": 1,
        "OptionalValue": "VoIP Sample transaction with TAM Traffic Study Override"
      }
    ],
    "TransCharge": 100
  },
  {
    "AdjustmentType": 0,
    "Billable": true,
    "CalculationType": 1,
    "CategoryDescription": "REGULATORY CHARGES",
    "CategoryID": 6,
    "CompanyIdentifier": "TEST",
    "Compliance": true,
    "CustomerNumber": "",
    "Description": "FCC Regulatory Fee (VoIP)",
    "ExemptionType": 0,
    "ExemptSaleAmount": 75,
    "InvoiceNumber": 0,
    "Optional": 0,
    "OptionalAlpha1": "",
    "Optional4": 0,
    "Optional5": 0,
    "Optional6": 0,
    "Optional7": 0,
    "Optional8": 0,
    "Optional9": 0,
    "Optional10": 0,
    "PCode": 0,
    "Rate": 0.00291,
    "RefundUncollect": 0,
    "ServiceLevelNumber": 0,
    "Surcharge": false,
    "TaxableMeasure": 25,
    "TaxAmount": 0.07275,
    "TaxLevel": 0,
    "TaxType": 226,
    "Lines": 0,
    "Minutes": 0,
    "OptionalFields": [
      {
        "OptionalKeyNo": 1,
        "OptionalValue": "VoIP Sample transaction with TAM Traffic Study Override"
      }
    ],
    "TransCharge": 100
  }
] 
  • Was this article helpful?