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-12-25",
  "end_date": "2023-12-25",
  "quantity": 123,
  "invoice_id": "<string>",
  "amount": "<string>",
  "name": "Item Name",
  "item_id": "4khy3nwzktxv7"
}
'

import requests

url = "https://api.withorb.com/v1/invoice_line_items"

payload = {
    "start_date": "2023-12-25",
    "end_date": "2023-12-25",
    "quantity": 123,
    "invoice_id": "<string>",
    "amount": "<string>",
    "name": "Item Name",
    "item_id": "4khy3nwzktxv7"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    start_date: '2023-12-25',
    end_date: '2023-12-25',
    quantity: 123,
    invoice_id: '<string>',
    amount: '<string>',
    name: 'Item Name',
    item_id: '4khy3nwzktxv7'
  })
};

fetch('https://api.withorb.com/v1/invoice_line_items', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.withorb.com/v1/invoice_line_items",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'start_date' => '2023-12-25',
    'end_date' => '2023-12-25',
    'quantity' => 123,
    'invoice_id' => '<string>',
    'amount' => '<string>',
    'name' => 'Item Name',
    'item_id' => '4khy3nwzktxv7'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.withorb.com/v1/invoice_line_items"

	payload := strings.NewReader("{\n  \"start_date\": \"2023-12-25\",\n  \"end_date\": \"2023-12-25\",\n  \"quantity\": 123,\n  \"invoice_id\": \"<string>\",\n  \"amount\": \"<string>\",\n  \"name\": \"Item Name\",\n  \"item_id\": \"4khy3nwzktxv7\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.withorb.com/v1/invoice_line_items")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"start_date\": \"2023-12-25\",\n  \"end_date\": \"2023-12-25\",\n  \"quantity\": 123,\n  \"invoice_id\": \"<string>\",\n  \"amount\": \"<string>\",\n  \"name\": \"Item Name\",\n  \"item_id\": \"4khy3nwzktxv7\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.withorb.com/v1/invoice_line_items")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"start_date\": \"2023-12-25\",\n  \"end_date\": \"2023-12-25\",\n  \"quantity\": 123,\n  \"invoice_id\": \"<string>\",\n  \"amount\": \"<string>\",\n  \"name\": \"Item Name\",\n  \"item_id\": \"4khy3nwzktxv7\"\n}"

response = http.request(request)
puts response.read_body

{
  "amount": "<string>",
  "end_date": "2023-11-07T05:31:56Z",
  "grouping": "<string>",
  "adjustments": [
    {
      "id": "<string>",
      "is_invoice_level": true,
      "filters": [
        {
          "values": [
            "<string>"
          ]
        }
      ],
      "applies_to_price_ids": [
        "<string>"
      ],
      "reason": "<string>",
      "replaces_adjustment_id": "<string>",
      "adjustment_type": "usage_discount",
      "usage_discount": 123,
      "amount": "<string>"
    }
  ],
  "name": "<string>",
  "quantity": 123,
  "start_date": "2023-11-07T05:31:56Z",
  "subtotal": "<string>",
  "adjusted_subtotal": "<string>",
  "credits_applied": "<string>",
  "partially_invoiced_amount": "<string>",
  "sub_line_items": [
    {
      "amount": "<string>",
      "name": "<string>",
      "quantity": 123,
      "grouping": {
        "key": "<string>",
        "value": "west"
      },
      "type": "matrix",
      "matrix_config": {
        "dimension_values": [
          "<string>"
        ]
      },
      "scaled_quantity": 123
    }
  ],
  "tax_amounts": [
    {
      "tax_rate_description": "<string>",
      "tax_rate_percentage": "<string>",
      "amount": "<string>"
    }
  ],
  "id": "<string>",
  "price": {
    "model_type": "unit",
    "unit_config": {
      "unit_amount": "<string>",
      "prorated": false
    },
    "metadata": {},
    "id": "<string>",
    "name": "<string>",
    "external_price_id": "<string>",
    "replaces_price_id": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "billing_cycle_configuration": {
      "duration": 123
    },
    "invoicing_cycle_configuration": {
      "duration": 123
    },
    "billable_metric": {
      "id": "<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
      },
      "filters": [
        {
          "values": [
            "<string>"
          ]
        }
      ],
      "license_type_id": "<string>"
    },
    "composite_price_filters": [
      {
        "values": [
          "<string>"
        ]
      }
    ],
    "invoice_grouping_key": "<string>",
    "discount": {
      "discount_type": "percentage",
      "percentage_discount": 0.5,
      "applies_to_price_ids": [
        "h74gfhdjvn7ujokd",
        "7hfgtgjnbvc3ujkl"
      ],
      "filters": [
        {
          "values": [
            "<string>"
          ]
        }
      ],
      "reason": "<string>"
    },
    "minimum": {
      "minimum_amount": "<string>",
      "filters": [
        {
          "values": [
            "<string>"
          ]
        }
      ],
      "applies_to_price_ids": [
        "<string>"
      ]
    },
    "minimum_amount": "<string>",
    "maximum": {
      "maximum_amount": "<string>",
      "filters": [
        {
          "values": [
            "<string>"
          ]
        }
      ],
      "applies_to_price_ids": [
        "<string>"
      ]
    },
    "maximum_amount": "<string>",
    "dimensional_price_configuration": {
      "dimensional_price_group_id": "<string>",
      "dimension_values": [
        "<string>"
      ]
    },
    "license_type": {
      "id": "<string>",
      "name": "<string>",
      "grouping_key": "<string>"
    }
  },
  "usage_customer_ids": [
    "<string>"
  ],
  "filter": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#400-constraint-violation",
  "status": 400,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#401-authentication-error",
  "status": 401,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#404-feature-not-available",
  "status": 400,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#409-resource-conflict",
  "status": 409,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#413-request-too-large",
  "status": 413,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#429-too-many-requests",
  "status": 429,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#500-internal-server-error",
  "status": 123,
  "detail": "<string>",
  "title": "<string>"
}

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

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-12-25",
  "end_date": "2023-12-25",
  "quantity": 123,
  "invoice_id": "<string>",
  "amount": "<string>",
  "name": "Item Name",
  "item_id": "4khy3nwzktxv7"
}
'

import requests

url = "https://api.withorb.com/v1/invoice_line_items"

payload = {
    "start_date": "2023-12-25",
    "end_date": "2023-12-25",
    "quantity": 123,
    "invoice_id": "<string>",
    "amount": "<string>",
    "name": "Item Name",
    "item_id": "4khy3nwzktxv7"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    start_date: '2023-12-25',
    end_date: '2023-12-25',
    quantity: 123,
    invoice_id: '<string>',
    amount: '<string>',
    name: 'Item Name',
    item_id: '4khy3nwzktxv7'
  })
};

fetch('https://api.withorb.com/v1/invoice_line_items', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.withorb.com/v1/invoice_line_items",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'start_date' => '2023-12-25',
    'end_date' => '2023-12-25',
    'quantity' => 123,
    'invoice_id' => '<string>',
    'amount' => '<string>',
    'name' => 'Item Name',
    'item_id' => '4khy3nwzktxv7'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.withorb.com/v1/invoice_line_items"

	payload := strings.NewReader("{\n  \"start_date\": \"2023-12-25\",\n  \"end_date\": \"2023-12-25\",\n  \"quantity\": 123,\n  \"invoice_id\": \"<string>\",\n  \"amount\": \"<string>\",\n  \"name\": \"Item Name\",\n  \"item_id\": \"4khy3nwzktxv7\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.withorb.com/v1/invoice_line_items")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"start_date\": \"2023-12-25\",\n  \"end_date\": \"2023-12-25\",\n  \"quantity\": 123,\n  \"invoice_id\": \"<string>\",\n  \"amount\": \"<string>\",\n  \"name\": \"Item Name\",\n  \"item_id\": \"4khy3nwzktxv7\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.withorb.com/v1/invoice_line_items")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"start_date\": \"2023-12-25\",\n  \"end_date\": \"2023-12-25\",\n  \"quantity\": 123,\n  \"invoice_id\": \"<string>\",\n  \"amount\": \"<string>\",\n  \"name\": \"Item Name\",\n  \"item_id\": \"4khy3nwzktxv7\"\n}"

response = http.request(request)
puts response.read_body

{
  "amount": "<string>",
  "end_date": "2023-11-07T05:31:56Z",
  "grouping": "<string>",
  "adjustments": [
    {
      "id": "<string>",
      "is_invoice_level": true,
      "filters": [
        {
          "values": [
            "<string>"
          ]
        }
      ],
      "applies_to_price_ids": [
        "<string>"
      ],
      "reason": "<string>",
      "replaces_adjustment_id": "<string>",
      "adjustment_type": "usage_discount",
      "usage_discount": 123,
      "amount": "<string>"
    }
  ],
  "name": "<string>",
  "quantity": 123,
  "start_date": "2023-11-07T05:31:56Z",
  "subtotal": "<string>",
  "adjusted_subtotal": "<string>",
  "credits_applied": "<string>",
  "partially_invoiced_amount": "<string>",
  "sub_line_items": [
    {
      "amount": "<string>",
      "name": "<string>",
      "quantity": 123,
      "grouping": {
        "key": "<string>",
        "value": "west"
      },
      "type": "matrix",
      "matrix_config": {
        "dimension_values": [
          "<string>"
        ]
      },
      "scaled_quantity": 123
    }
  ],
  "tax_amounts": [
    {
      "tax_rate_description": "<string>",
      "tax_rate_percentage": "<string>",
      "amount": "<string>"
    }
  ],
  "id": "<string>",
  "price": {
    "model_type": "unit",
    "unit_config": {
      "unit_amount": "<string>",
      "prorated": false
    },
    "metadata": {},
    "id": "<string>",
    "name": "<string>",
    "external_price_id": "<string>",
    "replaces_price_id": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "billing_cycle_configuration": {
      "duration": 123
    },
    "invoicing_cycle_configuration": {
      "duration": 123
    },
    "billable_metric": {
      "id": "<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
      },
      "filters": [
        {
          "values": [
            "<string>"
          ]
        }
      ],
      "license_type_id": "<string>"
    },
    "composite_price_filters": [
      {
        "values": [
          "<string>"
        ]
      }
    ],
    "invoice_grouping_key": "<string>",
    "discount": {
      "discount_type": "percentage",
      "percentage_discount": 0.5,
      "applies_to_price_ids": [
        "h74gfhdjvn7ujokd",
        "7hfgtgjnbvc3ujkl"
      ],
      "filters": [
        {
          "values": [
            "<string>"
          ]
        }
      ],
      "reason": "<string>"
    },
    "minimum": {
      "minimum_amount": "<string>",
      "filters": [
        {
          "values": [
            "<string>"
          ]
        }
      ],
      "applies_to_price_ids": [
        "<string>"
      ]
    },
    "minimum_amount": "<string>",
    "maximum": {
      "maximum_amount": "<string>",
      "filters": [
        {
          "values": [
            "<string>"
          ]
        }
      ],
      "applies_to_price_ids": [
        "<string>"
      ]
    },
    "maximum_amount": "<string>",
    "dimensional_price_configuration": {
      "dimensional_price_group_id": "<string>",
      "dimension_values": [
        "<string>"
      ]
    },
    "license_type": {
      "id": "<string>",
      "name": "<string>",
      "grouping_key": "<string>"
    }
  },
  "usage_customer_ids": [
    "<string>"
  ],
  "filter": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#400-constraint-violation",
  "status": 400,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#401-authentication-error",
  "status": 401,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#404-feature-not-available",
  "status": 400,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#409-resource-conflict",
  "status": 409,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#413-request-too-large",
  "status": 413,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#429-too-many-requests",
  "status": 429,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#500-internal-server-error",
  "status": 123,
  "detail": "<string>",
  "title": "<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.

Example:

"2023-09-22"

end_date

string<date>

required

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

Example:

"2023-09-22"

quantity

number

required

The number of units on the line item

Example:

1

invoice_id

string

required

The id of the Invoice to add this line item.

Example:

"4khy3nwzktxv7"

amount

string

required

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

Example:

"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.

Example:

"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.

Example:

"4khy3nwzktxv7"

Response

Created

amount

string

required

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

Example:

"7.00"

end_date

string<date-time>

required

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

Example:

"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.

adjustments

(MonetaryUsageDiscountAdjustment · object | MonetaryAmountDiscountAdjustment · object | MonetaryPercentageDiscountAdjustment · object | MonetaryTieredPercentageDiscountAdjustment · object | MonetaryMinimumAdjustment · object | MonetaryMaximumAdjustment · object)[]

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
MonetaryTieredPercentageDiscountAdjustment
MonetaryMinimumAdjustment
MonetaryMaximumAdjustment

Show child attributes

name

string

required

The name of the price associated with this line item.

Example:

"Fixed Fee"

quantity

number

required

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

Example:

1

start_date

string<date-time>

required

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

Example:

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

subtotal

string

required

The line amount before any adjustments.

Example:

"9.00"

adjusted_subtotal

string

required

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

Example:

"5.00"

credits_applied

string

required

The number of prepaid credits applied.

Example:

"6.00"

partially_invoiced_amount

string

required

Any amount applied from a partial invoice

Example:

"4.00"

sub_line_items

(MatrixSubLineItem · object | TierSubLineItem · object | OtherSubLineItem · object)[]

required

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

MatrixSubLineItem
TierSubLineItem
OtherSubLineItem

Show child attributes

tax_amounts

TaxAmount · object[]

required

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

Show child attributes

string

required

A unique ID for this line item.

price

UnitPrice · 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

Show child attributes

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.

Ingest events

List invoices

⌘I

API documentation

Alert

Coupon

Credit

Credit note

Customer

Dimensional Price Group

Event

Invoice

Item

LicenseType

License

Metric

Availability

Plan

Price

Subscription Change

Subscription

Price interval

Create invoice line item

Authorizations

Body

Response