v49

latestOpenAPI 3.1.0raw.githubusercontent.com2026-07-081445491.8 MB

Invoice

Create invoice line item

This creates a one-off fixed fee invoice line item on an Invoice. This can only be done for invoices that are in a draft status.

The behavior depends on which parameters are provided:

If item_id is provided without name: The item is looked up by ID, and the item's name is used for the line item.
If name is provided without item_id: An item with the given name is searched for in the account. If found, that item is used. If not found, a new item is created with that name. The new item's name is used for the line item.
If both item_id and name are provided: The item is looked up by ID for association, but the provided name is used for the line item (not the item's name).

post/invoice_line_items

Request body

start_datestring date required

A date string to specify the line item's start date in the customer's timezone.

end_datestring date required

A date string to specify the line item's end date in the customer's timezone.

quantitynumber required

The number of units on the line item

invoice_idstring required

The id of the Invoice to add this line item.

namestring nullable

The name to use for the line item. If item_id is not provided, Orb will search for an item with this name. If found, that item will be associated with the line item. If not found, a new item will be created with this name. If item_id is provided, this name will be used for the line item, but the item association will be based on item_id. At least one of name or item_id must be provided.

amountstring required

The total amount in the invoice's currency to add to the line item.

item_idstring nullable

The id of the item to associate with this line item. If provided without name, the item's name will be used for the price/line item. If provided with name, the item will be associated but name will be used for the line item. At least one of name or item_id must be provided.

Example request

{
  "start_date": "2023-09-22",
  "end_date": "2023-09-22",
  "quantity": 1,
  "invoice_id": "4khy3nwzktxv7",
  "name": "Item Name",
  "amount": "12.00",
  "item_id": "4khy3nwzktxv7"
}

Response

Created

amountstring required

The final amount for a line item after all adjustments and pre paid credits have been applied.

end_datestring date-time required

The end date of the range of time applied for this line item's price.

groupingstring nullable required

[DEPRECATED] For configured prices that are split by a grouping key, this will be populated with the key and a value. The amount and subtotal will be the values for this particular grouping.

namestring required

The name of the price associated with this line item.

quantitynumber required

Either the fixed fee quantity or the usage during the service period.

start_datestring date-time required

The start date of the range of time applied for this line item's price.

subtotalstring required

The line amount before any adjustments.

adjusted_subtotalstring required

The line amount after any adjustments and before overage conversion, credits and partial invoicing.

credits_appliedstring required

The number of prepaid credits applied.

partially_invoiced_amountstring required

Any amount applied from a partial invoice

idstring required

A unique ID for this line item.

usage_customer_idsstring[] nullable required

A list of customer ids that were used to calculate the usage for this line item.

filterstring nullable required

An additional filter that was used to calculate the usage for this line item.

Example response

{
  "amount": "7.00",
  "end_date": "2022-02-01T08:00:00+00:00",
  "name": "Fixed Fee",
  "quantity": 1,
  "start_date": "2022-02-01T08:00:00+00:00",
  "subtotal": "9.00",
  "adjusted_subtotal": "5.00",
  "credits_applied": "6.00",
  "partially_invoiced_amount": "4.00",
  "sub_line_items": [
    {
      "amount": "9.00",
      "name": "Tier One",
      "quantity": 5,
      "grouping": {
        "key": "region",
        "value": "west"
      }
    }
  ],
  "price": {
    "discount": {
      "applies_to_price_ids": [
        "h74gfhdjvn7ujokd",
        "7hfgtgjnbvc3ujkl"
      ],
      "percentage_discount": 0.15
    }
  }
}