Invoice items tools

• invoice_items_create: Create an invoice item
• invoice_items_delete: Delete an invoice item
• invoice_items_list: List invoice items

invoice_items_create#

Create an invoice item. Operation invoice_items.create · Brand level · permission invoices:write · risk tier write · since M5

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.

Annotations: readOnlyHint: false · destructiveHint: false · idempotentHint: false · openWorldHint: false

Arguments#

• Brand: pass brand_id with an organization or entity key; a brand key acts on its own brand.
• Idempotency: the result returns the idempotency_key used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours).
• Dry run: supported. dry_run: true checks permissions and rules and computes the result, then rolls everything back.

Errors#

• validation_failed: A field is malformed, both or neither of priceId and productId, an archived product, the item's customer isn't the draft's.
• resource_not_found: The customer, the invoice, the price or the product isn't this brand's in this mode (param names it).
• customer_deleted: The customer was deleted.
• invoice_status_invalid: invoiceId names an invoice that isn't a draft.
• invoice_item_price_unusable: A price is archived, recurring, a credit pack or a custom amount (use a product with unitAmount).
• invoice_currency_mismatch: An item's currency isn't the invoice's.
• idempotency_key_reused: The idempotency key was used before for another request.
• scope_required: The request names no brand (an org or entity key without Ownrecord-Brand).
• permission_denied: You can't change this brand's invoices (invoices:write: finance, owners and admins).
• livemode_not_allowed: You have no live-mode access, so you can't use live invoices.

Examples#

Add two consulting days to a draft

Arguments:

{
  "customerId": "cus_01m4tx5nj8emwbyf7y9vcf47ym",
  "invoiceId": "inv_01m4tx5nj8emwbyf7y9vcf47yk",
  "productId": "prod_01m4tx5nj8emwbyf7y9vcf47yr",
  "unitAmount": {
    "amount": "600000000",
    "currency": "EUR"
  },
  "quantity": 2,
  "description": "Implementation workshop (days)",
  "brand_id": "brd_01jbx4m3v8e9t0s6k2c5n7q1wz",
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}

Result output:

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

Arguments:

{
  "customerId": "cus_01m4tx5nj8emwbyf7y9vcf47ym",
  "priceId": "price_01m4tx5nj8emwbyf7y9vcf47yj",
  "brand_id": "brd_01jbx4m3v8e9t0s6k2c5n7q1wz",
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}

Result output:

{
  "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"
}

invoice_items_delete#

Delete an invoice item. Operation invoice_items.delete · Brand level · permission invoices:write · risk tier write · since M5

Deletes an invoice item that isn't billed yet: a pending item, or a line of a draft. Items of a finalized or voided invoice are part of its record and stay. Returns the deleted item.

Annotations: readOnlyHint: false · destructiveHint: true · idempotentHint: false · openWorldHint: false

Arguments#

• Brand: pass brand_id with an organization or entity key; a brand key acts on its own brand.
• Idempotency: the result returns the idempotency_key used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours).
• Dry run: supported. dry_run: true checks permissions and rules and computes the result, then rolls everything back.

Errors#

• validation_failed: id isn't an invoice item ID (ii_…).
• resource_not_found: This brand has no such invoice item in this mode.
• invoice_status_invalid: The item is on a finalized or voided invoice: it's part of that invoice's record.
• version_conflict: The item changed at the same moment; retry.
• scope_required: The request names no brand (an org or entity key without Ownrecord-Brand).
• permission_denied: You can't change this brand's invoices (invoices:write: finance, owners and admins).
• livemode_not_allowed: You have no live-mode access, so you can't use live invoices.

Example#

Remove a line from a draft

Arguments:

{
  "id": "ii_01m4tx5nj8emwbyf7y9vcf47ys",
  "brand_id": "brd_01jbx4m3v8e9t0s6k2c5n7q1wz",
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}

Result output:

{
  "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"
}

invoice_items_list#

List invoice items. Operation invoice_items.list · Brand level · permission invoices:read · risk tier read · since M5

Lists the brand's invoice items in the mode of the request, newest first: a customer's (customerId), an invoice's (invoiceId), or only those waiting for an invoice (pending=true). Paginate with limit (1–100, default 10) and starting_after.

Annotations: readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false

Arguments#

• Brand: pass brand_id with an organization or entity key; a brand key acts on its own brand.
• Read-only: changes nothing; idempotency_key is ignored.

Errors#

• validation_failed: A filter or pagination value is invalid, or invoiceId and pending=true are both given.
• scope_required: The request names no brand (an org or entity key without Ownrecord-Brand).
• permission_denied: You can't read this brand's invoices (invoices:read; every role but billing admin has it).
• livemode_not_allowed: You have no live-mode access, so you can't use live invoices.

Example#

The items of a draft

Arguments:

{
  "invoiceId": "inv_01m4tx5nj8emwbyf7y9vcf47yk",
  "brand_id": "brd_01jbx4m3v8e9t0s6k2c5n7q1wz"
}

Result output:

{
  "object": "list",
  "data": [
    {
      "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"
    }
  ],
  "has_more": false,
  "next_cursor": null
}