Create invoice line item

curl --request POST \
  --url https://api.useaira.com/v1/invoices/{invoiceId}/line-items \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "idempotencyKey": "<string>",
  "productId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "itemId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "startDate": "2023-12-25",
  "endDate": "2023-12-25",
  "amount": 123,
  "name": "<string>",
  "lineItemGroupId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "subLineItems": []
}
'

import requests

url = "https://api.useaira.com/v1/invoices/{invoiceId}/line-items"

payload = {
    "idempotencyKey": "<string>",
    "productId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "itemId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "startDate": "2023-12-25",
    "endDate": "2023-12-25",
    "amount": 123,
    "name": "<string>",
    "lineItemGroupId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "subLineItems": []
}
headers = {
    "X-API-KEY": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    idempotencyKey: '<string>',
    productId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    itemId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    startDate: '2023-12-25',
    endDate: '2023-12-25',
    amount: 123,
    name: '<string>',
    lineItemGroupId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    subLineItems: []
  })
};

fetch('https://api.useaira.com/v1/invoices/{invoiceId}/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.useaira.com/v1/invoices/{invoiceId}/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([
    'idempotencyKey' => '<string>',
    'productId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'itemId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'startDate' => '2023-12-25',
    'endDate' => '2023-12-25',
    'amount' => 123,
    'name' => '<string>',
    'lineItemGroupId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'subLineItems' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-KEY: <api-key>"
  ],
]);

$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.useaira.com/v1/invoices/{invoiceId}/line-items"

	payload := strings.NewReader("{\n  \"idempotencyKey\": \"<string>\",\n  \"productId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"itemId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"startDate\": \"2023-12-25\",\n  \"endDate\": \"2023-12-25\",\n  \"amount\": 123,\n  \"name\": \"<string>\",\n  \"lineItemGroupId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"subLineItems\": []\n}")

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

	req.Header.Add("X-API-KEY", "<api-key>")
	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.useaira.com/v1/invoices/{invoiceId}/line-items")
  .header("X-API-KEY", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"idempotencyKey\": \"<string>\",\n  \"productId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"itemId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"startDate\": \"2023-12-25\",\n  \"endDate\": \"2023-12-25\",\n  \"amount\": 123,\n  \"name\": \"<string>\",\n  \"lineItemGroupId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"subLineItems\": []\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.useaira.com/v1/invoices/{invoiceId}/line-items")

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

request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"idempotencyKey\": \"<string>\",\n  \"productId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"itemId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"startDate\": \"2023-12-25\",\n  \"endDate\": \"2023-12-25\",\n  \"amount\": 123,\n  \"name\": \"<string>\",\n  \"lineItemGroupId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"subLineItems\": []\n}"

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

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "idempotencyKey": "<string>",
  "customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "productId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "resourceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "licenseId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "lineItemGroupId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "scope": "credit_purchase",
  "startDate": "2023-12-25",
  "endDate": "2023-12-25",
  "totalUsage": 123,
  "usageFormat": "unit",
  "subtotalAmount": 123,
  "adjustmentAmount": 123,
  "totalAmount": 123,
  "discountAmount": 123,
  "metadata": {
    "type": "fixed",
    "billingTiming": "in_advance"
  },
  "subLineItems": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "type": "fixed_price",
      "name": "<string>",
      "description": "<string>",
      "usage": 123,
      "usageFormat": "unit",
      "amount": 123,
      "metadata": {
        "type": "fixed_price",
        "fixedPrice": 123
      }
    }
  ],
  "adjustments": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "type": "monetary_discount",
      "amount": 123
    }
  ],
  "itemId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

{
  "message": "<string>",
  "code": "<string>",
  "details": {},
  "causations": [
    {
      "message": "<string>",
      "code": "<string>",
      "details": {}
    }
  ]
}

{
  "message": "<string>"
}

{
  "message": "<string>",
  "code": "<string>",
  "details": {},
  "causations": [
    {
      "message": "<string>",
      "code": "<string>",
      "details": {}
    }
  ]
}

POST

invoices

{invoiceId}

line-items

Create invoice line item

curl --request POST \
  --url https://api.useaira.com/v1/invoices/{invoiceId}/line-items \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "idempotencyKey": "<string>",
  "productId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "itemId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "startDate": "2023-12-25",
  "endDate": "2023-12-25",
  "amount": 123,
  "name": "<string>",
  "lineItemGroupId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "subLineItems": []
}
'

import requests

url = "https://api.useaira.com/v1/invoices/{invoiceId}/line-items"

payload = {
    "idempotencyKey": "<string>",
    "productId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "itemId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "startDate": "2023-12-25",
    "endDate": "2023-12-25",
    "amount": 123,
    "name": "<string>",
    "lineItemGroupId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "subLineItems": []
}
headers = {
    "X-API-KEY": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    idempotencyKey: '<string>',
    productId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    itemId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    startDate: '2023-12-25',
    endDate: '2023-12-25',
    amount: 123,
    name: '<string>',
    lineItemGroupId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    subLineItems: []
  })
};

fetch('https://api.useaira.com/v1/invoices/{invoiceId}/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.useaira.com/v1/invoices/{invoiceId}/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([
    'idempotencyKey' => '<string>',
    'productId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'itemId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'startDate' => '2023-12-25',
    'endDate' => '2023-12-25',
    'amount' => 123,
    'name' => '<string>',
    'lineItemGroupId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'subLineItems' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-KEY: <api-key>"
  ],
]);

$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.useaira.com/v1/invoices/{invoiceId}/line-items"

	payload := strings.NewReader("{\n  \"idempotencyKey\": \"<string>\",\n  \"productId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"itemId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"startDate\": \"2023-12-25\",\n  \"endDate\": \"2023-12-25\",\n  \"amount\": 123,\n  \"name\": \"<string>\",\n  \"lineItemGroupId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"subLineItems\": []\n}")

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

	req.Header.Add("X-API-KEY", "<api-key>")
	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.useaira.com/v1/invoices/{invoiceId}/line-items")
  .header("X-API-KEY", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"idempotencyKey\": \"<string>\",\n  \"productId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"itemId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"startDate\": \"2023-12-25\",\n  \"endDate\": \"2023-12-25\",\n  \"amount\": 123,\n  \"name\": \"<string>\",\n  \"lineItemGroupId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"subLineItems\": []\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.useaira.com/v1/invoices/{invoiceId}/line-items")

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

request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"idempotencyKey\": \"<string>\",\n  \"productId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"itemId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"startDate\": \"2023-12-25\",\n  \"endDate\": \"2023-12-25\",\n  \"amount\": 123,\n  \"name\": \"<string>\",\n  \"lineItemGroupId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"subLineItems\": []\n}"

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

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "idempotencyKey": "<string>",
  "customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "productId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "resourceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "licenseId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "lineItemGroupId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "scope": "credit_purchase",
  "startDate": "2023-12-25",
  "endDate": "2023-12-25",
  "totalUsage": 123,
  "usageFormat": "unit",
  "subtotalAmount": 123,
  "adjustmentAmount": 123,
  "totalAmount": 123,
  "discountAmount": 123,
  "metadata": {
    "type": "fixed",
    "billingTiming": "in_advance"
  },
  "subLineItems": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "type": "fixed_price",
      "name": "<string>",
      "description": "<string>",
      "usage": 123,
      "usageFormat": "unit",
      "amount": 123,
      "metadata": {
        "type": "fixed_price",
        "fixedPrice": 123
      }
    }
  ],
  "adjustments": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "type": "monetary_discount",
      "amount": 123
    }
  ],
  "itemId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

{
  "message": "<string>",
  "code": "<string>",
  "details": {},
  "causations": [
    {
      "message": "<string>",
      "code": "<string>",
      "details": {}
    }
  ]
}

{
  "message": "<string>"
}

{
  "message": "<string>",
  "code": "<string>",
  "details": {},
  "causations": [
    {
      "message": "<string>",
      "code": "<string>",
      "details": {}
    }
  ]
}

Authorizations

X-API-KEY

string

header

required

API Key Authentication.

Path Parameters

invoiceId

string<uuid>

required

The unique identifier of the invoice to add the line item to.

Body

application/json

Schema for creating a one-off line item on an existing one-off invoice. When subLineItems is provided, the sum of usage × price (rounded to whole cents per row) must equal amount.

idempotencyKey

string

required

A unique idempotency key for this line item, scoped to the invoice.

Minimum string length: 1

Pattern: ^[a-zA-Z0-9_-]+$

productId

string<uuid>

required

The unique identifier of the product this line item belongs to.

itemId

string<uuid>

required

The unique identifier of the catalog item this line item bills.

startDate

string<date>

required

Start of the period covered by the line item.

endDate

string<date>

required

End of the period covered by the line item.

amount

number

required

Amount billed by the line item, in cents.

name

string | null

Optional line item name; defaults to the item name (or product name as fallback) when null.

lineItemGroupId

string<uuid> | null

Optional line item group to attach this line item to. The group must belong to the same invoice.

subLineItems

object[]

Optional breakdown of the line item amount into sub-line items. The sum of usage × price (rounded to whole cents per row) must equal amount.

Show child attributes

Response

Schema representing an invoice line item. Monetary amounts are integers in cents; the price breakdown lives in subLineItems.

string<uuid>

required

The unique identifier of the line item in our system.

idempotencyKey

string

required

A unique key that identifies the line item within the invoice. Supplied by the caller for one-off line items; generated by the billing engine otherwise.

customerId

string<uuid>

required

The unique identifier of the customer whose consumption this line item bills. On split or consolidated invoices it may be a subsidiary of the invoice's customer.

productId

string<uuid>

required

The unique identifier of the product this line item belongs to.

resourceId

string<uuid> | null

required

The unique identifier of the metered resource behind a usage_based line item. Null for line items not driven by resource usage.

licenseId

string<uuid> | null

required

The unique identifier of the license behind a license_based line item. Null for line items not driven by a license count.

lineItemGroupId

string<uuid> | null

required

The unique identifier of the line item group containing this line item. Null for standalone line items.

name

string

required

Display name of the line item as it appears on the invoice.

scope

enum<string>

required

What the line item charges for: usage_based (metered resource consumption), license_based (a license's reported count billed in full), fixed (recurring fixed charge of a plan), custom (custom plan charge, priced by a calculator that Aira writes for the tenant), minimum_commitment (plan-level minimum top-up), contract_minimum_commitment (contract-level minimum top-up), credit_purchase (credit pool top-up), additional_charge (extra charge added manually), one_off (line item of a one-off invoice), or tax_gross_up (tax gross-up charge).

Available options:

credit_purchase,

contract_minimum_commitment,

minimum_commitment,

fixed,

usage_based,

license_based,

custom,

additional_charge,

one_off,

tax_gross_up

startDate

string<date>

required

Start of the period covered by this line item.

endDate

string<date>

required

End of the period covered by this line item.

totalUsage

number | null

required

Total usage billed by the line item, in the unit given by usageFormat. Null for line items without a single usage (e.g. fixed charges without a quantity, and custom line items whose calculator returns no total).

usageFormat

enum<string> | null

required

How to read totalUsage, and the usage of each sub-line item that has no usageFormat of its own: unit means a count of resource units or a fixed charge quantity; currency means a monetary base amount in cents. Null when the line item has no single usage, as a custom line item whose sub-line items bill different kinds of volume, each with its own usageFormat.

Available options:

unit,

currency,

null

subtotalAmount

number

required

Line item amount before adjustments, in cents (sum of its sub-line item amounts).

adjustmentAmount

number

required

Net amount of the adjustments applied to this line item (discounts and allocation offsets), in cents. Negative when adjustments reduce the amount owed.

totalAmount

number

required

Final line item amount, in cents: subtotalAmount + adjustmentAmount.

discountAmount

number

required

The discount portion of adjustmentAmount, in cents (sum of monetary discount adjustments only). Negative when discounts were applied.

metadata

Fixed · object

required

Pricing metadata for the line item, where the shape is keyed by type. Always present, but null for line items without pricing metadata: credit_purchase, additional_charge, one_off, and tax_gross_up. It is populated for fixed (the billing timing), usage_based, license_based, minimum_commitment, contract_minimum_commitment, and custom (the definition and the calculation memory) line items.

Show child attributes

subLineItems

object[]

required

Breakdown of the line item amount into priced rows (included quantities, unit/package/tier prices, prorations, companions). Empty for line items without a breakdown.

Show child attributes

adjustments

object[]

required

Adjustments applied on top of the line item subtotal, such as discounts and allocation offsets.

Show child attributes

itemId

string<uuid> | null

The unique identifier of the catalog item this line bills. Null for line items not backed by a catalog item.