Items

Manage your catalog of products and services to reuse on invoices and quotes.

Overview

The catalog stores reusable products and services so you can drop them into invoices and quotes without retyping name, price, unit, or tax rate. Items are scoped to a specific company.

Each item has an auto-generated item_code (e.g. SER-000001) that you can override when creating it.

Create an Item

Bash

 1curl -X POST "https://api.corebill.io/v1/items?company_id=com_abc123" \
 2  -H "Authorization: Bearer sk_live_your_api_key" \
 3  -H "Content-Type: application/json" \
 4  -d '{
 5    "name": "Web Development",
 6    "description": "Frontend implementation",
 7    "unit": "hour",
 8    "unit_price": 75,
 9    "currency": "USD",
10    "item_type": "service",
11    "tax_rate": 16,
12    "category": "Development"
13  }'

Only name and unit_price are required.

All monetary amounts are in the major unit of the currency. unit_price: 75 means $75.00 USD.

List Items

Bash

 1# List all active items
 2curl "https://api.corebill.io/v1/items?company_id=com_abc123" \
 3  -H "Authorization: Bearer sk_live_your_api_key"
 4
 5# Filter by category
 6curl "https://api.corebill.io/v1/items?company_id=com_abc123&category=Development" \
 7  -H "Authorization: Bearer sk_live_your_api_key"
 8
 9# Search by name, code, or description
10curl "https://api.corebill.io/v1/items?company_id=com_abc123&query=development" \
11  -H "Authorization: Bearer sk_live_your_api_key"
12
13# Paginate (cursor-based)
14curl "https://api.corebill.io/v1/items?company_id=com_abc123&limit=20&starting_after=itm_xyz" \
15  -H "Authorization: Bearer sk_live_your_api_key"

Update an Item

Bash

 1curl -X POST "https://api.corebill.io/v1/items/itm_abc123?company_id=com_abc123" \
 2  -H "Authorization: Bearer sk_live_your_api_key" \
 3  -H "Content-Type: application/json" \
 4  -d '{
 5    "unit_price": 85,
 6    "category": "Engineering"
 7  }'

Delete an Item

Deleting an item is a soft delete (sets deleted_at and is_active = false). Existing invoices and quotes that reference it keep their line item snapshot intact. Requires admin permission.

Bash

 1curl -X DELETE "https://api.corebill.io/v1/items/itm_abc123?company_id=com_abc123" \
 2  -H "Authorization: Bearer sk_live_your_api_key"

Item Fields

Field	Type	Required	Description
`name`	string	Yes	Display name
`unit_price`	number	Yes	Price in major unit (e.g. `75` = $75.00)
`item_code`	string	No	Auto-generated if omitted (e.g. `SER-000001`)
`description`	string	No	Long description
`unit`	string	No	Unit of measure (`hour`, `unit`, `month`, ...). Default: `unit`
`currency`	string	No	ISO-4217 code. Default: `USD`
`item_type`	string	No	`service` or `subscription`. Default: `service`
`billing_frequency`	string	No	For subscriptions: `monthly`, `quarterly`, `semi_annual`, `yearly`, `one_time`
`tax_rate`	number	No	Tax percentage 0-100
`category`	string	No	Free-form category for grouping
`is_active`	boolean	No	Default: `true`
`metadata`	object	No	Custom key-value pairs

Subscription Items

For recurring billing, set item_type to subscription and pick a billing_frequency:

jsonJSON

 1{
 2  "name": "Pro Plan",
 3  "unit_price": 1000,
 4  "item_type": "subscription",
 5  "billing_frequency": "monthly"
 6}

When a subscription item is added to an invoice or quote, the billing frequency is preserved on the line item.

Quotes Companies