You can create a manual charge A manual charge represents user-defined charge information for a future invoice item charge (generated charge) based on an existing invoice item charge (source charge) from the same billing account. using the following endpoint and sample payload:

POST https://example-gotransverse.com/billing/2/manual-charges

Learn what you need to know to successfully create a manual charge in the Considerations, Before You Start, Request, Response and Next Steps sections below.

Considerations

Consider the following when creating a new manual charge:

• The manual charge defines specific values of the generated charge A generated charge is an invoice item charge created based on the details of a manual charge and a source charge. such as the reason, dates, description, price, quantity, and tax eligibility. The remaining values are defined by the source charge such as the billing account, charge type, charge category, and tax code (when applicable).

• The source charge A source charge is an existing invoice item charge used as the basis for the manual charge and resulting generated charge. for the manual charge is from an invoice with an Open or Closed status.

• The source charge has an invoice item charge type of charge, manual-usage, manual-usage-discount, usage, usage-discount.

• A new manual charge is created with a DRAFT status. The status needs to be updated to POSTED before it can be eligible for bill cycle or bill batch processing.

• Taxes are calculated for manual charges only when the tenant is configured with Avalara Communications Tax, Avalara (Legacy) Tax, External Tax, or Vertex Indirect Tax O Series as the tax processor.

Before You Start

You will need the following when creating a new manual charge:

• A manual charge reason or manual invoice reason with an ACTIVE status. Note the id, name, and reason_type of the reason for use in the request payload. Refer to Manual Charge Reasons and Manual Invoice Reasons.

• A source charge on which to base the manual charge. Note the id and type of the source charge for use in the request payload.

Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
    "type": "sourced",
    "source_charge": {
        "id": "70301",
        "invoice_item_charge_type": "charge"
    },
    "description": "string",
    "status": "DRAFT",
    "quantity": "5",
    "unit_price": "125.00",
    "start_date": "2023-01-01T00:00:00-06:00",
    "end_date": "2023-02-01T00:00:00-06:00",
    "effective_date": "2023-06-02T00:00:00-06:00",
    "taxable": false,
    "reason": {
        "id": 451,
        "name": "Manual Charge Reason",
        "reason_type": "manual-charge"
    }
}

Create Manual Charge Request Fields

Name	Description	Data Type	Required or Optional	Notes
type	The type of manual charge. The available value is sourced.	string	Required
source_charge	The existing invoice item charge to source charge details from for the manual charge and the resulting generated charge.	object	Required
id	The ID of the source invoice item charge.	string	Required
invoice_item_charge_type	The type of source invoice item charge. Available values are charge, manual-usage, manual-usage-discount, usage, usage-discount.	string	Required
description	A description of the manual charge.	string	Optional
status	The status of the manual charge. Available value for a new manual charge: DRAFT.	string	Required
quantity	The quantity of the charge.	number	Required
unit_price	The unit price of the charge.	number	Required
start_date	The date and time the charge.	string	Required	Date/Time in ISO 8601 Format. ISO 8601 Examples: 2015-12-12Z, 2015-12-12T12:12+02:00, 2015-12-12T12:12:14Z, 2015-12-12T12:12:14+02:00
end_date	The date and time the charge.	string	Required	Date/Time in ISO 8601 Format. ISO 8601 Examples: 2015-12-12Z, 2015-12-12T12:12+02:00, 2015-12-12T12:12:14Z, 2015-12-12T12:12:14+02:00
effective_date	The date and time the charge is effective.	string	Required	This date determines the bill cycle in which the generated charge is invoiced. The date cannot occur in the future. Date/Time in ISO 8601 Format. ISO 8601 Examples: 2015-12-12Z, 2015-12-12T12:12+02:00, 2015-12-12T12:12:14Z, 2015-12-12T12:12:14+02:00
taxable	Specifies whether the charge is taxable: TRUE — Tax is calculated for the charge when invoiced. FALSE — Tax is not calculated for the charge.	boolean	Required	The default value is TRUE. The tax code of the source charge is used when calculating tax for the generated charge.
reason	The manual charge or manual invoice reason.	object	Required	Refer to Manual Charge Reasons or Manual Invoice Reasons.
id	The ID of the manual charge reason.	string	Required
name	The name of the manual charge reason.	string	Required
reason_type	The type of reason. Possible values are manual-charge or manual-invoice.	string	Required

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  "type": "sourced",
  "id": "136535",
  "description": "string"
  "status": "DRAFT",
  "quantity": 5,
  "amount": 625.00,
  "taxable": false,
  "unit_price": 125.00,
  "start_date": "2023-01-01T00:00:00-06:00",
  "end_date": "2023-02-01T00:00:00-06:00",
  "effective_date": "2023-06-02T01:00:00-05:00",
  "reason": {
    "reason_type": "manual-charge",
    "id": "451",
    "name": "Manual Charge Reason"
  },
  "source_charge": {
    "invoice_item_charge_type": "charge",
    "id": "70301"
  }
}

The following fields are returned when a new manual charge is successfully created:

• type — The type of manual charge. The available value is source.

• id — The ID of the manual charge.

• description — A description of the manual charge.

• status — The status of the manual charge. New manual charges are created with a DRAFT status.

• quantity — The quantity of the charge.

• amount — The amount of the charge.

• taxable — Specifies whether the charge is taxable:

  • true: Tax is calculated for the charge when invoiced.

  • false: Tax is not calculated for the charge when invoiced.

• unit_price — The unit price of the charge.

• start_date — The date and time the charge starts.

• end_date — The date and time the charge ends.

• effective_date — The date and time the manual charge becomes effective. This date determines the bill cycle in which the charge is generated and invoiced.

• reason — The reason for the manual charge.

  • reason_type: The type of reason. Possible values are manual-charge and manual-invoice.

  • id: The ID of the reason.

  • name: The name of the reason.

• source_charge — The invoice item charge object the manual charge is based on:

  • invoice_item_charge_type: The type of source invoice item charge. Possible values are charge, manual-usage, manual-usage-discount, usage, usage-discount.

  • id: The ID of the source invoice item charge.

Next Steps

Once the manual charge is created, you can change the status from Draft to Posted using the /manual-charges/{id}/post endpoint. Alternatively, you can delete a manual charge with a Draft status.

Related Topics

• Post a Manual Charge

• Delete a Manual Charge

• Query Manual Charge Reasons

• Query Manual Invoice Reasons

Topic Updated: 7/2024.