Create an invoice item · Ownrecord docs

Adds a line to a draft invoice (invoiceId), or creates a pending item that waits for the customer's next invoice: the next subscription invoice, or a draft created with includePendingItems.

The item is an active one-time price (priceId: its product, amount, currency and tax behavior), or a product with a unitAmount (productId, taxBehavior default exclusive), times a quantity. Amounts are integer micros in whole minor units. An item on a draft is in the draft's currency and for its customer. Tax is quoted when the invoice is finalized.

At a glance

REST: POST /api/v1/invoice_items
MCP tool: invoice_items_create
Operation ID: invoice_items.create
Scope: Brand
Permission: invoices:write
Risk tier: write
Dry run: Supported (send Ownrecord-Dry-Run: true)
Idempotency: Idempotency-Key required
Modes: Test and live
Authentication: API key with the invoices:write scope
Since: M5

Request

Body

A JSON object (Content-Type: application/json):

Field	Type	Required	Description
`customerId`	`cus_…` ID	Yes	The customer (`cus_…`).
`invoiceId`	`inv_…` ID	No	A draft of the same customer and currency; without it the item is pending.
`priceId`	`price_…` ID	No	An active one-time price with a fixed amount: its product, amount, currency and tax behavior.
`productId`	`prod_…` ID	No	Instead of a price: the product (its tax category and revenue account), with `unitAmount`.
`unitAmount`	object	No	With `productId`: the price of one unit.
`unitAmount.amount`	string	Yes	Integer micros as a string (12500000 = 12.50), in whole minor units of the currency.
`unitAmount.currency`	string	Yes	ISO 4217 currency code.
`taxBehavior`	one of `exclusive`, `inclusive`	No	With `productId`: whether `unitAmount` includes tax (default `exclusive`).
`quantity`	integer (1 to 1000000)	No	Whole units, 1 to 1000000 (default 1).
`description`	string	No	The line's text on the invoice (default: the product's name, and the price's nickname).
`period`	object	No	The service period the item covers (shown on the invoice).
`period.start`	date-time	Yes
`period.end`	date-time	Yes
`metadata`	object	No	Your own key-value pairs (at most 50 keys, values of at most 500 characters).

Response

201 Created with a JSON object:

Field	Type	Description
`id`	`ii_…` ID
`object`	`"invoice_item"`
`livemode`	boolean
`customerId`	`cus_…` ID
`subscriptionId`	`sub_…` ID or null
`invoiceId`	`inv_…` ID or null	The invoice the item is on; null while it waits for the customer's next invoice.
`origin`	one of `pending`, `invoice`	`invoice`: created for a draft; `pending`: created for the next invoice.
`description`	string
`productId`	`prod_…` ID
`priceId`	`price_…` ID or null
`taxCategoryId`	one of 9 values, e.g. `electronically_supplied_service`, `saas`, `ebook` (all in the OpenAPI document)
`taxBehavior`	one of `inclusive`, `exclusive`
`quantity`	integer
`unitAmount`	money
`amount`	money	Quantity × unit amount.
`period`	object or null
`proration`	boolean
`taxDate`	date-time or null	The date whose tax rates apply (a proration's change date).
`metadata`	object
`createdAt`	date-time
`updatedAt`	date-time

Examples

Add two consulting days to a draft

HTTP

POST /api/v1/invoice_items
Authorization: Bearer or_test_…
Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14
Content-Type: application/json

{
  "customerId": "cus_01m4tx5nj8emwbyf7y9vcf47ym",
  "invoiceId": "inv_01m4tx5nj8emwbyf7y9vcf47yk",
  "productId": "prod_01m4tx5nj8emwbyf7y9vcf47yr",
  "unitAmount": {
    "amount": "600000000",
    "currency": "EUR"
  },
  "quantity": 2,
  "description": "Implementation workshop (days)"
}

Response (201):

JSON

{
  "id": "ii_01m4tx5nj8emwbyf7y9vcf47ys",
  "object": "invoice_item",
  "livemode": false,
  "customerId": "cus_01m4tx5nj8emwbyf7y9vcf47ym",
  "subscriptionId": null,
  "invoiceId": "inv_01m4tx5nj8emwbyf7y9vcf47yk",
  "origin": "invoice",
  "description": "Implementation workshop (days)",
  "productId": "prod_01m4tx5nj8emwbyf7y9vcf47yr",
  "priceId": null,
  "taxCategoryId": "consulting_remote",
  "taxBehavior": "exclusive",
  "quantity": 2,
  "unitAmount": {
    "amount": "600000000",
    "currency": "EUR"
  },
  "amount": {
    "amount": "1200000000",
    "currency": "EUR"
  },
  "period": null,
  "proration": false,
  "taxDate": null,
  "metadata": {},
  "createdAt": "2026-10-20T08:30:00.000Z",
  "updatedAt": "2026-10-20T08:30:00.000Z"
}

A setup fee for the customer's next invoice

HTTP

POST /api/v1/invoice_items
Authorization: Bearer or_test_…
Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14
Content-Type: application/json

{
  "customerId": "cus_01m4tx5nj8emwbyf7y9vcf47ym",
  "priceId": "price_01m4tx5nj8emwbyf7y9vcf47yj"
}

Response (201):

JSON

{
  "id": "ii_01m4tx5nj8emwbyf7y9vcf47ys",
  "object": "invoice_item",
  "livemode": false,
  "customerId": "cus_01m4tx5nj8emwbyf7y9vcf47ym",
  "subscriptionId": null,
  "invoiceId": null,
  "origin": "pending",
  "description": "Genno Pro (Setup fee)",
  "productId": "prod_01m4tx5nj8emwbyf7y9vcf47yh",
  "priceId": "price_01m4tx5nj8emwbyf7y9vcf47yj",
  "taxCategoryId": "saas",
  "taxBehavior": "exclusive",
  "quantity": 1,
  "unitAmount": {
    "amount": "49000000",
    "currency": "EUR"
  },
  "amount": {
    "amount": "49000000",
    "currency": "EUR"
  },
  "period": null,
  "proration": false,
  "taxDate": null,
  "metadata": {},
  "createdAt": "2026-10-20T08:30:00.000Z",
  "updatedAt": "2026-10-20T08:30:00.000Z"
}

Errors

Code	HTTP status	When	What to do
`validation_failed`	400	A field is malformed, both or neither of `priceId` and `productId`, an archived product, the item's customer isn't the draft's.	Fix the fields listed in `details.issues` and send the request again.
`resource_not_found`	404	The customer, the invoice, the price or the product isn't this brand's in this mode (`param` names it).	Check the ID and that your credentials are scoped to the right organization, entity, brand and mode.
`customer_deleted`	400	The customer was deleted.	Create a new customer for this buyer. Deleted customers stay readable for the records they belong to, but can't be changed.
`invoice_status_invalid`	409	`invoiceId` names an invoice that isn't a draft.	Check the invoice's `status` (`details.status`) and what it still allows (`details.allowed_actions`). Drafts are edited and finalized; open invoices are sent, paid, voided or marked uncollectible; paid and void invoices don't change (corrections are credit notes).
`invoice_item_price_unusable`	400	A price is archived, recurring, a credit pack or a custom amount (use a product with `unitAmount`).	Use an active one-time price with a fixed amount, or give the product (`productId`) and a `unitAmount` instead. Recurring prices are billed by subscriptions and credit packs by checkout.
`invoice_currency_mismatch`	400	An item's currency isn't the invoice's.	Every item of an invoice is in the invoice's currency (`details.invoice_currency`). Create a separate draft for the other currency.
`idempotency_key_reused`	409	The idempotency key was used before for another request.	Use a new Idempotency-Key for a different request, or resend the original request unchanged.
`scope_required`	400	The request names no brand (an org or entity key without `Ownrecord-Brand`).	Call the operation with credentials or a target at its level: an organization, a legal entity, a brand or the platform (`details.required_scope`).
`permission_denied`	403	You can't change this brand's invoices (`invoices:write`: finance, owners and admins).	Ask an organization owner or admin for a role or scope that allows this action.
`livemode_not_allowed`	403	You have no live-mode access, so you can't use live invoices.	Use test mode, or credentials for the target's mode. Developers need live access granted by an organization owner or admin.

It can also return these common errors: api_version_unsupported, invalid_json, unsupported_media_type, authentication_required, api_key_invalid, idempotency_key_required, idempotency_in_progress, approval_required, approval_rejected, approval_expired, stale_approval, approval_policy_denied, rate_limited, internal_error.

At a glance#

Request#

Body#

Response#

Examples#

Add two consulting days to a draft#

A setup fee for the customer's next invoice#

Errors#