BiasDocs

Line items

Line items represent the individual products and charges on an invoice. Each line item includes a quantity, pricing details, and computed subtotal and total amounts after discounts and taxes.

Line items are managed through the Invoices API. Include them when creating or updating an invoice — there are no separate line item endpoints.

The LineItem object

Name
object
Type
"line_item",
Description
Literal representing the object’s type.
Name
id
Type
string,
Description
Unique identifier for the object.
Name
live
Type
boolean,
Description
Has the value true if the object exists in a production environment or the value false if the object exists in a sandbox environment.
Name
created_at
Type
integer,
Description
Time at which the object was created. Measured in milliseconds since the Unix epoch.
Name
description
Type
string or null,
Description
Optional descriptive text for this line item.
Name
discounts
Type
array of Discounts or null,
Description
Expandable. The discounts applied to this line item.
Name
name
Type
string or null,
Description
The display name for this line item when not backed by a catalog price.
Name
price
Type
string or Price or null,
Description
Expandable. The catalog price backing this line item, if any.
Name
quantity
Type
number, at most 9999,
Description
The quantity of this product being purchased.
Name
subtotal
Type
integer,
Description
The subtotal amount in cents after discounts.
Name
taxes
Type
array of objects,
Description
The taxes applied to this line item.
Properties
Name
total
Type
integer,
Description
The total amount in cents after applying discounts and taxes.
Name
type
Type
enum,
Description
Discriminates how this line item is priced.
Name
unit_amount
Type
integer or null,
Description
The unit amount in cents for this line item when it is not backed by a catalog price.
Name
updated_at
Type
integer,
Description
Time at which the object was last updated. Measured in milliseconds since the Unix epoch.

The LineItem object

{
  "object": "line_item",
  "id": "li_rbw8iroSXBkFMZ8bisSxK",
  "live": false,
  "created_at": 1750000000000,
  "updated_at": 1750000000000,
  "type": "custom",
  "quantity": 2,
  "name": "Custom item",
  "description": "Custom consulting work",
  "unit_amount": 1000,
  "price": "price_dz1NVvl5CSogERkeA9Ng67",
  "discounts": [],
  "subtotal": 2000,
  "total": 2000
}

Adding line items

When creating an invoice, include at least one line item in the line_items array. Each invoice must have at least one line item.

Line items can reference catalog prices or use one-off custom pricing. See Line item types below.

Create an invoice with line items

const invoice = await bias.invoices.create({
  customer: "cus_abc123",
  line_items: [
    {
      type: "catalog",
      price: "price_abc123",
      quantity: 2
    },
    {
      type: "custom",
      name: "Custom service",
      unit_amount: 1500,
      quantity: 1
    }
  ],
  due_date: 1750086400000
});

Response example

{
  "object": "invoice",
  "live": false,
  "id": "inv_2bA3FSNtE8Qmpg2ufwPmC2",
  "created_at": 1750000000000,
  "updated_at": 1750000000000,
  "billing_address": null,
  "customer": "cus_aB4DEXqbFGOlpEOxwp0Fx1",
  "due_date": 1750086400000,
  "days_until_due": null,
  "payments": [],
  "line_items": [],
  "metadata": {},
  "number": "INV-001",
  "shipping_details": {
    "name": "John Doe",
    "phone": "+1 (555) 123-4567",
    "address": {
      "line1": "123 Hope St",
      "line2": null,
      "city": "Los Angeles",
      "state": "CA",
      "postal_code": "94111",
      "country": "US"
    }
  },
  "status": "open",
  "default_taxes": [],
  "subtotal": 2000,
  "total_taxes": 0,
  "total": 2000,
  "amount_due": 2000,
  "amount_paid": 0,
  "external_sync": null,
  "attachments": [],
  "credit_notes": null,
  "memo": null,
  "footer": null,
  "custom_fields": null,
  "payment_link": null
}

Updating line items

When updating a draft invoice, provide a new line_items array. This replaces all existing line items on the invoice.

Only draft invoices can have their line items changed. Once an invoice is finalized, its line items are locked.

Update invoice line items

const invoice = await bias.invoices.update("id", {
  customer: "cus_aB4DEXqbFGOlpEOxwp0Fx1",
  due_date: 1750172800000
});

Response example

{
  "object": "invoice",
  "live": false,
  "id": "inv_2bA3FSNtE8Qmpg2ufwPmC2",
  "created_at": 1750000000000,
  "updated_at": 1750000000000,
  "billing_address": null,
  "customer": "cus_aB4DEXqbFGOlpEOxwp0Fx1",
  "due_date": 1750086400000,
  "days_until_due": null,
  "payments": [],
  "line_items": [],
  "metadata": {},
  "number": "INV-001",
  "shipping_details": {
    "name": "John Doe",
    "phone": "+1 (555) 123-4567",
    "address": {
      "line1": "123 Hope St",
      "line2": null,
      "city": "Los Angeles",
      "state": "CA",
      "postal_code": "94111",
      "country": "US"
    }
  },
  "status": "open",
  "default_taxes": [],
  "subtotal": 2000,
  "total_taxes": 0,
  "total": 2000,
  "amount_due": 2000,
  "amount_paid": 0,
  "external_sync": null,
  "attachments": [],
  "credit_notes": null,
  "memo": null,
  "footer": null,
  "custom_fields": null,
  "payment_link": null
}

Line item types

Invoice line items are discriminated by the type field.

Catalog line items

Catalog line items reference an existing price from your product catalog. The price determines the unit amount and product details.

{
    "type": "catalog",
    "price": "price_abc123",
    "quantity": 2
}

Custom line items

Custom line items are one-off charges with an inline name and unit_amount. Use these for ad hoc fees, services, or adjustments that are not backed by a catalog price.

{
    "type": "custom",
    "name": "Custom service",
    "unit_amount": 1500,
    "quantity": 1
}

Custom line items may have a negative unit_amount to represent a credit or adjustment. The invoice total cannot be negative — credit line items may not exceed the value of the other line items.

Taxes

Apply taxes to individual line items by including a taxes array on each line item input. Each tax requires a percentage and display_name.

If no line-level taxes are provided, the invoice’s default_taxes are applied instead.

{
    "type": "catalog",
    "price": "price_abc123",
    "quantity": 1,
    "taxes": [
        {
            "percentage": 8.25,
            "display_name": "CA Sales Tax"
        }
    ]
}

Discounts

Apply discounts to a line item by including discount IDs in the discounts array. Discounts are applied before taxes when computing the line item subtotal and total.

{
    "type": "catalog",
    "price": "price_abc123",
    "quantity": 1,
    "discounts": ["disc_abc123"]
}
Previous
Next

Created by Bias in California