# Chapter 4.3.16 - Optional Fields

Source: https://developer.avalara.com/products/communications/integration-guides/dev-guide_rest_v2/customizing-transactions/sample-transactions/optional-fields/

-   [Previous](/communications/dev-guide_rest_v2/customizing-transactions/sample-transactions/invoice-mode/)
-   [Next](/communications/dev-guide_rest_v2/customizing-transactions/sample-transactions/adjustment/)

The Optional Fields object (`opt`) is a [Key/Value Pair](/communications/dev-guide_rest_v2/reference/key-value-pair/) that allows you to include up to 10 custom fields for use in Reporting. The Optional Fields are not returned as part of the [`CalcTaxes` response](/communications/dev-guide_rest_v2/reference/calc-taxes-response/), but Optional Field 1 - Optional Field 10 can be included on reports generated in the [Customer Portal](https://communications.avalara.net).

Optional Fields can be used in both the [Invoice](/communications/dev-guide_rest_v2/reference/invoice/) and the [Line Item](/communications/dev-guide_rest_v2/reference/line-item/). The 10 available [Key/Value pairs](/communications/dev-guide_rest_v2/reference/key-value-pair/) can be spread across both the invoice and each line item individually. [For example](#example):

-   The **transaction** contains 1 Invoice and 5 LineItem objects
-   The **Invoice** object contains Optional Fields keys 1 through 5
-   Each **LineItem** object contains:

-   LineItem 001 contains Optional Fields keys 6 through 10
-   LineItem 002 contains Optional Fields keys 8 and 9
-   LineItem 003 contains Optional Field key 7 only
-   LineItem 004 contains Optional Fields keys 6 through 10
-   LineItem 005 contains Optional Fields keys 7, 9, and 10

The Optional Fields at the **Invoice** level are applied to all Line Items.

To use the Optional Fields:

-   Set the Key (`key`) to a number between 1 and 10
    -   Each key/value pair must have a unique key
-   Add the custom value for the specified key in Value (`val`)

#### Notes

1.  The Optional Field value field (`val`) does not need to be the same across all Line Items even if the Key (`key`) is the same
2.  The distribution of the Optional Field key/value pairs (`opt`) is not mandated by REST v2, but it is **recommended** to set Keys 1-5 on the [Invoice](/communications/dev-guide_rest_v2/reference/invoice/) and Keys 5-10 on the [LineItem](/communications/dev-guide_rest_v2/reference/line-item/)

### Optional Fields Example

This example demonstrates using Optional Fields on both the [Invoice](/communications/dev-guide_rest_v2/reference/invoice/) and the [LineItems](/communications/dev-guide_rest_v2/reference/line-item/).

```json
{ "cmpn": { "bscl": 0, "svcl": 0, "fclt": false, "frch": false, "reg": false }, "inv": [ { "doc": "OPTIONAL FIELDS EXAMPLE", "cmmt": false, "bill": { "cnty": "San Francisco", "ctry": "USA", "int": true, "geo": false, "city": "San Francisco", "st": "CA", "zip": "94102" }, "cust": 0, "lfln": false, "date": "2017-05-01T12:00:00Z", "itms": [ { "ref": "Line Item 001", "chg": 100, "line": 0, "sale": 1, "incl": false, "tran": 19, "serv": 6, "dbt": false, "adj": false, "opt": [ { "key": "6", "val": "LineItem Value 6" }, { "key": "7", "val": "LineItem Value 7" }, { "key": "8", "val": "LineItem Value 8" }, { "key": "9", "val": "LineItem Value 9" }, { "key": "10", "val": "LineItem Value 10" } ] }, { "ref": "Line Item 002", "chg": 0, "line": 10, "sale": 1, "incl": false, "tran": 19, "serv": 21, "dbt": false, "adj": false, "opt": [ { "key": "8", "val": "LineItem Value 8" }, { "key": "9", "val": "LineItem 002 Value 9 (different from Key 9 in LineItem 001)" } ] }, { "ref": "Line Item 003", "chg": 25, "line": 0, "sale": 1, "incl": false, "tran": 19, "serv": 37, "dbt": false, "adj": false, "opt": [ { "key": "7", "val": "LineItem Value 7" } ] }, { "ref": "Line Item 004", "chg": 125, "line": 0, "sale": 1, "incl": false, "tran": 19, "serv": 6, "dbt": false, "adj": false, "opt": [ { "key": "6", "val": "LineItem Value 6" }, { "key": "7", "val": "LineItem Value 7" }, { "key": "8", "val": "LineItem Value 8" }, { "key": "9", "val": "LineItem Value 9" }, { "key": "10", "val": "LineItem Value 10" } ] }, { "ref": "Line Item 005", "chg": 250, "line": 0, "sale": 1, "incl": false, "tran": 19, "serv": 6, "dbt": false, "adj": false, "opt": [ { "key": "7", "val": "Unique Value for LineItem 005 - Key 7" }, { "key": "9", "val": "LineItem Value 9" }, { "key": "10", "val": "LineItem Value 10" } ] } ], "invm": true, "dtl": true, "summ": true, "opt": [ { "key": "1", "val": "Invoice Value 1" }, { "key": "2", "val": "Invoice Value 2" }, { "key": "3", "val": "Invoice Value 3" }, { "key": "4", "val": "Invoice Value 4" }, { "key": "5", "val": "Invoice Value 5" } ] } ]}
```

#### Response

Taxes (`txs` and `summ`) are returned as normal. No Optional Fields (`opt`) are returned in the [`CalcTaxes` response](/communications/dev-guide_rest_v2/reference/calc-taxes-response/).

[View the Response JSON](#collapse1)

```json
{ "inv": [ { "doc": "OPTIONAL FIELDS EXAMPLE", "itms": [ { "ref": "Line Item 001", "txs": [ { "bill": true, "cmpl": true, "tm": 35.099999999999994, "calc": 1, "cat": "CONNECTIVITY CHARGES", "cid": 5, "name": "Universal Lifeline Telephone Service Charge (VoIP)", "exm": 64.9, "lns": 0, "min": 0, "pcd": 253500, "rate": 0.0475, "sur": true, "tax": 1.6672499999999997, "lvl": 1, "tid": 454 }, { "bill": true, "cmpl": true, "tm": 35.099999999999994, "calc": 1, "cat": "CONNECTIVITY CHARGES", "cid": 5, "name": "CA Teleconnect Fund (VoIP)", "exm": 64.9, "lns": 0, "min": 0, "pcd": 253500, "rate": 0.0108, "sur": true, "tax": 0.37908, "lvl": 1, "tid": 452 }, { "bill": true, "cmpl": true, "tm": 35.099999999999994, "calc": 1, "cat": "CONNECTIVITY CHARGES", "cid": 5, "name": "CA High Cost Fund A (VoIP)", "exm": 64.9, "lns": 0, "min": 0, "pcd": 253500, "rate": 0.0035, "sur": true, "tax": 0.12284999999999999, "lvl": 1, "tid": 450 }, { "bill": true, "cmpl": true, "tm": 35.099999999999994, "calc": 1, "cat": "CONNECTIVITY CHARGES", "cid": 5, "name": "TRS (VoIP)", "exm": 64.9, "lns": 0, "min": 0, "pcd": 253500, "rate": 0.005, "sur": true, "tax": 0.17549999999999996, "lvl": 1, "tid": 217 }, { "bill": true, "cmpl": true, "tm": 35.099999999999994, "calc": 1, "cat": "E-911 CHARGES", "cid": 7, "name": "E911 (VoIP)", "exm": 64.9, "lns": 0, "min": 0, "pcd": 253500, "rate": 0.0075, "sur": false, "tax": 0.26324999999999993, "lvl": 1, "tid": 161 }, { "bill": true, "cmpl": true, "tm": 64.9, "calc": 1, "cat": "CONNECTIVITY CHARGES", "cid": 5, "name": "FUSF (VoIP)", "exm": 35.099999999999994, "lns": 0, "min": 0, "pcd": 0, "rate": 0.174, "sur": false, "tax": 11.2926, "lvl": 0, "tid": 162 }, { "bill": true, "cmpl": true, "tm": 64.9, "calc": 1, "cat": "REGULATORY CHARGES", "cid": 6, "name": "FCC Regulatory Fee (VoIP)", "exm": 35.099999999999994, "lns": 0, "min": 0, "pcd": 0, "rate": 0.00302, "sur": false, "tax": 0.19599800000000003, "lvl": 0, "tid": 226 } ] }, { "ref": "Line Item 002", "txs": [ { "bill": true, "cmpl": true, "tm": 0, "calc": 4, "cat": "E-911 CHARGES", "cid": 7, "name": "San Francisco Access line Tax (VoIP)", "exm": 0, "lns": 10, "min": 0, "pcd": 377300, "rate": 3.27, "sur": false, "tax": 32.7, "lvl": 3, "tid": 250 } ] }, { "ref": "Line Item 003", "txs": [ { "bill": true, "cmpl": true, "tm": 25, "calc": 1, "cat": "SALES AND USE TAXES", "cid": 1, "name": "District Tax", "exm": 0, "lns": 0, "min": 0, "pcd": 377200, "rate": 0.0125, "sur": false, "tax": 0.3125, "lvl": 2, "tid": 4 }, { "bill": true, "cmpl": true, "tm": 25, "calc": 1, "cat": "SALES AND USE TAXES", "cid": 1, "name": "Sales Tax", "exm": 0, "lns": 0, "min": 0, "pcd": 377300, "rate": 0.0125, "sur": false, "tax": 0.3125, "lvl": 2, "tid": 1 }, { "bill": true, "cmpl": true, "tm": 25, "calc": 1, "cat": "SALES AND USE TAXES", "cid": 1, "name": "Sales Tax", "exm": 0, "lns": 0, "min": 0, "pcd": 377300, "rate": 0.06, "sur": false, "tax": 1.5, "lvl": 1, "tid": 1 } ] }, { "ref": "Line Item 004", "txs": [ { "bill": true, "cmpl": true, "tm": 43.875, "calc": 1, "cat": "CONNECTIVITY CHARGES", "cid": 5, "name": "Universal Lifeline Telephone Service Charge (VoIP)", "exm": 81.125, "lns": 0, "min": 0, "pcd": 253500, "rate": 0.0475, "sur": true, "tax": 2.0840625, "lvl": 1, "tid": 454 }, { "bill": true, "cmpl": true, "tm": 43.875, "calc": 1, "cat": "CONNECTIVITY CHARGES", "cid": 5, "name": "CA Teleconnect Fund (VoIP)", "exm": 81.125, "lns": 0, "min": 0, "pcd": 253500, "rate": 0.0108, "sur": true, "tax": 0.47385000000000005, "lvl": 1, "tid": 452 }, { "bill": true, "cmpl": true, "tm": 43.875, "calc": 1, "cat": "CONNECTIVITY CHARGES", "cid": 5, "name": "CA High Cost Fund A (VoIP)", "exm": 81.125, "lns": 0, "min": 0, "pcd": 253500, "rate": 0.0035, "sur": true, "tax": 0.1535625, "lvl": 1, "tid": 450 }, { "bill": true, "cmpl": true, "tm": 43.875, "calc": 1, "cat": "CONNECTIVITY CHARGES", "cid": 5, "name": "TRS (VoIP)", "exm": 81.125, "lns": 0, "min": 0, "pcd": 253500, "rate": 0.005, "sur": true, "tax": 0.21937500000000001, "lvl": 1, "tid": 217 }, { "bill": true, "cmpl": true, "tm": 43.875, "calc": 1, "cat": "E-911 CHARGES", "cid": 7, "name": "E911 (VoIP)", "exm": 81.125, "lns": 0, "min": 0, "pcd": 253500, "rate": 0.0075, "sur": false, "tax": 0.3290625, "lvl": 1, "tid": 161 }, { "bill": true, "cmpl": true, "tm": 81.125, "calc": 1, "cat": "CONNECTIVITY CHARGES", "cid": 5, "name": "FUSF (VoIP)", "exm": 43.875, "lns": 0, "min": 0, "pcd": 0, "rate": 0.174, "sur": false, "tax": 14.115749999999998, "lvl": 0, "tid": 162 }, { "bill": true, "cmpl": true, "tm": 81.125, "calc": 1, "cat": "REGULATORY CHARGES", "cid": 6, "name": "FCC Regulatory Fee (VoIP)", "exm": 43.875, "lns": 0, "min": 0, "pcd": 0, "rate": 0.00302, "sur": false, "tax": 0.2449975, "lvl": 0, "tid": 226 } ] }, { "ref": "Line Item 005", "txs": [ { "bill": true, "cmpl": true, "tm": 87.75, "calc": 1, "cat": "CONNECTIVITY CHARGES", "cid": 5, "name": "Universal Lifeline Telephone Service Charge (VoIP)", "exm": 162.25, "lns": 0, "min": 0, "pcd": 253500, "rate": 0.0475, "sur": true, "tax": 4.168125, "lvl": 1, "tid": 454 }, { "bill": true, "cmpl": true, "tm": 87.75, "calc": 1, "cat": "CONNECTIVITY CHARGES", "cid": 5, "name": "CA Teleconnect Fund (VoIP)", "exm": 162.25, "lns": 0, "min": 0, "pcd": 253500, "rate": 0.0108, "sur": true, "tax": 0.9477000000000001, "lvl": 1, "tid": 452 }, { "bill": true, "cmpl": true, "tm": 87.75, "calc": 1, "cat": "CONNECTIVITY CHARGES", "cid": 5, "name": "CA High Cost Fund A (VoIP)", "exm": 162.25, "lns": 0, "min": 0, "pcd": 253500, "rate": 0.0035, "sur": true, "tax": 0.307125, "lvl": 1, "tid": 450 }, { "bill": true, "cmpl": true, "tm": 87.75, "calc": 1, "cat": "CONNECTIVITY CHARGES", "cid": 5, "name": "TRS (VoIP)", "exm": 162.25, "lns": 0, "min": 0, "pcd": 253500, "rate": 0.005, "sur": true, "tax": 0.43875000000000003, "lvl": 1, "tid": 217 }, { "bill": true, "cmpl": true, "tm": 87.75, "calc": 1, "cat": "E-911 CHARGES", "cid": 7, "name": "E911 (VoIP)", "exm": 162.25, "lns": 0, "min": 0, "pcd": 253500, "rate": 0.0075, "sur": false, "tax": 0.658125, "lvl": 1, "tid": 161 }, { "bill": true, "cmpl": true, "tm": 162.25, "calc": 1, "cat": "CONNECTIVITY CHARGES", "cid": 5, "name": "FUSF (VoIP)", "exm": 87.75, "lns": 0, "min": 0, "pcd": 0, "rate": 0.174, "sur": false, "tax": 28.231499999999997, "lvl": 0, "tid": 162 }, { "bill": true, "cmpl": true, "tm": 162.25, "calc": 1, "cat": "REGULATORY CHARGES", "cid": 6, "name": "FCC Regulatory Fee (VoIP)", "exm": 87.75, "lns": 0, "min": 0, "pcd": 0, "rate": 0.00302, "sur": false, "tax": 0.489995, "lvl": 0, "tid": 226 } ] } ], "summ": [ { "max": 2147483647, "min": 0, "tchg": 166.725, "calc": 1, "cat": "CONNECTIVITY CHARGES", "cid": 5, "name": "Universal Lifeline Telephone Service Charge (VoIP)", "exm": 308.275, "lns": 0, "pcd": 253500, "rate": 0.0475, "sur": true, "tax": 7.919437499999999, "lvl": 1, "tid": 454 }, { "max": 2147483647, "min": 0, "tchg": 166.725, "calc": 1, "cat": "CONNECTIVITY CHARGES", "cid": 5, "name": "CA Teleconnect Fund (VoIP)", "exm": 308.275, "lns": 0, "pcd": 253500, "rate": 0.0108, "sur": true, "tax": 1.80063, "lvl": 1, "tid": 452 }, { "max": 2147483647, "min": 0, "tchg": 166.725, "calc": 1, "cat": "CONNECTIVITY CHARGES", "cid": 5, "name": "CA High Cost Fund A (VoIP)", "exm": 308.275, "lns": 0, "pcd": 253500, "rate": 0.0035, "sur": true, "tax": 0.5835374999999999, "lvl": 1, "tid": 450 }, { "max": 2147483647, "min": 0, "tchg": 166.725, "calc": 1, "cat": "CONNECTIVITY CHARGES", "cid": 5, "name": "TRS (VoIP)", "exm": 308.275, "lns": 0, "pcd": 253500, "rate": 0.005, "sur": true, "tax": 0.8336250000000001, "lvl": 1, "tid": 217 }, { "max": 2147483647, "min": 0, "tchg": 166.725, "calc": 1, "cat": "E-911 CHARGES", "cid": 7, "name": "E911 (VoIP)", "exm": 308.275, "lns": 0, "pcd": 253500, "rate": 0.0075, "sur": false, "tax": 1.2504374999999999, "lvl": 1, "tid": 161 }, { "max": 2147483647, "min": 0, "tchg": 308.275, "calc": 1, "cat": "CONNECTIVITY CHARGES", "cid": 5, "name": "FUSF (VoIP)", "exm": 166.725, "lns": 0, "pcd": 0, "rate": 0.174, "sur": false, "tax": 53.639849999999996, "lvl": 0, "tid": 162 }, { "max": 2147483647, "min": 0, "tchg": 308.275, "calc": 1, "cat": "REGULATORY CHARGES", "cid": 6, "name": "FCC Regulatory Fee (VoIP)", "exm": 166.725, "lns": 0, "pcd": 0, "rate": 0.00302, "sur": false, "tax": 0.9309905, "lvl": 0, "tid": 226 }, { "max": 2147483647, "min": 0, "tchg": 0, "calc": 4, "cat": "E-911 CHARGES", "cid": 7, "name": "San Francisco Access line Tax (VoIP)", "exm": 0, "lns": 10, "pcd": 377300, "rate": 3.27, "sur": false, "tax": 32.7, "lvl": 3, "tid": 250 }, { "max": 2147483647, "min": 0, "tchg": 25, "calc": 1, "cat": "SALES AND USE TAXES", "cid": 1, "name": "District Tax", "exm": 0, "lns": 0, "pcd": 377200, "rate": 0.0125, "sur": false, "tax": 0.3125, "lvl": 2, "tid": 4 }, { "max": 2147483647, "min": 0, "tchg": 25, "calc": 1, "cat": "SALES AND USE TAXES", "cid": 1, "name": "Sales Tax", "exm": 0, "lns": 0, "pcd": 377300, "rate": 0.0125, "sur": false, "tax": 0.3125, "lvl": 2, "tid": 1 }, { "max": 2147483647, "min": 0, "tchg": 25, "calc": 1, "cat": "SALES AND USE TAXES", "cid": 1, "name": "Sales Tax", "exm": 0, "lns": 0, "pcd": 377300, "rate": 0.06, "sur": false, "tax": 1.5, "lvl": 1, "tid": 1 } ] } ]}
```

### See Also

#### Input Objects

-   [`CalcTaxes` request](/communications/dev-guide_rest_v2/reference/calc-taxes-request/)
-   [Invoice](/communications/dev-guide_rest_v2/reference/invoice/)
-   [Line item](/communications/dev-guide_rest_v2/reference/line-item/)
-   [Key Value Pair](/communications/dev-guide_rest_v2/reference/key-value-pair/)

#### Output Objects

-   [`CalcTaxes` response](/communications/dev-guide_rest_v2/reference/calc-taxes-response/)
-   [Detailed tax results](/communications/dev-guide_rest_v2/reference/detailed-tax-result/)
-   [Summarized tax results](/communications/dev-guide_rest_v2/reference/summarized-tax-result/)

-   [Previous](/communications/dev-guide_rest_v2/customizing-transactions/sample-transactions/invoice-mode/)
-   [Next](/communications/dev-guide_rest_v2/customizing-transactions/sample-transactions/adjustment/)