Skip to main content
POST
/
invoice_line_items
Create invoice line item
curl --request POST \
  --url https://api.withorb.com/v1/invoice_line_items \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "start_date": "2023-09-22",
  "end_date": "2023-09-22",
  "quantity": 1,
  "invoice_id": "4khy3nwzktxv7",
  "name": "Item Name",
  "amount": "12.00",
  "item_id": "4khy3nwzktxv7"
}'
{
  "amount": "7.00",
  "discount": {
    "discount_type": "percentage",
    "applies_to_price_ids": [
      "h74gfhdjvn7ujokd",
      "7hfgtgjnbvc3ujkl"
    ],
    "filters": [
      {
        "field": "price_id",
        "operator": "includes",
        "values": [
          "<any>"
        ]
      }
    ],
    "reason": "<string>",
    "percentage_discount": 0.15
  },
  "end_date": "2022-02-01T08:00:00+00:00",
  "grouping": "<string>",
  "minimum": {
    "minimum_amount": "<string>",
    "filters": [
      {
        "field": "price_id",
        "operator": "includes",
        "values": [
          "<any>"
        ]
      }
    ],
    "applies_to_price_ids": [
      "<string>"
    ]
  },
  "minimum_amount": "<string>",
  "maximum": {
    "maximum_amount": "<string>",
    "filters": [
      {
        "field": "price_id",
        "operator": "includes",
        "values": [
          "<any>"
        ]
      }
    ],
    "applies_to_price_ids": [
      "<string>"
    ]
  },
  "maximum_amount": "<string>",
  "adjustments": [
    {
      "id": "<string>",
      "is_invoice_level": true,
      "filters": [
        {
          "field": "price_id",
          "operator": "includes",
          "values": [
            "<any>"
          ]
        }
      ],
      "applies_to_price_ids": [
        "<string>"
      ],
      "reason": "<string>",
      "replaces_adjustment_id": "<string>",
      "adjustment_type": "usage_discount",
      "usage_discount": 123,
      "amount": "<string>"
    }
  ],
  "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"
      },
      "type": "matrix",
      "scaled_quantity": 123,
      "matrix_config": {
        "dimension_values": [
          "<string>"
        ]
      }
    }
  ],
  "tax_amounts": [
    {
      "tax_rate_description": "<string>",
      "tax_rate_percentage": "<string>",
      "amount": "<string>"
    }
  ],
  "id": "<string>",
  "price": {
    "model_type": "unit",
    "unit_config": {
      "unit_amount": "<string>"
    },
    "metadata": {},
    "id": "<string>",
    "name": "<string>",
    "external_price_id": "<string>",
    "replaces_price_id": "<string>",
    "price_type": "usage_price",
    "created_at": "2023-11-07T05:31:56Z",
    "cadence": "one_time",
    "billing_mode": "in_advance",
    "billing_cycle_configuration": {
      "duration": 123,
      "duration_unit": "day"
    },
    "invoicing_cycle_configuration": {
      "duration": 123,
      "duration_unit": "day"
    },
    "billable_metric": {
      "id": "<string>"
    },
    "dimensional_price_configuration": {
      "dimensional_price_group_id": "<string>",
      "dimension_values": [
        "<string>"
      ]
    },
    "fixed_price_quantity": 123,
    "plan_phase_order": 123,
    "currency": "<string>",
    "conversion_rate": 123,
    "conversion_rate_config": {
      "conversion_rate_type": "unit",
      "unit_config": {
        "unit_amount": "<string>"
      }
    },
    "item": {
      "id": "<string>",
      "name": "<string>"
    },
    "credit_allocation": {
      "currency": "<string>",
      "allows_rollover": true,
      "custom_expiration": {
        "duration": 123,
        "duration_unit": "day"
      }
    },
    "composite_price_filters": [
      {
        "field": "price_id",
        "operator": "includes",
        "values": [
          "<any>"
        ]
      }
    ],
    "discount": {
      "discount_type": "percentage",
      "applies_to_price_ids": [
        "h74gfhdjvn7ujokd",
        "7hfgtgjnbvc3ujkl"
      ],
      "filters": [
        {
          "field": "price_id",
          "operator": "includes",
          "values": [
            "<any>"
          ]
        }
      ],
      "reason": "<string>",
      "percentage_discount": 0.15
    },
    "minimum": {
      "minimum_amount": "<string>",
      "filters": [
        {
          "field": "price_id",
          "operator": "includes",
          "values": [
            "<any>"
          ]
        }
      ],
      "applies_to_price_ids": [
        "<string>"
      ]
    },
    "minimum_amount": "<string>",
    "maximum": {
      "maximum_amount": "<string>",
      "filters": [
        {
          "field": "price_id",
          "operator": "includes",
          "values": [
            "<any>"
          ]
        }
      ],
      "applies_to_price_ids": [
        "<string>"
      ]
    },
    "maximum_amount": "<string>"
  },
  "usage_customer_ids": [
    "<string>"
  ],
  "filter": "<string>"
}

Authorizations

​
Authorization
string
header
required

API Keys can be issued in the Orb's web application.

Body

application/json
​
start_date
string<date>
required

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

Examples:

"2023-09-22"

​
end_date
string<date>
required

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

Examples:

"2023-09-22"

​
quantity
number
required

The number of units on the line item

Examples:

1

​
invoice_id
string
required

The id of the Invoice to add this line item.

Examples:

"4khy3nwzktxv7"

​
amount
string
required

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

Examples:

"12.00"

​
name
string | null

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.

Examples:

"Item Name"

​
item_id
string | null

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.

Examples:

"4khy3nwzktxv7"

Response

Created

​
amount
string
required

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

Examples:

"7.00"

​
discount
object | null
required
deprecated

This field is deprecated in favor of adjustments

  • PercentageDiscount
  • TrialDiscount
  • UsageDiscount
  • AmountDiscount
​
end_date
string<date-time>
required

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

Examples:

"2022-02-01T08:00:00+00:00"

​
grouping
string | null
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.

​
minimum
object | null
required
deprecated

This field is deprecated in favor of adjustments.

​
minimum_amount
string | null
required
deprecated

This field is deprecated in favor of adjustments.

​
maximum
object | null
required
deprecated

This field is deprecated in favor of adjustments.

​
maximum_amount
string | null
required
deprecated

This field is deprecated in favor of adjustments.

​
adjustments
Adjustments · array
required

All adjustments applied to the line item in the order they were applied based on invoice calculations (ie. usage discounts -> amount discounts -> percentage discounts -> minimums -> maximums).

  • MonetaryUsageDiscountAdjustment
  • MonetaryAmountDiscountAdjustment
  • MonetaryPercentageDiscountAdjustment
  • MonetaryMinimumAdjustment
  • MonetaryMaximumAdjustment
​
name
string
required

The name of the price associated with this line item.

Examples:

"Fixed Fee"

​
quantity
number
required

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

Examples:

1

​
start_date
string<date-time>
required

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

Examples:

"2022-02-01T08:00:00+00:00"

​
subtotal
string
required

The line amount before any adjustments.

Examples:

"9.00"

​
adjusted_subtotal
string
required

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

Examples:

"5.00"

​
credits_applied
string
required

The number of prepaid credits applied.

Examples:

"6.00"

​
partially_invoiced_amount
string
required

Any amount applied from a partial invoice

Examples:

"4.00"

​
sub_line_items
Sub Line Items · array
required

For complex pricing structures, the line item can be broken down further in sub_line_items.

  • MatrixSubLineItem
  • TierSubLineItem
  • OtherSubLineItem
​
tax_amounts
TaxAmount · object[]
required

An array of tax rates and their incurred tax amounts. Empty if no tax integration is configured.

​
id
string
required

A unique ID for this line item.

​
price
object
required

The Price resource represents a price that can be billed on a subscription, resulting in a charge on an invoice in the form of an invoice line item. Prices take a quantity and determine an amount to bill.

Orb supports a few different pricing models out of the box. Each of these models is serialized differently in a given Price object. The model_type field determines the key for the configuration object that is present.

For more on the types of prices, see the core concepts documentation

  • UnitPrice
  • TieredPrice
  • BulkPrice
  • BulkWithFiltersPrice
  • PackagePrice
  • MatrixPrice
  • ThresholdTotalAmountPrice
  • TieredPackagePrice
  • TieredWithMinimumPrice
  • GroupedTieredPrice
  • TieredPackageWithMinimumPrice
  • PackageWithAllocationPrice
  • UnitWithPercentPrice
  • MatrixWithAllocationPrice
  • TieredWithProrationPrice
  • UnitWithProrationPrice
  • GroupedAllocationPrice
  • BulkWithProrationPrice
  • GroupedWithProratedMinimumPrice
  • GroupedWithMeteredMinimumPrice
  • GroupedWithMinMaxThresholdsPrice
  • MatrixWithDisplayNamePrice
  • GroupedTieredPackagePrice
  • MaxGroupTieredPackagePrice
  • ScalableMatrixWithUnitPricingPrice
  • ScalableMatrixWithTieredPricingPrice
  • CumulativeGroupedBulkPrice
  • MinimumCompositePrice
  • PercentCompositePrice
  • EventOutputPrice
​
usage_customer_ids
string[] | null
required

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

​
filter
string | null
required

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

⌘I