Scaling: Handling errors in invoice mode

This example demonstrates usinginvm =true for batch processing purposes. When invoice mode is enabled for batch processing, each line is treated as related to the entire invoice. As a result, if 1 line error, AFC will raise an error for the entire invoice, as shown in Example 1 below. To fix this error, you need to rerun the entire invoice containing the line item that failed, as shown in Example 2.

Example 1:

Invoice mode isfalse.
Detail mode istrue.
Line 1:
- Line reference is 1_CertTest0_PCD_Only_StreamingVideo
- Bill-to PCode isn’t specified. This line will use the document-level PCode, which is1363100.
- Charge for the transaction is $500
- T/S pair is57/674 (Digital Goods/Streaming Video - OTT - Live)
Line 2:
- Line reference is 2_CertTest0_PCD_Only_StreamingVideo
- Bill-to PCode is00000000000003.
- Charge for the transaction is $500
- T/S pair is57/674 (Digital Goods/Streaming Video - OTT - Live)

Example 2:

The Bill-to PCode for line item 2_CertTest0_PCD_Only_StreamingVideo is removed, and the line item Bill-to PCode will default to the invoice Bill-to PCode.

Example 1: Submit with incorrect PCode

Example request:

The example below runs a transaction in invoice mode with an incorrect PCode at the line item.

curl --location --request POST 'https://communicationsua.avalara.net/api/v2/afc/CalcTaxes' \
--header 'Content-Type: application/json' \
--header 'client_id: 787' \
--header 'client_profile_id;' \
--header 'Authorization: Basic {Base64-encoded credentials}' \
--data-raw '{
    "cfg": {"incrf": true //--Return Reporting Information.
    },
    "cmpn": {"bscl": 1, //--Business Class: Typical value is "1". Is the provider and an Incumbant Local Exchange Carrier ("ILEC",  basically those companies that own the wire, antennas and switches of a network) or not?   0=ILEC, 1=NOT an ILEC (or Competitive Local Exchange Carrier "CLEC"). Streaming default to "1""svcl": 0, //--Service Class:  Is the provider Primarily a local service provider, or long distance?   0=Primary Local; 1=Primary Long Distance.  Streaming default: 0."fclt": false, //--Facilities:  Does the company providing the service have facilities to provide the service?  Streaming default: false."frch": false, //--Franchise:  Indicates if the company provides services sold pursuant to a franchise agreement between the carrier and jurisdiction. Streaming default: false."reg": false, //--Regulated:  Is the Seller is regulated?  Streaming default: false."idnt": "CertCompany"
    },
    "inv": [{    "doc": "Error Handling", //--Document Code:  Required.  A unique value that is used to Commit transactions through the Commit API. Do NOT use InvoiceNumber.  GUID preferable. Every unique call must have a unique "doc".    "cmmt": false, //--Commit:  Required.  The status of transaction for end of period compliance reporting.  Previously CalcTaxes uncommitted transactions can be committed through the Commit API.    "bill": { //--Bill To Object:  Calculates taxed based on the granularity of the address. Options include: passing only Preassigned Pcode value in PCD value via the GEO/PCODE APIs.  The actual address fields: the more granular the address, the more accurate the results.
"pcd": 1363100    },    "cust": 0, //--Customer Type: Required.  Default to "0" for Streaming.    "date": "2022-06-02",    "itms": [
{
    "ref": "1_CertTest0_PCD_Only_StreamingVideo",
    "chg": 500,
    "sale": 1,
    "incl": false,
    "tran": 57,
    "serv": 674,
    "adj": false
},
{
    "ref": "2_CertTest0_PCD_Only_StreamingVideo",
    "chg": 500,
    "sale": 1,
    "incl": false,
    "tran": 57,
    "serv": 674,
    "adj": false,
    "bill": { //--Bill To Object:  Calculates taxed based on the granularity of the address. Options include: passing only Preassigned Pcode value in PCD value via the GEO/PCODE APIs.  The// actual address fields: the more granular the address, the more accurate the results."pcd": 00000000000003
    }
}    ],    "invm": true, //--All line items related to a single invoice    "dtl": true, //--Returns Line Item Detail Taxes    "summ": false,    "acct": "CertCompany",    "custref": "CertTest0",    "invn": "CertTest0",    "bcyc": "202206",    "bpd": { //--Billing Period Object: Used for reporting.
"month": "06",
"year": "2022"    },    "opt": [
{
    "key": "1",
    "val": "FP0" //Idea for locating FP and incorporting in a SelfTest API Endpoint
}    ]}
    ]
}'

Example response:

The response returns an error for the entire invoice and indicates that the reason for the error is that the PCode on line 2_CertTest0_PCD_Only_StreamingVideo is incorrect.

{
    "inv": [{    "doc": "Error Handling",    "itms": [
{
    "ref": "1_CertTest0_PCD_Only_StreamingVideo"
},
{
    "ref": "2_CertTest0_PCD_Only_StreamingVideo",
    "err": [{    "code": -12,    "msg": "PCode not found."}
    ]
}    ],    "err": [
{
    "code": -2000,
    "msg": "One or more LineItems are invalid."
}    ]}
    ]

Example 2: Resubmit with the correct PCode

Example request:

The example below removes the incorrect Bill-to PCode from the 2_CertTest0_PCD_Only_StreamingVideo line item. In this case, the Bill-to PCode will default to the PCode for the invoice. Because the request was run in invoice mode, the entire invoice needs to be rerun.

curl --location --request POST 'https://communicationsua.avalara.net/api/v2/afc/CalcTaxes' \
--header 'Content-Type: application/json' \
--header 'client_id: 787' \
--header 'client_profile_id;' \
--header 'Authorization: Basic {Base64-encoded credentials}' \
--data-raw '{
    "cfg": {"incrf": true //--Return Reporting Information.
    },
    "cmpn": {"bscl": 1, //--Business Class: Typical value is "1". Is the provider and an Incumbant Local Exchange Carrier ("ILEC",  basically those companies that own the wire, antennas and switches of a network) or not?   0=ILEC, 1=NOT an ILEC (or Competitive Local Exchange Carrier "CLEC"). Streaming default to "1""svcl": 0, //--Service Class:  Is the provider Primarily a local service provider, or long distance?   0=Primary Local; 1=Primary Long Distance.  Streaming default: 0."fclt": false, //--Facilities:  Does the company providing the service have facilities to provide the service?  Streaming default: false."frch": false, //--Franchise:  Indicates if the company provides services sold pursuant to a franchise agreement between the carrier and jurisdiction. Streaming default: false."reg": false, //--Regulated:  Is the Seller is regulated?  Streaming default: false."idnt": "CertCompany"
    },
    "inv": [{    "doc": "Error Handling", //--Document Code:  Required.  A unique value that is used to Commit transactions through the Commit API. Do NOT use InvoiceNumber.  GUID preferable. Every unique call must have a unique "doc".    "cmmt": false, //--Commit:  Required.  The status of transaction for end of period compliance reporting.  Previously CalcTaxes uncommitted transactions can be committed through the Commit API.    "bill": { //--Bill To Object:  Calculates taxed based on the granularity of the address. Options include: passing only Preassigned Pcode value in PCD value via the GEO/PCODE APIs.  The actual address fields: the more granular the address, the more accurate the results.
"pcd": 1363100    },    "cust": 0, //--Customer Type: Required.  Default to "0" for Streaming.    "date": "2022-06-02",    "itms": [
{
    "ref": "1_CertTest0_PCD_Only_StreamingVideo",
    "chg": 500,
    "sale": 1,
    "incl": false,
    "tran": 57,
    "serv": 674,
    "adj": false
},
{
    "ref": "2_CertTest0_PCD_Only_StreamingVideo",
    "chg": 500,
    "sale": 1,
    "incl": false,
    "tran": 57,
    "serv": 674,
    "adj": false
}    ],    "invm": true, //--All line items related to a single invoice    "dtl": true, //--Returns Line Item Detail Taxes    "summ": false,    "acct": "CertCompany",    "custref": "CertTest0",    "invn": "CertTest0",    "bcyc": "202206",    "bpd": { //--Billing Period Object: Used for reporting.
"month": "06",
"year": "2022"    },    "opt": [
{
    "key": "1",
    "val": "FP0" //Idea for locating FP and incorporting in a SelfTest API Endpoint
}    ]}
    ]
}'

Example response:

The response shows a successful invoice request and provides tax information for both line items.

{
    "inv": [{    "doc": "Error Handling",    "itms": [
{
    "ref": "1_CertTest0_PCD_Only_StreamingVideo",
    "txs": [{    "bill": true,    "cmpl": true,    "tm": 512.0,    "calc": 1,    "cat": "UTILITY USER TAXES",    "cid": 8,    "name": "Utility Users Tax (Cable Television)",    "exm": 0.0,    "lns": 0,    "min": 0.0,    "pcd": 1362800,    "rate": 0.03,    "sur": true,    "tax": 15.36,    "lvl": 2,    "tid": 71},{    "bill": true,    "cmpl": true,    "tm": 500.0,    "calc": 1,    "cat": "GROSS RECEIPTS TAXES",    "cid": 3,    "name": "Statutory Gross Receipts NF (Video)",    "exm": 0.0,    "lns": 0,    "min": 0.0,    "pcd": 1362800,    "rate": 0.024,    "sur": false,    "tax": 12.0,    "lvl": 1,    "tid": 534},{    "bill": true,    "cmpl": true,    "tm": 500.0,    "calc": 1,    "cat": "EXCISE TAXES",    "cid": 4,    "name": "Excise Tax NF",    "exm": 0.0,    "lns": 0,    "min": 0.0,    "pcd": 1362800,    "rate": 0.03,    "sur": false,    "tax": 15.0,    "lvl": 1,    "tid": 533}
    ]
},
{
    "ref": "2_CertTest0_PCD_Only_StreamingVideo",
    "txs": [{    "bill": true,    "cmpl": true,    "tm": 512.0,    "calc": 1,    "cat": "UTILITY USER TAXES",    "cid": 8,    "name": "Utility Users Tax (Cable Television)",    "exm": 0.0,    "lns": 0,    "min": 0.0,    "pcd": 1362800,    "rate": 0.03,    "sur": true,    "tax": 15.36,    "lvl": 2,    "tid": 71},{    "bill": true,    "cmpl": true,    "tm": 500.0,    "calc": 1,    "cat": "GROSS RECEIPTS TAXES",    "cid": 3,    "name": "Statutory Gross Receipts NF (Video)",    "exm": 0.0,    "lns": 0,    "min": 0.0,    "pcd": 1362800,    "rate": 0.024,    "sur": false,    "tax": 12.0,    "lvl": 1,    "tid": 534},{    "bill": true,    "cmpl": true,    "tm": 500.0,    "calc": 1,    "cat": "EXCISE TAXES",    "cid": 4,    "name": "Excise Tax NF",    "exm": 0.0,    "lns": 0,    "min": 0.0,    "pcd": 1362800,    "rate": 0.03,    "sur": false,    "tax": 15.0,    "lvl": 1,    "tid": 533}
    ]
}    ],    "incrf": {
"acct": "CertCompany",
"custref": "CertTest0",
"invn": "CertTest0",
"bcyc": "202206"    }}
    ]
}