Adding External Invoice Charges and Supporting Documents to an Invoice

You can add externally calculated charges to an invoice so that each invoice includes the appropriate charges and discounts expected by customers. It allows support of more complex invoice calculation and discount strategies even when the data and process calculations do not reside within Gotransverse.

To add externally calculated fees to an invoice, the associated bill cycle must have the Include External Charges check box selected. After calculating all standard invoice charges, the bill cycle run moves to Paused status at which point you can add the external charges with API 2.0.

Adding External Charges to an Invoice

To add external charges to the invoice with API 2.0, run the following endpoints:

  1. Run the bill cycle and wait until it moves to Paused status:
    1. Retrieve a list bill cycle runs and find the first one in Ready status:
      GET bill-cycle-runs?bill_cycle_name=bill-cycle-external-sample&step_status=READY

      Note: You can use the following query parameters: id, bill_cycle_id, bill_cycle_name, open_date, close_date, status. The following parameters must be used together with parameters from the previous list: sequence, step_status, step.
      For example: GET /bill-cycles?name=bill-cycle-external-sample&step= AVAILABLE

      Sample response

      {
      "bill_run_type": "cycle",
      "id": "2352948",
      "sequence": 5,
      "step": "AVAILABLE",
      "step_status": "READY",
      "status_date": "2020-03-13T07:06:11-05:00",
      "open_date": "2020-03-12T00:00:00-05:00",
      "close_date": "2020-03-13T00:00:00-05:00",
      "processed_invoice_count": 0,
      "use_payment_term": false,
      "status": "READY",
      "bill_cycle": {
      	"bill_cycle_type": "daily",
      	"id": "30854",
      	"name": "bill-cycle-external"
      }
      }

    2. To execute the bill cycle, in the request body, enter the needed data:
      POST /bill-cycle-runs/{id}/run

      Request body

      {
      "scheduled_date": "2020-04-15T11:22:30.438Z",
      "invoice_date": "2020-03-13T11:22:30.438Z",
      "invoice_due_date": "2020-04-15T11:22:30.438Z",
      "use_payment_term": true
      }							

    3. Retrieve this bill cycle run by ID and make sure it’s in Paused status:
      GET /bill-cycle-runs/{id}

      Response sample

      {
      "bill_run_type": "cycle",
      "id": "2352948",
      "sequence": 5,
      "step": "EXTERNAL_CHARGES",
      "step_status": "PAUSED",
      "status_date": "2020-04-15T06:23:41-05:00",
      "open_date": "2020-03-12T00:00:00-05:00",
      "close_date": "2020-03-13T00:00:00-05:00",
      "scheduled_run_date": "2020-04-15T06:23:31-05:00",
      "processed_invoice_count": 1,
      "invoice_date": "2020-03-13T06:22:30-05:00",
      "use_payment_term": true,
      "status": "READY",
      "bill_cycle": {
      	 "bill_cycle_type": "daily",
      	 "id": "30854",
      	 "name": "bill-cycle-external"
      }
      }

  2. Retrieve the available invoices for the paused bill cycle run and note the ID of the one to which you want to add the external fees:
    GET /bill-cycle-runs/{id}/invoices

    Response sample

    [
    {
    "invoice_type": "standard",
    "id": "874112",
    "amount": 250.00,
    "status": "DRAFT",
    "invoice_num": "116907436",
    "external_invoice_num": null,
    "billing_account": {
    	"id": "1511862",
    	"account_num": "Dpref3329",
    	"external_account_num": null
    },
    "occurred_on": "2020-03-12T00:00:00-05:00",
    "due_date": "2020-03-12",
    "amount_to_pay": 250.00,
    "late_fee_charged": false,
    "invoice_items": [
    {
    	"invoice_item_type": "service",
    	"id": "16215636",
    	"quantity": 1.00000,
    	"description": "Sample Subscription Product #1",
    	"taxable": false,
    	"service": {
    		"id": "2310910"
    	},
    	"unit_amount": 50.00,
    	"total_amount": 50.00,
    	"prorated_percentage": 100.00000,
    	"charges": [
    		{
    		"invoice_item_charge_type": "charge",
    		"id": "17621550",
    		"amount": 50.00,
    		"balance": 50.00,
    		"paid": false,
    		"details": [],
    		"un_prorated_amount": 50.00000,
    		"price_category": {
    			"charge_category_type": "price",
    			"id": "6176",
    			"name": "Sample Price Charge Category #1"
    		},
    		"recurring_charge": true,
    		"bill_in_advance": true,
    		"description": "Sample Price Charge Category #1",
    		"exclude_from_taxation": false,
    		"quantity": 1.00000,
    		"tax_inclusive": false
    	}
    	],
    	"start_date": "2020-03-12T00:00:00-05:00",
    	"end_date": "2020-03-13T00:00:00-05:00"
    },
    {
    "invoice_item_type": "service",
    "id": "16215638",
    "quantity": 1.00000,
    "description": "Sample Subscription Product #1",
    "taxable": false,
    "service": {
    	"id": "2311058"
    },
    "unit_amount": 50.00,
    "total_amount": 50.00,
    "prorated_percentage": 100.00000,
    "charges": [
    {
    	"invoice_item_charge_type": "charge",
    	"id": "17621552",
    	"amount": 50.00,
    	"balance": 50.00,
    	"paid": false,
        "details": [],
    	"un_prorated_amount": 50.00000,
    	"price_category": {
    		"charge_category_type": "price",
    		"id": "6176",
    		"name": "Sample Price Charge Category #1"
    	},
    	"recurring_charge": true,
    	"bill_in_advance": true,
    	"description": "Sample Price Charge Category #1",
    	"exclude_from_taxation": false,
    	"quantity": 1.00000,
    	"tax_inclusive": false
    }
    ],
    "start_date": "2020-03-11T00:00:00-05:00",
    "end_date": "2020-03-12T00:00:00-05:00"
    },
    {
    "invoice_item_type": "service",
    "id": "16215640",
    "quantity": 1.00000,
    "description": "Sample Subscription Product #1",
    "taxable": false,
    "service": {
    	"id": "2311058"
    },
    "unit_amount": 50.00,
    "total_amount": 50.00,
    "prorated_percentage": 100.00000,
    	"charges": [
    	{
    		"invoice_item_charge_type": "charge",
    		"id": "17621554",
    			"amount": 50.00,
    			"balance": 50.00,
    			"paid": false,
    			"details": [],
    			"un_prorated_amount": 50.00000,
    			"price_category": {
    				"charge_category_type": "price",
    				"id": "6176",
    				"name": "Sample Price Charge Category #1"
    			},
    		"recurring_charge": true,
    		"bill_in_advance": true,
    		"description": "Sample Price Charge Category #1",
    		"exclude_from_taxation": false,
    		"quantity": 1.00000,
    		"tax_inclusive": false
    	}
    	],
    "start_date": "2020-03-12T00:00:00-05:00",
    "end_date": "2020-03-13T00:00:00-05:00"
    },
    {
    "invoice_item_type": "service",
    "id": "16215642",
    "quantity": 1.00000,
    "description": "Sample Subscription Product #1",
    "taxable": false,
    "service": {
    	"id": "2312918"
    },
    "unit_amount": 50.00,
    "total_amount": 50.00,
    "prorated_percentage": 100.00000,
    "charges": [
    {
    	"invoice_item_charge_type": "charge",
    	"id": "17621556",
    	"amount": 50.00,
    	"balance": 50.00,
    	"paid": false,
    	"details": [],
    	"un_prorated_amount": 50.00000,
    	"price_category": {
    		"charge_category_type": "price",
    		"id": "6176",
    		"name": "Sample Price Charge Category #1"
    },
    "recurring_charge": true,
    "bill_in_advance": true,
    "description": "Sample Price Charge Category #1",
    "exclude_from_taxation": false,
    "quantity": 1.00000,
    "tax_inclusive": false
    }
    ],
    "start_date": "2020-03-11T00:00:00-05:00",
    "end_date": "2020-03-12T00:00:00-05:00"
    },
    {
    "invoice_item_type": "service",
    "id": "16215644",
    "quantity": 1.00000,
    "description": "Sample Subscription Product #1",
    "taxable": false,
    "service": {
    	"id": "2312918"
    },
    	"unit_amount": 50.00,
    	"total_amount": 50.00,
    	"prorated_percentage": 100.00000,
    	"charges": [
    	{
    		"invoice_item_charge_type": "charge",
    		"id": "17621558",
    		"amount": 50.00,
    		"balance": 50.00,
    		"paid": false,
    		"details": [],
    		"un_prorated_amount": 50.00000,
    		"price_category": {
    				"charge_category_type": "price",
    				"id": "6176",
    				"name": "Sample Price Charge Category #1"
    		},
    		"recurring_charge": true,
    		"bill_in_advance": true,
    		"description": "Sample Price Charge Category #1",
    		"exclude_from_taxation": false,
    		"quantity": 1.00000,
    		"tax_inclusive": false
    	}
    	],
    	"start_date": "2020-03-12T00:00:00-05:00",
    	"end_date": "2020-03-13T00:00:00-05:00"
    	}
    	],
    	"auto_payment_date": "2020-03-12",
    	"disputed": false,
    	"bill_cycle": {
    	    "bill_cycle_type": "daily",
    	    "id": "30854",
    	    "name": "bill-cycle-external"
    	}
    }
    ]

  3. Retrieve manual invoice reasons, find the needed one and note its ID, reason type, and name:
    GET /manual-invoice-reasons

    Sample response

    [
    {
    "reason_type": "manual-invoice",
    "id": "1952",
    "name": "Default Manual Invoice Reason",
    "description": "Default Manual Invoice Reason",
    "status": "ACTIVE"
    }
    ]

  4. Retrieve ad hoc charge categories, find the needed one, and note its ID and name:
    GET /charge-categories?type=adhoc

    Sample response

    [
    {
    "charge_category_type": "adhoc",
    "id": "3546",
    "name": "Adhoc category",
    "description": "default",
    "priority": 22,
    "status": "ACTIVE"
    },
    {
    "charge_category_type": "adhoc",
    "id": "4204",
    "name": "Adhoc Category1",
    "priority": 27,
    "status": "ACTIVE"
    },
    {
    "charge_category_type": "adhoc",
    "id": "6134",
    "name": "SZH Adhoc Category#1",
    "priority": 66,
    "status": "ACTIVE"
    }
    ]

    Response sample

    {
    "invoice_items": [
    {
    	"status_code": 201,
    	"invoice_item": {
    		"invoice_item_type": "manual-adhoc",
    		"id": "16215652",
    		"quantity": 1,
    		"description": "description",
    		"taxable": true,
    		"unit_amount": 100.00,
    		"total_amount": 100.00,
    		"charges": [
    		{
    			"invoice_item_charge_type": "manual-adhoc",
    			"id": "17621566",
    			"amount": 100.00,
    			"balance": 100.00,
    			"paid": false,
    			"details": [],
    			"un_prorated_amount": 100,
    			"price_category": {
    				"charge_category_type": "adhoc",
    				"id": "3546",
    				"name": "Adhoc category"
    			},
    			"description": "Adhoc category",
    			"exclude_from_taxation": false,
    			"quantity": 1,
    			"tax_inclusive": false,
    			"use_original_tax_data": false
    			}
    			],
    			"start_date": "2018-01-01T04:37:21-06:00",
    			"end_date": "2020-07-07T05:37:21-05:00",
    			"manual_type": "ADHOC",
    			"reason": {
    				"reason_type": "manual-invoice",
    				"id": "1952",
    				"name": "Default Manual Invoice Reason"
    			}
    		}
    	}
    ]
    }
  5. Add external charges to the specified invoice through the following endpoint. In the request body, specify the manual invoice reason and ad hoc charge category retrieved in Steps 3 and 4.
    POST /bill-cycle-runs/{bill_cycle_run_id}/invoices/{invoice_id}/items/bulk

    Sample request

    {
    "invoice_items" : [ {
    	"invoice_item_type" : "manual-adhoc",
    	"quantity" : 1,
    	"start_date" : "2018-01-01T12:37:21.648+02:00",
    	"end_date" : "2020-07-07T12:37:21.648+02:00",		
          "description" : "description",
    "charges" : [ {
    	"invoice_item_charge_type" : "manual-adhoc",
    	"charge_category" : {
    		"charge_category_type" : "adhoc",
    		"id": "3546",
    		"name": "Adhoc category"
    	},
    	"quantity" : 1,
    	"start_date" : "2018-01-01T12:37:21.648+02:00",
    	"end_date" : "2020-07-07T12:37:21.648+02:00",
    	"amount" : 100,
    	"exclude_from_taxation" : false
    }],
    "reason" : {
    	"reason_type" : "manual-invoice",
    	"id": "1952",
    	"name": "Default Manual Invoice Reason"
    }
    }]
    }

  6. Attach additional information to the invoice in a ZIP file, if needed.
  7. Resume the bill cycle run: POST /bill-cycle-runs/{id}/resume

Attaching a ZIP File

Supporting documentation can include any files compressed in a ZIP format. You can add only one ZIP file that doesn’t exceed the maximum allowed size. You can view the maximum ZIP size specified in the Maximum Zip File Attachment Size in MB system setting.

When you send an invoice that includes zipped documents, they are unpacked as part of the distribution process and the end-customer receives individual documents instead of a ZIP file. This way, the invoice attachments will not be blocked by email or virus detection applications and they are easy for the customer to view.

Note: Zipped files that exceed the maximum amount allowed for automatic unpacking are not unzipped during the distribution process and are delivered in ZIP format instead to the end-customer. You can view the maximum allowed size for a ZIP file to be unpacked in the following system setting: Maximum Size for Auto Unzipping Files During Email Distribution in MB.

To attach a ZIP file to an invoice:

  1. Retrieve details about the desired invoice by the associated bill cycle run:
    GET /bill-cycle-runs/{id}/invoices
  2. Enter the required parameters and execute the following endpoint:
    POST /invoices/{invoice_id}/content
    • create_content_dataRequired. Select a ZIP file to add to the invoice.
    • create_invoice_content_data_name—Enter the name of the invoice content data
    • create_invoice_content_data_description—Enter additional information for the invoice content data
    • Note: You can use any API execution tool for running this command. The following image displays Postman.

    Sample response

    {
    "invoice_content_type": "zip",
    "id": "208946",
    "name": "sample_zip",
    "description": "more information",
    "distributed": false,
    "bill_interval_run": {
    	"bill_run_type": "cycle",
    	"id": "2351724"
    }
    }
  3. If needed, you can download these charges. To download the additional charges, in the HTTP Accept header, enter ZIP, then execute the following command:
    GET /invoices/{id}/content

    Note: You can use any API execution tool for running this command. The following image displays Postman.

    With this endpoint, you can also download invoice content such as a PDF, CSV, ZIP, XML, or JSON file by the associated invoice ID. Each invoice attachment is downloaded in a separate API request. To specify the format of the file you want to download, enter the needed one in the HTTP Accept header.

    Note: If you want to delete a ZIP file, use the following endpoint:
    DELETE /invoices/{invoice_id}/content/{id}

  4. Resume the bill cycle run, then approve:
    POST /bill-cycle-runs/{id}/resume
    POST /bill-cycle-runs/{id}/approve

    Alternatively, cancel the bill cycle run to delete previously uploaded ZIP file. To generate a PDF and CSV versions of the invoice and then delete the uploaded ZIP file, resume the bill cycle run, then cancel:POST /bill-cycle-runs/{id}/cancel

The final invoice calculations, including the related taxes, if any, are applied after all associated discounts or additional fees are applied.

Note: To configure notifications sent when the bill cycle is in the statuses of Pause and Resume, use the Action Framework.