In this topic:

Ad Hoc Manual Invoices

This example shows you how to use the Gotransverse Billing API to create a manual ad hoc invoice — an adjusting invoice with specific invoice items and charges based on an original invoice.

Example Updated: February 2018.

Terminology

Standard Invoice: Invoice generated within the normal course of Gotransverse billing. Also original invoice, source invoice.

Manual Invoice: Invoice generated within a separate bill batch used to:

  • Present correct administrative attributes such as billing account name or address previously issued invoices; or
  • Correct previously issued invoiced amounts.

Invoice Item: A subset of an invoice representing amounts charged to a billing account for services, onetime charges, usage, etc. along with any related discounts, taxes, etc.

Invoice Item Charge: A subset of an invoice item representing the separate components of the invoice item such as the gross charge and its related discount, taxes, etc.

Gross Invoice Item Charges: Non-tax invoice item charges that may or may not be taxable.

Manual Invoice Types

  • Reverse: Creates a manual invoice with identical invoice item charges but with the values reversed. A manual invoice created by the reverse function will show the exact name and address that appeared on the original invoice, even if the billing account’s name and address have changed in the system.
  • Reissue: Creates a manual invoice with identical invoice item charges. A manual invoice created by the reissue function will show the current name and address on the billing account.
  • Reissue with Retax: Creates a manual invoice with the same gross invoice item charges, but the tax processor will re-tax these gross charges based on the effective date or a date override provided by the user. This will create new tax invoice item charge records.
  • Ad hoc: Creates a manual invoice with invoice items and charges based on items and charges from specified standard invoice items and charges. Modifications to standard invoice items can include changing the original invoice item charge amount, reversing an original invoice item charge by applying a negative amount, or changing tax attributes of an invoice item charge for retax purposes.

Reverse/Reissue/Retax functionality acts on an entire invoice. Ad hoc manual invoices allows the user to make modifications to a portion of the invoice. Additionally, Reverse/Reissue allows the user to make modifications not related to AR balance.

Ad Hoc Manual Invoice Requirements

Note: Users are currently able to create ad hoc manual invoice from standard invoice items and charges only, and not from other manual invoices.

  • Ad hoc manual invoices allow changes to any of the eight invoice item and/or charge attributes from a source invoice item and its charges. These are also known as override fields. If a value for one or more of the attributes is provided, it overrides the value from original invoice item, even if Use_Original_Tax_Data = True.
  • Start Date Specifies the period of benefit for the invoice item. For example, the original invoice item may have a start date of Jan 1, but the ad hoc manual invoice item is for Jan 1 to Jan 5.
    • May be specified on invoice item and invoice item charge
    • If not provided, defaults to value from original invoice item and charge
    End Date Specifies the period of benefit for the invoice item. For example, the original invoice item may have an end date of Feb 1, but the ad hoc manual invoice item is for Jan 1 to Jan 5.
    • May be specified on invoice item and invoice item charge
    • If not provided, defaults to value from original invoice item and charge
    Quantity
    • May be specified on invoice item and invoice item charge
    • If not provided, defaults to value from original invoice item and charge
    Amount
    • May be specified on invoice item charge
    • If not provided, defaults to value from original invoice item charge
    Description
    • May be specified on invoice item
    • If not provided, defaults to value from original invoice item
    Tax Code Specifies the tax code value sent to the tax processor for calculating tax charges. Also known as ‘transaction/service pair’ for ad hoc manual invoices using Avalara Communications Tax.
    • May be specified on the invoice item charge
    • Only applicable to invoice item charges that are taxable
    • If not provided:
      • Defaults to current value when Use_Original_Tax_Data = False
      • Defaults to value from original invoice item when Use_Original_Tax_Data = True
    Tax Pcode A numeric value that is generated by Gotransverse when you add an address to a billing account or service. The P-Code is associated with a taxing jurisdiction used to calculate taxes. It is recommended to use a P-Code that is the most geographically specific. Applicable to ad hoc manual invoices using Avalara Communications Tax only.
    • May be specified on the invoice item charge
    • Only applicable to invoice item charges that are taxable
    • If not provided:
      • Defaults to current value of the service or add-on being taxed when Use_Original_Tax_Data = False
      • Defaults to P-Code value used from original invoice item when Use_Original_Tax_Data = True
    Tax Date Specifies the date when the tax should be applied. This date is sent to the Tax Processor for calculating taxes. For example, if creating an ad hoc manual invoice for an invoice created one month ago, the tax date is set to one month in the past.
    • May be specified on the invoice item charge
    • Only applicable to invoice item charges that are taxable
    • If not provided:
      • Defaults to current value when Use_Original_Tax_Data = False
      • Defaults to value from original invoice item when Use_Original_Tax_Data = True
  • Ad hoc manual invoices have three additional attributes:
  • Exclude from Taxation If set to true, the invoice item charge will not be taxed regardless of its tax settings. If set to false, the invoice item charge will be taxed normally.
    • Specified on an invoice item charge
    • Required
    Manual Invoice Reason This may be used for reporting, GL postings, and invoice notifications.
    • Specified on invoice and invoice item
    • Required
    Use Original Tax Data

    For use with Avalara Communications Tax, specifies what tax data is used for the ad hoc manual invoice retax.

    • If set to true, the original tax values from the source invoice item (amount, quantity, tax code, tax Pcode, and tax date) are used.
    • If set to false, the current tax data (from the payload) is used to perform the ad hoc retax.
    • Default value is false. If not specified, assumed value is false.

    Note: Even if Use_Original_Tax_Data = True, any override field values specified in the payload override original tax data values. For example, if you set 'Use_Original_Tax_Data = TRUE', but then specify a tax_pcode value of 12345678, the value 12345678 is used in the ad hoc tax calculation in lieu of the original tax_pcode value for the source invoice item.

  • Ad hoc manual invoice item types that do not source from original charges:
  • Adhoc Not currently supported
    TaxOnly Not currently supported

Additional Considerations

  • Ad hoc invoice items must be created with invoice item charges with source_ids belonging to the original invoice item’s source_id. There is currently no validation for this. The user must be accurate in maintaining this relationship while creating ad hoc invoices via the API call.
  • Invoice item amount = sum of invoice item charge amounts and will be calculated by Gotransverse.
  • Invoice amount = sum of invoice item amounts and will be calculated by Gotransverse.
  • Manual-Tax and Manual-Adhoc invoice item charges are not yet delivered in full as of February 2018. This functionality aims to create ad hoc invoice item charges without reference to an original invoice item or charge. This means the user is able to create them without providing “source_charge_id” and “source_invoice_item_type.” Ensure that you are not sending API calls with these ad hoc invoice item charge types.

Creating an Ad Hoc Invoice

Example Scenario

An invoice contains two services, each with a taxable recurring price (50 EUR) and a taxable discount (20 EUR) with a tax rate of 10%. Total invoice amount = (50-20)*2*1.1 = 66 EUR.

This invoice contains two invoice items, each with four invoice item charges for a total of eight invoice item charges for the invoice. Each invoice item has a charge for the service price of 50 EUR, a discount of -20 EUR and a tax of 5 and -2 EUR for a total of 33 EUR for each invoice item and 66 EUR for the invoice.

The original invoice defined above is created for January. The billing manager discovers that price of the second service should have been 45 EUR and discount should have been reduced proportionally to 18 EUR.

Desired ad hoc invoice amount = -3.3 EUR (((45-50) – (18-20))*1.1)

Prerequisites

  • A manual invoice reason exists in Gotransverse. (Setup > Reasons > Manual Invoice Reasons)
  • A tax processor is configured in Gotransverse. (Admin > Integration > Tax Processors: External Tax)

API Request Execution

  1. If necessary, get billing account ID via billing account number. For full implementation, we suggest you maintain the billing account ID in an application like Salesforce so you don’t need this API call for manual invoice processing:
    GET / billing/2/billing-accounts?account_num={billing_account_num}
    Example
    GET https://example-tract-api.com/billing/2/billing-accounts?account_num=99
    Response
    {"id": "1421298", "account_num": "99",…etc}
  2. Get invoice ID, invoice item ID and type, invoice item charge ID and type via invoice number or via billing account number:
    • Via invoice number: GET /billing/2/invoices?invoice _num={invoice _num}
      Example
      GET https://example-tract-api.com/billing/2/invoices?invoice_num=398-233
    • Via billing account number: GET /billing/2/invoices?account_num={billing_account_num}
      Example
      GET https://example-tract-api.com/billing/2/invoices?account_num=99
    • Response for Both

      Assumes there is one invoice on this billing account. Relevant information for further steps is in blue.

      
      [
        {
          "invoice_type": "standard", 
          "id": "744266",
          "amount": 66, 
          "status": "OPEN",
          "invoice_num": "398-233",
          "billing_account": {
            "id": "1421298", 
            "account_num": "99", 
            "external_account_num": null
          },
          "occurred_on": "2017-02-01T00:00:00-06:00",
          "due_date": "2017-02-01",
          "amount_to_pay": 66,
          "late_fee_charged": false,
          "bill_cycle": {
            "bill_cycle_type": "monthly",
            "id": "9534",
            "name": "Test Ad Hoc"
          },					
          "invoice_items": [
            {
              "invoice_item_type": "service", 
              "id": "8265276",
              "quantity": 1,
              "taxable": true, 
              "service": {
                "id": "2091728"
              },
            "unit_amount": 33, 
            "total_amount": 33, 
            "prorated_percentage": 100, 					
            "charges": [
              {
                "invoice_item_charge_type": "charge",
                "id": "9476846", 
                "amount": 50, 
                "balance": 30, 
                "paid": false, 
                "un_prorated_amount": 50, 
                "price_category": {
                  "charge_category_type": "price",
                  "id": "2266",
                  "name": "Default"
                },
                "recurring_charge": true, 
                "bill_in_advance": false, 
                "description": "Default",
                "exclude_from_taxation": false,
                "quantity": 1
              },
              {
                "invoice_item_charge_type": "discount",
                "id": "9476847", 
                "amount": -30, 
                "balance": 0, 
                "paid": true, 
                "un_prorated_amount": -20,
                "price_category": {
                  "charge_category_type": "discount",
                  "id": "2267",
                  "name": "Discount"
                },
                "recurring_charge": true, 
                "bill_in_advance": false, 
                "description": "Default",
                "exclude_from_taxation": false,
                "quantity": 1,
                "discount_code": {
                  "discount_code_type": "service",
                  "id": "27756"
                }
              },
              {							
                "invoice_item_charge_type": "tax",
                "id": "9477020",
                "amount": 5, "balance": 5,
                "paid": false, 
                "price_category":{
                  "charge_category_type": "tax",
                  "id": "2334",
                  "name": "Sales Tax"
                },
                "description": "VAT",
                "exclude_from_taxation": false,
                "quantity": 1,
                "tax_category_id": 0,
                "tax_code": "1",
                "tax_level":"Federal",
                "tax_rate": 0.1, 
                "jurisdiction_name": "VAT"
              },
              {
                "invoice_item_charge_type": "tax",
                "id": "9477084",
                "amount": -2, 
                "balance": -2,
                "paid": true, 
                "price_category": {
                  "charge_category_type": "tax",
                  "id": "2334",
                  "name": "Sales Tax"
                },
                "description": "VAT",
                "exclude_from_taxation": false,
                "quantity": 1,
                "tax_category_id": 0,
                "tax_code": "1",
                "tax_level": "Federal",
                "tax_rate": 0.1, 
                "jurisdiction_name": "VAT"
              },
            ], 
            "start_date": "2017-01-01T00:00:00-06:00",
            "end_date": "2017-02-01T00:00:00-06:00"}
          }
          {
            "invoice_item_type": "service",
            "id": "8265277",
            "quantity": 1,
            "taxable": false, 
            "service": {  
              "id": "2091728"
            },
            "unit_amount": 33, 
            "total_amount": 33, 
            "prorated_percentage": 100,				 
            "charges": [
              {
                "invoice_item_charge_type": "charge",
                "id": "9476847", 
                "amount": 50, 
                "balance": 30, 
                "paid": false, 
                "un_prorated_amount": 50, 
                "price_category": {
                  "charge_category_type": "price",
                  "id": "2266",
                  "name": "Default"
                },
                "recurring_charge": true, 
                "bill_in_advance": false, 
                "description": "Default",
                "exclude_from_taxation": false,
                "quantity": 1
              },
              {
                "invoice_item_charge_type": "discount",
                "id": "9476848", 
                "amount": -30, 
                "balance": 0, 
                "paid": true, 
                "un_prorated_amount": -20, 
                "price_category": {
                  "charge_category_type": "discount",
                  "id": "2267",
                  "name": "Discount"
                },
                "recurring_charge": true, 
                "bill_in_advance": false, 
                "description": "Default",
                "exclude_from_taxation": false,
                "quantity": 1,
                "discount_code": {
                  "discount_code_type": "service",
                  "id": "27756"
                }
              }, 
              {
                "invoice_item_charge_type": "tax",
                "id": "9477021",
                "amount": 3.3, 
                "balance": 3.3,
                "paid": false, 
                "price_category": {
                  "charge_category_type": "tax",
                  "id": "2334",
                  "name": "Sales Tax"
                },
                "description": "VAT",
                "exclude_from_taxation": false, 
                "quantity": 1,
                "tax_category_id": 0,
                "tax_description": "Some description",
                "tax_code": "1",
                "tax_level": "Federal",
                "tax_rate": 0.1, 
                "jurisdiction_name": "VAT"
              },
              {
                "invoice_item_charge_type": "tax",
                "id": "9477085",
                "amount": -2, 
                "balance": -2,
                "paid": true, 
                "price_category": {
                  "charge_category_type": "tax",
                  "id": "2334",
                  "name": "Sales Tax"
                },
                "description": "VAT",
                "exclude_from_taxation": false, 
                "tax_category_id": 0,
                "tax_description": "Some description",
                "quantity": 1,
                "tax_code": "1",
                "tax_level": "Federal",
                "tax_rate": 0.1, 
                "jurisdiction_name": "VAT"
              }
            ],
            "start_date": "2017-01-01T00:00:00-06:00",
            "end_date": "2017-02-01T00:00:00-06:00"
          }
        ], 
        "billing_statement": {
          "statement_type": "statement",
          "balance": 0, 
          "id": "567990",
          "total_amount": 66, 
          "service_charges": 60, 
          "activity_charges": 0, 
          "other_charges_and_credits": 0, 
          "taxes_and_fees": 6, 
          "total_current_charges": 66, 
          "payment_received_amount": 0, 
          "payment_canceled_amount": 0,
          "credit_adjustments_posted_amount": 0, 
          "credit_adjustments_write_off_amount": 0
        },
        "auto_payment_date": "2017-02-01"
       }
      ]
  3. If necessary, get manual invoice reason ID. For full implementation, we suggest you maintain manual invoice reason IDs in an application like Salesforce so you don’t need this API call for manual invoice processing:
    GET /billing/2/manual-invoice-reasons
    Example
    GET https://example-tract-api.com/billing/2/manual-invoice-reasons

    Response

    
    [{
      "reason_type": "manual-invoice",
      "id": "1940",
      "name": "Default Manual Invoice Reason",
      "description": "Default Manual Invoice Reason",
      "status": "ACTIVE
    }]
  4. Create ad hoc bill batch and invoice:
    POST /billing/2/billing-accounts/{billing_account_id}/adhoc-bill-batches
    Mandatory fields are in red. Variable values populated from previous steps are in blue.

    Example
    POST https://example-tract-api.com/billing/2/billing-accounts/1421298/adhoc-bill-batches

    Payload

    
    {"name": "Ad-Hoc25",
    "invoice_due_date": "2017-02-20T10:58:45.278Z",
    "use_payment_term": true,
    "invoice_date": "2017-03-10T10:58:45.278Z",
    "auto_approve": false,
    "reason": {
      "id": "1940",
      "reason_type": "manual-invoice"
      },
    "invoices": [
      {
        "invoice_type": "manual",
    	"invoice_items": [
    	  {
            "invoice_item_type": "manual-service",
            "reason": {
            "id": "1940",
            "reason_type": "manual-invoice"}, 
            "quantity": 1,
            "charges": [
            { 
              "invoice_item_charge_type": "manual",
              "amount": -5,
              "exclude_from_taxation": false,
              "source_charge": {
              "id":"9476847",
              "invoice_item_charge_type": "charge"}
            },
            {
            "invoice_item_charge_type": "manual-discount",
            "amount": 2,
            "exclude_from_taxation": false,
            "source_charge": {
            "id": "9476848",
            "invoice_item_charge_type": "discount"}
            }  
            ],
            "source_item": {
              "id": "8265277",
              "invoice_item_type": "service"}
              }]
           } ],
       "auto_run": true
    }

    Response

    
    {
      "bill_batch_type": "adhoc",
      "id": "9608",
      "name": "Ad-Hoc25",
      "use_payment_term": true,
      "status": "ACTIVE",
      "currency_code": "USD",
      "end_date": "2017-03-10T04:58:45-06:00",
      "internal_render": true,
      "bill_batch_runs": [
        {
          "bill_run_type": "batch",
          "id": "989142",
          "sequence": 1,
          "step": "AVAILABLE",
          "step_status": "SCHEDULED",
          "status_date": "2017-11-29T16:50:59-06:00",
          "open_date": "2017-03-10T04:58:45-06:00",
          "close_date": "2017-03-10T04:58:45-06:00",
          "scheduled_run_date": "2017-11-29T16:50:59-06:00",
          "invoice_due_date": "2017-02-20T00:00:00-06:00",
          "processed_invoice_count": 0,
          "invoice_date": "2017-03-10T04:58:45-06:00",
          "use_payment_term": false,
          "invoices": [
            {
              "invoice_type": "manual",
              "id": "744366",
              "amount": -3,
              "status": "DRAFT",
              "invoice_num": "115039924",
              "billing_account": {
                "id": "1421298",
                "account_num": "103",
                "external_account_num": null
              },
              "occurred_on": "2017-03-10T04:58:45-06:00",
              "due_date": "2017-02-20",
              "amount_to_pay": -3,
              "late_fee_charged": false,
              "invoice_items": [
                {
                  "invoice_item_type": "manual-service",
                  "id": "8265440",
                  "quantity": 1,
                  "taxable": true,
                  "unit_amount": -3,
                  "total_amount": -3,
                  "prorated_percentage": 100,
                  "charges": [
                    {
                      "invoice_item_charge_type": "manual",
                      "id": "9477102",
                      "amount": -5,
                      "balance": -5,
                      "paid": true,
                      "un_prorated_amount": -5,
                      "price_category": {
                        "charge_category_type": "price",
                        "id": "3482",
                        "name": "PRI-eBayK"
                        },
                      "recurring_charge": true,
                      "bill_in_advance": false,
                      "description": "PRI-eBayK",
                      "exclude_from_taxation": false,
                      "previous_charge": {
                        "invoice_item_charge_type": "charge",
                        "id": "9477080"
                      }
                    },
                    {
                      "invoice_item_charge_type": "manual-discount",
                      "id": "9477104",
                      "amount": 2,
                      "balance": 0,
                      "paid": true,
                      "un_prorated_amount": 2,
                      "price_category": {
                        "charge_category_type": "discount",
                        "id": "4168",
                        "name": "PRI-eBayK"
                         },
                      "recurring_charge": true,
                      "bill_in_advance": false,
                      "description": "PRI-eBayK",
                      "exclude_from_taxation": false,
                      "previous_charge": {
                        "invoice_item_charge_type": "discount",
                        "id": "9477078"
                        }
                    }
              ],
              "start_date": "2018-07-20T00:00:00-05:00",
              "end_date": "2018-07-20T00:00:00-05:00",
              "previous_item": {
                "invoice_item_type": "service",
                "id": "8265434"
                },
              "manual_type": "ADHOC",
              "reason": {
                "reason_type": "manual-invoice",
                "id": "1940",
                "name": "Default Manual Invoice Reason"
                },
              "service": {
                "id": "2091818"
                }
              }
            ],
            "auto_payment_date": "2017-03-10"
            }
          ]
        }
      ],
      "auto_approve": false,
      "reason": {
        "reason_type": "manual-invoice",
        "id": "1940",
        "name": "Default Manual Invoice Reason"
          }
      }

  5. Get information about newly created bill batch by bill batch run ID:
    GET /billing/2/bill-batch-runs/{bill_batch_run_id}
    Example
    GET https://example-tract-api.com/billing/2/bill-batch-runs/989142

    Response

    Look for “status:” “PROCESSING” to ensure bill batch has completed running.

    
    [
      {
        "bill_batch_type": "adhoc",
        "id": "9608",
        "name": "Ad-Hoc25",
        "use_payment_term": true,
        "status": "ACTIVE",
        "currency_code": "USD",
        "end_date": "2017-03-10T04:58:45-06:00",
        "internal_render": true,
        "bill_batch_runs": [
          {
            "bill_run_type": "batch",
            "id": "989142",
            "sequence": 1,
            "step": "GENERATE_KPIS",
            "step_status": "COMPLETED",
            "status_date": "2017-11-29T16:02:11-06:00",
            "open_date": "2017-03-10T04:58:45-06:00",
            "close_date": "2017-03-10T04:58:45-06:00",
            "scheduled_run_date": "2017-11-29T16:02:06-06:00",
            "invoice_due_date": "2017-02-20T00:00:00-06:00",
            "processed_invoice_count": 1,
            "invoice_date": "2017-03-10T04:58:45-06:00",
            "use_payment_term": false,
            "invoices": [
              {
                "invoice_type": "manual",
                "id": "744366",
                "amount": -3.3,
                "status": "PROCESSING",
                "invoice_num": "115039907",
                "billing_account": {
                  "id": "1421298",
                  "account_num": "99",
                  "external_account_num": null
                },
                "occurred_on": "2017-03-10T04:58:45-06:00",
                "due_date": "2017-02-20",
                "amount_to_pay": -3.3,
                "late_fee_charged": false,
                "invoice_items": [
                  {
                    "invoice_item_type": "manual-service",
                    "id": "8265440",
                    "quantity": 1,
                    "taxable": true,
                    "unit_amount": -3.3,
                    "total_amount": -3.3,
                    "prorated_percentage": 100,
                    "charges": [
                      {
                        "invoice_item_charge_type": "manual",
                        "id": "9477086",
                        "amount": -5,
                        "balance": -5,
                        "paid": true,
                        "un_prorated_amount": -5,
                        "price_category": {
                          "charge_category_type": "price",
                          "id": "3482",
                          "name": "PRI-eBayK"
                        },
                        "recurring_charge": true,
                        "bill_in_advance": false,
                        "description": "PRI-eBayK",
                        "exclude_from_taxation": false,
                        "previous_charge": {
                          "invoice_item_charge_type": "charge",
                          "id": "9477080"
                        }
                      },
                      {
                        "invoice_item_charge_type": "manual-discount",
                        "id": "9477104",
                        "amount": 2,
                        "balance": 0,
                        "paid": true,
                        "un_prorated_amount": 2,
                        "price_category": {
                          "charge_category_type": "discount",
                          "id": "4168",
                          "name": "PRI-eBayK"
                          },
                        "recurring_charge": true,
                        "bill_in_advance": false,
                        "description": "PRI-eBayK",
                        "exclude_from_taxation": false,
                        "previous_charge": {
                          "invoice_item_charge_type": "discount",
                          "id": "9477078"
                        }
                      },
                      {
                        "invoice_item_charge_type": "tax",
                        "id": "9477090",
                        "amount": -0,5,
                        "balance": -0,5,
                        "paid": true,
                        "price_category": {
                          "charge_category_type": "tax",
                          "id": "2334",
                          "name": "Sales Tax"
                        },
                        "description": "VAT",
                        "exclude_from_taxation": false,
                        "tax_category_id": 0,
                        "tax_description": "Some description",
                        "tax_code": "1",
                        "tax_level": "Federal",
                        "tax_rate": 0.25,
                        "jurisdiction_name": "VAT"
                      },
                      {
                        "invoice_item_charge_type": "tax",
                        "id": "9477092",
                        "amount": 0.2,
                        "balance": 0.2,
                        "paid": false,
                        "price_category": {
                          "charge_category_type": "tax",
                          "id": "2334",
                          "name": "Sales Tax"
                        },
                        "description": "VAT",
                        "exclude_from_taxation": false,
                        "tax_category_id": 0,
                        "tax_description": "Some description",
                        "tax_code": "1",
                        "tax_level": "Federal",
                        "tax_rate": 0.25,
                        "jurisdiction_name": "VAT"
                      }
                    ],
                    "start_date": "2018-07-20T00:00:00-05:00",
                    "end_date": "2018-07-20T00:00:00-05:00",
                    "previous_item": {
                      "invoice_item_type": "service",
                      "id": "8265434"
                      },
                    "manual_type": "ADHOC",
                    "reason": {
                      "reason_type": "manual-invoice",
                      "id": "1940",
                      "name": "Default Manual Invoice Reason"
                    },
                    "service": {
                      "id": "2091818"
                    }
                  }
                ],
                "billing_statement": {
                  "statement_type": "adhoc-statement",
                  "id": "568080",
                  "service_charges": -3,
                  "activity_charges": 0,
                  "other_charges_and_credits": 0,
                  "taxes_and_fees": -0.3,
                  "total_current_charges": -3.3
                  },
                "auto_payment_date": "2017-03-10"
                }
              ]
            }
          ],
         "auto_approve": false,
         "reason": {
    	  "reason_type": "manual-invoice",
    	  "id": "1940",
    	  "name": "Default Manual Invoice Reason"
         }	
        }
      ]
    1. Run bill batch if "auto_run" was set to be “false” in step #4:
      POST /billing/2/bill-batch-runs/{bill_batch_run_id}/run
      Example
      POST https://example-tract-api.com/billing/2/bill-batch-runs/989142/run

      Payload

      
      {
      "scheduled_date": "2017-11-30T17:42:50.320Z",
      "bill_run_type": "batch",
      "invoice_date": "2017-02-10T10:58:45.278Z",
      "invoice_due_date": "2017-11-28T17:42:50.320Z",
      "use_payment_term": true
      }	
      				

      Response

      Empty - 204 No Response
    2. Approve bill batch if "auto_approve" was set to “false” in step #4:
      POST /billing/2/bill-batch-runs/{bill_batch_run_id}/approve
      Example
      POST https://example-tract-api.com/billing/2/bill-batch-runs/989142/approve

      Response

      Empty - 204 No Response
    3. Cancel bill batch if it is already run, but not yet approved:
      POST /billing/2/bill-batch-runs/{bill_batch_run_id}/cancel
      Example
      POST https://example-tract-api.com/billing/2/bill-batch-runs/989142/cancel

      Response

      Empty - 204 No Response
    4. Delete bill batch if its bill batch run is already canceled:
      DELETE /billing/2/bill-batches/{bill_batch _id}
      Example
      DELETE https://example-tract-api.com/billing/2/bill-batches/9608

      Response

      Empty - 204 No Response

Creating an Ad Hoc Invoice Using Updated Tax Data

Example Scenario

An invoice for service period 8/2/2017 - 9/2/2017 contains one service with a taxable recurring price ($100.00 USD) and the following taxed amounts:

  • $1.00 Transit Tax @ 1%
  • $1.00 Sales Tax (Local) @ 1%
  • $6.25 Sales Tax (State) @ 6.25%

This invoice contains one invoice item with four invoice item charges (1 charge for the service price of $100.00 USD and associated taxes of $1.00. $1.00, and $6.25). The total amount of the invoice is $108.25 ($100 + $1 + $1 + $6.25)

The billing manager discovers that the price of the service as well as the PCode and Tax Code (Transaction/Service Pair) used for tax calculation purposes was incorrect.

Desired corrections for Ad Hoc Invoice are as follows:

  • Charge amount should be changed from $100.00 USD to $90.00 USD
  • PCode should be changed from 3887600 to 3879200
  • T/S Pair should be changed from 24-60 to 19-30

Prerequisites

  • A manual invoice reason exists in Gotransverse. (Setup > Reasons > Manual Invoice Reasons)
  • A tax processor is configured in Gotransverse. (Admin > Integration > Tax Processors: External Tax)

API Request Execution

  1. Get invoice ID, invoice item ID and type, invoice item charge ID and type via a query to the invoices endpoint using invoice number or billing account number as a query key.
    Example
    GET https://example-tract-api.com/billing/2/invoices?invoice_num=418391

    Response

    Assumes there is one invoice on this billing account. Relevant information for further steps is in blue.

    [
        {
            "invoice_type": "standard",
            "id": "754144",
            "amount": 108.25,
            "status": "OPEN",
            "invoice_num": "418391",
            "billing_account": {
                "id": "1424664",
                "account_num": "316",
                "external_account_num": null
            },
            "occurred_on": "2017-10-01T00:00:00-05:00",
            "due_date": "2017-10-31",
            "amount_to_pay": 108.25,
            "late_fee_charged": false,
            "bill_cycle": {
                "bill_cycle_type": "monthly",
                "id": "11452",
                "name": "Ad Hoc Bill Cycle 2"
            },
            "invoice_items": [
                {
                    "invoice_item_type": "service",
                    "id": "8307960",
                    "quantity": 1,
                    "taxable": true,
                    "service": {
                        "id": "2096366"
                    },
                    "unit_amount": 108.25,
                    "total_amount": 108.25,
                    "prorated_percentage": 100,
                    "charges": [
                        {
                            "invoice_item_charge_type": "charge",
                            "id": "9531490",
                            "amount": 100,
                            "balance": 100,
                            "paid": false,
                            "un_prorated_amount": 100,
                            "price_category": {
                                "charge_category_type": "price",
                                "id": "2538",
                                "name": "Price Charge Category M3"
                            },
                            "recurring_charge": true,
                            "bill_in_advance": false,
                            "description": "Price Charge Category M3",
                            "exclude_from_taxation": false,
                            "quantity": 1
                        },
                        {
                            "invoice_item_charge_type": "tax",
                            "id": "9531496",
                            "amount": 1,
                            "balance": 1,
                            "paid": false,
                            "price_category": {
                                "charge_category_type": "tax",
                                "id": "2380",
                                "name": "Tax Price Category"
                            },
                            "description": "Transit Tax",
                            "exclude_from_taxation": false,
                            "quantity": 1,
                            "tax_category_id": 0,
                            "tax_description": "Transit Tax",
                            "tax_code": "24-60",
                            "tax_level": "Local",
                            "tax_rate": 0.01
                        },
                        {
                            "invoice_item_charge_type": "tax",
                            "id": "9531498",
                            "amount": 1,
                            "balance": 1,
                            "paid": false,
                            "price_category": {
                                "charge_category_type": "tax",
                                "id": "2380",
                                "name": "Tax Price Category"
                            },
                            "description": "Sales Tax",
                            "exclude_from_taxation": false,
                            "quantity": 1,
                            "tax_category_id": 0,
                            "tax_description": "Sales Tax",
                            "tax_code": "24-60",
                            "tax_level": "Local",
                            "tax_rate": 0.01
                        },
                        {
                            "invoice_item_charge_type": "tax",
                            "id": "9531500",
                            "amount": 6.25,
                            "balance": 6.25,
                            "paid": false,
                            "price_category": {
                                "charge_category_type": "tax",
                                "id": "2380",
                                "name": "Tax Price Category"
                            },
                            "description": "Sales Tax",
                            "exclude_from_taxation": false,
                            "quantity": 1,
                            "tax_category_id": 0,
                            "tax_description": "Sales Tax",
                            "tax_code": "24-60",
                            "tax_level": "State",
                            "tax_rate": 0.0625
                        }
                    ],
                    "start_date": "2017-08-02T00:00:00-05:00",
                    "end_date": "2017-09-02T00:00:00-05:00"
                }
            ],
            "billing_statement": {
                "statement_type": "statement",
                "balance": 0,
                "id": "576232",
                "total_amount": 108.25,
                "service_charges": 100,
                "activity_charges": 0,
                "other_charges_and_credits": 0,
                "taxes_and_fees": 8.25,
                "total_current_charges": 108.25,
                "payment_received_amount": 0,
                "payment_canceled_amount": 0,
                "credit_adjustments_posted_amount": 0,
                "credit_adjustments_write_off_amount": 0
            },
            "auto_payment_date": "2017-10-26",
            "disputed": false
        }
    ]
  2. If necessary, get manual invoice reason ID. For full implementation, we suggest you maintain manual invoice reason IDs in an application like Salesforce so you don’t need this API call for manual invoice processing:
    Example
    GET https://example-tract-api.com/billing/2/manual-invoice-reasons

    Response

    [
    	{
      		"reason_type": "manual-invoice",
      		"id": "1942",
      		"name": "Default Manual Invoice Reason",
      		"description": "Default Manual Invoice Reason",
      		"status": "ACTIVE
    	}
    ]
  3. Create an ad hoc bill batch and invoice with the following updates in mind:
    • Reverse ALL amounts from original invoice by inputting negative amounts for the original gross and tax charges:
      • -$100.00 Service Charge Amount
      • -$1.00 Transit Tax @ 1%
      • -$1.00 Sales Tax (Local) @ 1%
      • -$6.25 Sales Tax (State) @ 6.25%
    • Correct amounts and tax attributes (override fields):
      • Charge amount should be changed from $100.00 USD to $90.00 USD
      • PCode should be changed from 3887600 to 3879200
      • Tax Code (T/S pair) should be changed from 24-60 to 19-30
      • Note that the example payload below includes override values for 'quantity' and 'tax_date' that are the same on the original source invoice item. These fields are included to show where override values go if they are needed.
    POST /billing/2/billing-accounts/{billing-account-id}/adhoc-bill-batches

    Example
    POST https://example-tract-api.com/billing/2/billing-accounts/1424664/adhoc-bill-batches

    Payload

    Mandatory fields are in red. Variable values populated from previous steps are in blue. Fields that are overridden from their original values are in green.

    {
    "name": "Test Ad Hoc Invoice - Modifications for Invoice 418931",
    "invoice_due_date": "2018-02-28T10:58:45.278Z",
    "use_payment_term": true,
    "invoice_date": "2018-02-22T10:58:45.278Z",
    "auto_approve": false,
    "reason": {
      "id": "1942",
      "reason_type": "manual-invoice"
      },
    "invoices": [
      {
        "invoice_type": "manual",
      "invoice_items": [
        {
            "invoice_item_type": "manual-service",
            "reason": {
            "id": "1942",
            "reason_type": "manual-invoice"}, 
            "quantity": 1,
            "charges": [
            { 
              "invoice_item_charge_type": "manual",
              "amount": -100,
              "exclude_from_taxation": true,
              "source_charge": {
              "id":"9531490",
              "invoice_item_charge_type": "charge"}
            },
            {
            "invoice_item_charge_type: "manual-tax",
            "amount": -1,
            "exclude_from_taxation": true,
            "source_charge": {
            "id": "9531496",
            "invoice_item_charge_type": "tax"}
            },  
            {
            "invoice_item_charge_type": "manual-tax",
            "amount": -1,
            "exclude_from_taxation": true,
            "source_charge": {
            "id": "9531498",
            "invoice_item_charge_type": "tax"}
            },
            {
            "invoice_item_charge_type": "manual-tax",
            "amount": -6.25,
            "exclude_from_taxation": true,
            "source_charge": {
            "id": "9531500",
            "invoice_item_charge_type": "tax"}
            }
           {
            "invoice_item_charge_type": "manual",
            "quantity": 1,        
            "amount": 90,
            "tax_code": "19-30,
            "tax_pcode": 3879200,
            "tax_date": "2017-10-01T00:00:00+03:00",
             "use_original_tax_data": false,
            "exclude_from_taxation": false,
            "source_charge": {
            "id": "9531490",
            "invoice_item_charge_type": "charge"}
            }
            ],
            "source_item": {
              "id": "8307960",
              "invoice_item_type": "service"}
              }]
           } ],
       "auto_run": true
    }

    Response

    
    {
        "bill_batch_type": "adhoc",
        "id": "11454",
        "name": "Test Ad Hoc Invoice - Modifications for Invoice 418931",
        "use_payment_term": true,
        "status": "ACTIVE",
        "currency_code": "USD",
        "end_date": "2018-02-22T04:58:45-06:00",
        "internal_render": true,
        "bill_batch_runs": [
            {
                "bill_run_type": "batch",
                "id": "1077710",
                "sequence": 1,
                "step": "AVAILABLE",
                "step_status": "SCHEDULED",
                "status_date": "2018-02-22T16:25:11-06:00",
                "open_date": "2018-02-22T04:58:45-06:00",
                "close_date": "2018-02-22T04:58:45-06:00",
                "scheduled_run_date": "2018-02-22T16:25:11-06:00",
                "processed_invoice_count": 0,
                "invoice_date": "2018-02-22T04:58:45-06:00",
                "use_payment_term": true,
                "status": "READY",
                "invoices": [
                    {
                        "invoice_type": "manual",
                        "id": "754150",
                        "amount": -18.25,
                        "status": "DRAFT",
                        "invoice_num": "115234833",
                        "billing_account": {
                            "id": "1424664",
                            "account_num": "316",
                            "external_account_num": null
                        },
                        "occurred_on": "2018-02-22T04:58:45-06:00",
                        "due_date": "2018-03-24",
                        "amount_to_pay": -18.25,
                        "late_fee_charged": false,
                        "invoice_items": [
                            {
                                "invoice_item_type": "manual-service",
                                "id": "8307966",
                                "quantity": 1,
                                "taxable": true,
                                "unit_amount": -18.25,
                                "total_amount": -18.25,
                                "prorated_percentage": 100,
                                "charges": [
                                    {
                                        "invoice_item_charge_type": "manual",
                                        "id": "9531510",
                                        "amount": -100,
                                        "balance": -100,
                                        "paid": true,
                                        "un_prorated_amount": -100,
                                        "price_category": {
                                            "charge_category_type": "price",
                                            "id": "2538",
                                            "name": "Price Charge Category M3"
                                        },
                                        "recurring_charge": true,
                                        "bill_in_advance": false,
                                        "description": "Price Charge Category M3",
                                        "exclude_from_taxation": true,
                                        "quantity": 1,
                                        "previous_charge": {
                                            "invoice_item_charge_type": "charge",
                                            "id": "9531490"
                                        },
                                        "use_original_tax_data": false
                                    },
                                    {
                                        "invoice_item_charge_type": "manual-tax",
                                        "id": "9531512",
                                        "amount": -1,
                                        "balance": -1,
                                        "paid": true,
                                        "un_prorated_amount": -1,
                                        "price_category": {
                                            "charge_category_type": "tax",
                                            "id": "2380",
                                            "name": "Tax Price Category"
                                        },
                                        "description": "Tax Price Category",
                                        "exclude_from_taxation": true,
                                        "quantity": 1,
                                        "previous_charge": {
                                            "invoice_item_charge_type": "tax",
                                            "id": "9531496"
                                        },
                                        "use_original_tax_data": false,
                                        "tax_category_id": 0,
                                        "tax_lines": 0
                                    },
                                    {
                                        "invoice_item_charge_type": "manual-tax",
                                        "id": "9531514",
                                        "amount": -1,
                                        "balance": -1,
                                        "paid": true,
                                        "un_prorated_amount": -1,
                                        "price_category": {
                                            "charge_category_type": "tax",
                                            "id": "2380",
                                            "name": "Tax Price Category"
                                        },
                                        "description": "Tax Price Category",
                                        "exclude_from_taxation": true,
                                        "quantity": 1,
                                        "previous_charge": {
                                            "invoice_item_charge_type": "tax",
                                            "id": "9531498"
                                        },
                                        "use_original_tax_data": false,
                                        "tax_category_id": 0,
                                        "tax_lines": 0
                                    },
                                    {
                                        "invoice_item_charge_type": "manual-tax",
                                        "id": "9531516",
                                        "amount": -6.25,
                                        "balance": -6.25,
                                        "paid": true,
                                        "un_prorated_amount": -6.25,
                                        "price_category": {
                                            "charge_category_type": "tax",
                                            "id": "2380",
                                            "name": "Tax Price Category"
                                        },
                                        "description": "Tax Price Category",
                                        "exclude_from_taxation": true,
                                        "quantity": 1,
                                        "previous_charge": {
                                            "invoice_item_charge_type": "tax",
                                            "id": "9531500"
                                        },
                                        "use_original_tax_data": false,
                                        "tax_category_id": 0,
                                        "tax_lines": 0
                                    },
                                    {
                                        "invoice_item_charge_type": "manual",
                                        "id": "9531518",
                                        "amount": 90,
                                        "balance": 90,
                                        "paid": false,
                                        "un_prorated_amount": 90,
                                        "price_category": {
                                            "charge_category_type": "price",
                                            "id": "2538",
                                            "name": "Price Charge Category M3"
                                        },
                                        "recurring_charge": true,
                                        "bill_in_advance": false,
                                        "description": "Price Charge Category M3",
                                        "exclude_from_taxation": false,
                                        "quantity": 1,
                                        "previous_charge": {
                                            "invoice_item_charge_type": "charge",
                                            "id": "9531490"
                                        },
                                        "tax_pcode": 3879200,
                                        "tax_code": "19-30",
                                        "use_original_tax_data": false,
                                        "tax_date": "2017-09-30T16:00:00-05:00"
                                    }
                                ],
                                "start_date": "2017-08-02T00:00:00-05:00",
                                "end_date": "2017-09-02T00:00:00-05:00",
                                "previous_item": {
                                    "invoice_item_type": "service",
                                    "id": "8307960"
                                },
                                "manual_type": "ADHOC",
                                "reason": {
                                    "reason_type": "manual-invoice",
                                    "id": "1942",
                                    "name": "Default Manual Invoice Reason"
                                },
                                "service": {
                                    "id": "2096366"
                                }
                            }
                        ],
                        "auto_payment_date": "2018-03-19",
                        "disputed": false
                    }
                ]
            }
        ],
        "auto_approve": false,
        "reason": {
            "reason_type": "manual-invoice",
            "id": "1942",
            "name": "Default Manual Invoice Reason"
        }
    }
  4. Get information about newly created bill batch by bill batch run ID:
    GET /billing/2/bill-batch-runs/{bill_batch_run_id}
    Example
    GET https://example-tract-api.com/billing/2/bill-batch-runs/1077710

    Response

    Look for “status:” “PROCESSING” to ensure bill batch has completed running.

    {
        "bill_run_type": "batch",
        "id": "1077710",
        "sequence": 1,
        "step": "GENERATE_KPIS",
        "step_status": "COMPLETED",
        "status_date": "2018-02-22T16:25:14-06:00",
        "open_date": "2018-02-22T04:58:45-06:00",
        "close_date": "2018-02-22T04:58:45-06:00",
        "scheduled_run_date": "2018-02-22T16:25:11-06:00",
        "processed_invoice_count": 1,
        "invoice_date": "2018-02-22T04:58:45-06:00",
        "use_payment_term": true,
        "status": "APPROVAL",
        "invoices": [
            {
                "invoice_type": "manual",
                "id": "754150",
                "amount": -0.07,
                "status": "PROCESSING",
                "invoice_num": "115234833",
                "billing_account": {
                    "id": "1424664",
                    "account_num": "316",
                    "external_account_num": null
                },
                "occurred_on": "2018-02-22T04:58:45-06:00",
                "due_date": "2018-03-24",
                "amount_to_pay": -0.07,
                "late_fee_charged": false,
                "invoice_items": [
                    {
                        "invoice_item_type": "manual-service",
                        "id": "8307966",
                        "quantity": 1,
                        "taxable": true,
                        "unit_amount": -0.07,
                        "total_amount": -0.07,
                        "prorated_percentage": 100,
                        "charges": [
                            {
                                "invoice_item_charge_type": "manual",
                                "id": "9531510",
                                "amount": -100,
                                "balance": -100,
                                "paid": true,
                                "un_prorated_amount": -100,
                                "price_category": {
                                    "charge_category_type": "price",
                                    "id": "2538",
                                    "name": "Price Charge Category M3"
                                },
                                "recurring_charge": true,
                                "bill_in_advance": false,
                                "description": "Price Charge Category M3",
                                "exclude_from_taxation": true,
                                "quantity": 1,
                                "previous_charge": {
                                    "invoice_item_charge_type": "charge",
                                    "id": "9531490"
                                },
                                "use_original_tax_data": false
                            },
                            {
                                "invoice_item_charge_type": "manual-tax",
                                "id": "9531512",
                                "amount": -1,
                                "balance": -1,
                                "paid": true,
                                "un_prorated_amount": -1,
                                "price_category": {
                                    "charge_category_type": "tax",
                                    "id": "2380",
                                    "name": "Tax Price Category"
                                },
                                "description": "Tax Price Category",
                                "exclude_from_taxation": true,
                                "quantity": 1,
                                "previous_charge": {
                                    "invoice_item_charge_type": "tax",
                                    "id": "9531496"
                                },
                                "use_original_tax_data": false,
                                "tax_category_id": 0,
                                "tax_lines": 0
                            },
                            {
                                "invoice_item_charge_type": "manual-tax",
                                "id": "9531514",
                                "amount": -1,
                                "balance": -1,
                                "paid": true,
                                "un_prorated_amount": -1,
                                "price_category": {
                                    "charge_category_type": "tax",
                                    "id": "2380",
                                    "name": "Tax Price Category"
                                },
                                "description": "Tax Price Category",
                                "exclude_from_taxation": true,
                                "quantity": 1,
                                "previous_charge": {
                                    "invoice_item_charge_type": "tax",
                                    "id": "9531498"
                                },
                                "use_original_tax_data": false,
                                "tax_category_id": 0,
                                "tax_lines": 0
                            },
                            {
                                "invoice_item_charge_type": "manual-tax",
                                "id": "9531516",
                                "amount": -6.25,
                                "balance": -6.25,
                                "paid": true,
                                "un_prorated_amount": -6.25,
                                "price_category": {
                                    "charge_category_type": "tax",
                                    "id": "2380",
                                    "name": "Tax Price Category"
                                },
                                "description": "Tax Price Category",
                                "exclude_from_taxation": true,
                                "quantity": 1,
                                "previous_charge": {
                                    "invoice_item_charge_type": "tax",
                                    "id": "9531500"
                                },
                                "use_original_tax_data": false,
                                "tax_category_id": 0,
                                "tax_lines": 0
                            },
                            {
                                "invoice_item_charge_type": "manual",
                                "id": "9531518",
                                "amount": 90,
                                "balance": 90,
                                "paid": false,
                                "un_prorated_amount": 90,
                                "price_category": {
                                    "charge_category_type": "price",
                                    "id": "2538",
                                    "name": "Price Charge Category M3"
                                },
                                "recurring_charge": true,
                                "bill_in_advance": false,
                                "description": "Price Charge Category M3",
                                "exclude_from_taxation": false,
                                "quantity": 1,
                                "previous_charge": {
                                    "invoice_item_charge_type": "charge",
                                    "id": "9531490"
                                },
                                "tax_pcode": 3879200,
                                "tax_code": "19-30",
                                "use_original_tax_data": false,
                                "tax_date": "2017-09-30T16:00:00-05:00"
                            },
                            {
                                "invoice_item_charge_type": "tax",
                                "id": "9531520",
                                "amount": 1.75,
                                "balance": 1.75,
                                "paid": false,
                                "price_category": {
                                    "charge_category_type": "tax",
                                    "id": "2380",
                                    "name": "Tax Price Category"
                                },
                                "description": "Sales Tax",
                                "exclude_from_taxation": false,
                                "quantity": 1,
                                "tax_category_id": 0,
                                "tax_description": "Sales Tax",
                                "tax_code": "19-30",
                                "tax_level": "Local",
                                "tax_rate": 0.0175
                            },
                            {
                                "invoice_item_charge_type": "tax",
                                "id": "9531522",
                                "amount": 6.26,
                                "balance": 6.26,
                                "paid": false,
                                "price_category": {
                                    "charge_category_type": "tax",
                                    "id": "2380",
                                    "name": "Tax Price Category"
                                },
                                "description": "Sales Tax",
                                "exclude_from_taxation": false,
                                "quantity": 1,
                                "tax_category_id": 0,
                                "tax_description": "Sales Tax",
                                "tax_code": "19-30",
                                "tax_level": "State",
                                "tax_rate": 0.0625
                            },
                            {
                                "invoice_item_charge_type": "tax",
                                "id": "9531524",
                                "amount": 9.99,
                                "balance": 9.99,
                                "paid": false,
                                "price_category": {
                                    "charge_category_type": "tax",
                                    "id": "2380",
                                    "name": "Tax Price Category"
                                },
                                "description": "FUSF (VoIP)",
                                "exclude_from_taxation": false,
                                "quantity": 1,
                                "tax_category_id": 0,
                                "tax_description": "FUSF (VoIP)",
                                "tax_code": "19-30",
                                "tax_level": "Federal",
                                "tax_rate": 0.171
                            },
                            {
                                "invoice_item_charge_type": "tax",
                                "id": "9531526",
                                "amount": 0.18,
                                "balance": 0.18,
                                "paid": false,
                                "price_category": {
                                    "charge_category_type": "tax",
                                    "id": "2380",
                                    "name": "Tax Price Category"
                                },
                                "description": "FCC Regulatory Fee (VoIP)",
                                "exclude_from_taxation": false,
                                "quantity": 1,
                                "tax_category_id": 0,
                                "tax_description": "FCC Regulatory Fee (VoIP)",
                                "tax_code": "19-30",
                                "tax_level": "Federal",
                                "tax_rate": 0.00302
                            }
                        ],
                        "start_date": "2017-08-02T00:00:00-05:00",
                        "end_date": "2017-09-02T00:00:00-05:00",
                        "previous_item": {
                            "invoice_item_type": "service",
                            "id": "8307960"
                        },
                        "manual_type": "ADHOC",
                        "reason": {
                            "reason_type": "manual-invoice",
                            "id": "1942",
                            "name": "Default Manual Invoice Reason"
                        },
                        "service": {
                            "id": "2096366"
                        }
                    }
                ],
                "billing_statement": {
                    "statement_type": "adhoc-statement",
                    "id": "576238",
                    "service_charges": -10,
                    "activity_charges": 0,
                    "other_charges_and_credits": 0,
                    "taxes_and_fees": 9.93,
                    "total_current_charges": -0.07
                },
                "auto_payment_date": "2018-03-19",
                "disputed": false
            }
        ]
    }
  5. Run bill batch if "auto_run" was set to be “false” in step #3:
    POST /billing/2/bill-batch-runs/{bill_batch_run_id}/run
    Example
    POST https://example-tract-api.com/billing/2/bill-batch-runs/1077710/run

    Payload

    {
        "scheduled_date": "2018-02-26T17:42:50.320Z",
        "bill_run_type": "batch",
        "invoice_date": "2018-02-26T10:58:45.278Z",
        "invoice_due_date": "2018-03-26T17:42:50.320Z",
        "use_payment_term": true
    }

    Response

    Empty - 204 No Response
  6. Approve bill batch if "auto_approve" was set to “false” in step #3:
    POST /billing/2/bill-batch-runs/{bill_batch_run_id}/approve
    Example
    POST https://example-tract-api.com/billing/2/bill-batch-runs/1077710/approve

    Response

    Empty - 204 No Response
  7. Cancel bill batch if it is already run, but not yet approved:
    POST /billing/2/bill-batch-runs/{bill_batch_run_id}/cancel
    Example
    POST https://example-tract-api.com/billing/2/bill-batch-runs/1077710/cancel

    Response

    Empty - 204 No Response
  8. Delete bill batch if its bill batch run is already canceled:
    DELETE /billing/2/bill-batches/{bill_batch _id}
    Example
    DELETE https://example-tract-api.com/billing/2/bill-batches/11454

    Response

    Empty - 204 No Response

Ad Hoc Manual Invoice Reference Information

Additional Relevant Endpoints

  • GET /invoices
  • GET /invoices/{id}
  • GET /invoice-items
  • GET /invoice-items/{id}
  • GET /invoices/{id}/items/{invoice_item_id}
  • GET /invoices/{id}/items
  • GET /invoice-item-charges
  • GET /invoice-item-charges/{id}
  • GET /invoices/{id}/items/{invoice_item_id}/charges/{invoice_item_charge_id}
  • GET /invoices/{id}/items/{invoice_item_id}/charges
  • GET /invoices/{invoice_id}/items/{invoice_item_id}/charges
  • GET /billing-accounts/{id}/adhoc-bill-batches/{adhoc_bill_batch_id}
  • GET /bill-batch-runs
  • GET /bill-batch-runs/{id}

Payload Values

The following table shows a matrix of payload values for Ad Hoc invoice_item_type and Ad Hoc invoice_item_charge_type fields.

Description source invoice_item.type source invoice_item_charge.type manual invoice_item.type manual invoice_item_charge.type
Manual Debit adjustment charge adjustment charge manual-adjustment manual
Manual Debit adjustment tax-Reverse, Reissue adjustment tax manual-adjustment manual-tax
Manual One time product charge product one-time-price manual-product manual-one-time-price
Manual One time product scheduled charge product one-time-price manual-product manual-one-time-price
Manual One time product tax-Reverse, Reissue product tax manual-product manual-tax
Manual Additional fee additional-fee additional-fee manual-additional-fee manual-additional-fee
Manual Additional fee tax-Reverse, Reissue additional-fee tax manual-additional-fee manual-tax
Manual Service credit recurring charge service-credit charge manual-service-credit manual
Manual Service credit discount service-credit discount manual-service-credit manual-discount
Manual Service credit tax-Reverse, Reissue service-credit tax manual-service-credit manual-tax
Manual Service one-time charge service charge manual-service manual
Manual Service recurring charge service charge manual-service manual
Manual Service recurring discount service discount manual-service manual-discount
Manual Service one-time discount service discount manual-service manual-discount
Manual Service tax-Reverse, Reissue service tax manual-service manual-tax
Manual Usage charge usage usage manual-usage manual-usage
Manual Usage tax-Reverse, Reissue usage tax manual-usage manual-tax
Top