Scaling: Batch request - handling errors

This example demonstrates usinginvm =false for batch processing purposes. When invoice mode is disabled for batch processing, each line is treated as an individual tax request. If one line errors, AFC will raise the error related to an individual line, as shown in Example 1 below. To fix this error, you only need to rerun that line item that failed, as shown in Example 2 below.

Example 1:

Invoice mode isfalse.
Detail mode istrue.
Line 1
- Line reference is 1_CertTest0_PCD_Only_StreamingVideo
- Bill-to PCode is not 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 YW5nZWxhLmJhcnR6QGF2YWxhcmEuY29tOkp2SjI0NjAxQXZhbGFyYSE2' \
--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": false, //--Line items are unrelated
            "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 related to line 2_CertTest0_PCD_Only_StreamingVideo. The error indicates that the PCode is invalid.

{
    "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",
                    "err": [
                        {
                            "code": -12,
                            "msg": "PCode not found."
                        }
                    ]
                }
            ],
            "incrf": {
                "acct": "CertCompany",
                "custref": "CertTest0",
                "invn": "CertTest0",
                "bcyc": "202206"
            }
        }
    ]
}

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 and reruns just that line item. In this case, the Bill-to PCode will default to the PCode for the invoice.

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 YW5nZWxhLmJhcnR6QGF2YWxhcmEuY29tOkp2SjI0NjAxQXZhbGFyYSE2' \
--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": "2_CertTest0_PCD_Only_StreamingVideo",
                    "chg": 500,
                    "sale": 1,
                    "incl": false,
                    "tran": 57,
                    "serv": 674,
                    "adj": false
                }
            ],
            "invm": false, //----Line items are unrelated
            "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 successfully provides tax information for both line items.

{
    "inv": [
        {
            "doc": "Error Handling",
            "itms": [
                {
                    "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"
            }
        }
    ]
}