Chapter 4.2.1 - Bundle File

What is a Bundle file?

Product offerings by Telecommunication companies include grouping of services into a special price for competitive and/or other strategic reasons. The grouping of services is called “bundling.”

Communications REST v2 handles these bundled products through the creation of a Bundle file. Instead of creating a transaction with multiple line items, use a Bundle file with one line item to easily apply a set group (bundle) of products. Taxes calculated for bundled transactions are calculated for each transaction/service defined within the bundle. Brackets and other logic is applied to the transaction as whole rather than individual line items.
The Bundle file is made up of:

  • Assigned Bundle Transaction and Service IDs to be used in a REST v2 transaction
    • Sequential IDs (for example, 20000/20001 for the first bundle and 20000/20002 for the second bundle)
    • Transaction ID and Service ID cannot be changed
  • Transaction/Service pairs
  • Percentage of the sale amount to apply to the particular Transaction/Service pair

There are no limits to the number of Transaction/Service pairs that can be included in a Bundle file. Multiple bundles - up to 200 - can also be created in the same Bundle file (each with their own unique Bundle ID). The percentages must total to 100%.

Creating the Bundle file

The easiest way to create a Bundle file is through the AFC Bundler within the desktop AFC Manager application. Contact your Customer Account Manager (CAM) for more details.
The Bundle file can also be created manually. The file contains a header row containing the Bundler version number and a is a comma-delimited row for each bundle included. Each comma-delimited row contains:

  • Bundle Transaction ID for the bundle to be used in the REST v2 transaction
  • Bundle Service ID for the bundle to be used in the REST v2 transaction
  • Name of the bundle
  • Number of Transaction/Service pairs included in the bundle
  • For each Transaction/Service pair included in the bundle:
    • Transaction ID
    • Service ID
    • Percentage to be applied to this Transaction/Service pair
    • Transaction Type description with the Transaction ID in parenthesis
    • Service Type description with the Transaction ID in parenthesis

Bundle files use a *.bdl file extension.

Sample

For this example, the Bundle file contains 1 bundle (20000/20001) with these Transaction/Service pairs included:

  • 13/6 (Cellular/Access Charge) at 50%
  • 13/11 (Cellular/Activation) at 25%
  • 9/6 (Voice Mail/Access Charge) at 25%
Version,3.0.0
20000,20001,SampleBundle,3,13,6,50,Cellular (13),Access Charge (6),13,11,25,Cellular (13),Activation (11),9,6,25,Voice Mail (9),Access Charge (6)

Pro Tip - Duplicate T/S Pairs

Don’t use the same T/S Pair within a single bundle file. Instead, summarize the percentage as a single entry within the bundle.

Using the Bundle file

The Bundle file is applied to a client profile. You must pass the associated client_profile_id as part of the header to use the Bundle file.
Create a transaction using the Bundle Transaction ID and Bundle Service ID (tran is 20000 and serv is 20001 for this example) and specify the sale amount (chg).

{
  "cmpn": {
    "bscl": 0,
    "svcl": 0,
    "fclt": false,
    "frch": false,
    "reg": false
  },
  "inv": [
    {
      "bill": {
        "cnty": "Johnson",
        "ctry": "USA",
        "int": true,
        "geo": false,
        "city": "Overland Park",
        "st": "KS",
        "zip": "66212"
      },
      "cust": 0,
      "lfln": false,
      "date": "2018-12-01T12:00:00Z",
      "itms": [
        {
          "ref": "Line Item 001 - Bundle File",
          "chg": 100,
          "sale": 1,
          "tran": 20000,
          "serv": 20001
        }
      ],
      "invm": true,
      "dtl": false,
      "summ": true
    }
  ]
}

Note about Bundle File Results

Bundled tax calculations return summarized detailed results (txs) when more than one bundle item returns the same tax type.

Requesting a new client profile or changes to an existing client profile

Contact CommunicationSupport@avalara.com:

  1. Request the customization files and configurations. Attach existing customization files to the email
  2. Include the environment(s)
  3. Include the client_profile_id to be updated if changes are needed to an existing client profile
  4. The client profiles could take up to 8 hours to become available once applied