Create a Manual Charge

You can create a manual charge 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 such as the reason, dates, description, invoicing service group, 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 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 must be updated to POSTED before it can be eligible for bill cycle or bill batch processing. Refer to Post a Manual Charge.
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. Retrieve the id and type of the source charge for use in the request payload using the following endpoint:

GET /invoice-items
An invoicing service group (optional). Retrieve the id and name of an invoicing service group from the same billing account using the following endpoint:

GET /billing_accounts/{id}/invoicing-service-groups

Request

The following is an example of a request payload for creating a new manual charge:

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
    "type": "sourced",
    "source_charge": {
        "id": "70301",
        "invoice_item_charge_type": "charge"
    },
    "description": "Rebill manual charge",
    "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"
    },
    "invoicing_service_group": {
        "id": "8433",
        "name": "Division 4"
    }
}

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.	string	Required
unit_price	The unit price of the charge.	string	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.	string	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 reason or manual invoice reason.	object	Required	Refer to Manual Charge Reasons or Manual Invoice Reasons.
id	The ID of the reason.	string	Required
name	The name of the reason.	string	Required
reason_type	The type of reason. Possible values are manual-charge or manual-invoice.	string	Required
invoicing_service_group	A reference to an invoicing service group entity from the same billing account.	object	Optional	Refer to Invoicing Service Groups.
id	The ID of the invoicing service group.	string	Optional
name	The name of the invoicing service group.	string	Optional

Response

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
    "type": "sourced",
    "id": "136535",
    "description": "Rebill manual charge",
    "status": "DRAFT",
    "quantity": 5,
    "amount": 625,
    "taxable": false,
    "unit_price": 125,
    "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"
    },
    "invoicing_service_group": {
        "id": "8433",
        "name": "Division 4"
    }
}

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 entity 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.
invoicing_service_group — The invoicing service group the generated charge will be assigned to and invoiced with:
- id: The ID of the invoicing service group.
- name: The name of the invoicing service group.

Next Steps

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

Topic Updated: 4/2025.