API reference
Invoiceitems
Invoice Items represent the component lines of an invoice. When you create an invoice item with an invoice field, it is attached to the specified invoice and included as an invoice line item within invoice.lines. Invoice Items can be created before you are ready to actually send the invoice. This can be particularly useful when combined with a subscription. Sometimes you want to add a charge or credit to a customer, but actually charge or credit the customer's card only at the end of a regular billing cycle. This is useful for combining several charges (to minimize per-transaction fees), or for having Stripe tabulate your usage-based billing totals. Related guides: Integrate with the Invoicing API, Subscription Invoices.
https://api.knoxapi.comCreate an invoice item
POST/v1/invoiceitems
Creates an item to be added to a draft invoice (up to 250 items per invoice). If no invoice is specified, the item will be on the next invoice created for the customer specified.
Body parameters
amountintegerThe integer amount in cents (or local equivalent) of the charge to be applied to the upcoming invoice. Passing in a negative
amountwill reduce theamount_dueon the invoice.currencystringThree-letter ISO currency code, in lowercase. Must be a supported currency.
customerstringThe ID of the customer to bill for this invoice item.
customer_accountstringThe ID of the account representing the customer to bill for this invoice item.
descriptionstringAn arbitrary string which you can attach to the invoice item. The description is displayed in the invoice for easy tracking.
discountablebooleanControls whether discounts apply to this invoice item. Defaults to false for prorations or negative invoice items, and true for all other invoice items.
discountsarray of objectsThe coupons and promotion codes to redeem into discounts for the invoice item or invoice line item.
Show 3 child parameters
couponstringdiscountstringpromotion_codestring
expandarray of stringsSpecifies which fields in the response should be expanded.
invoicestringThe ID of an existing invoice to add this invoice item to. For subscription invoices, when left blank, the invoice item will be added to the next upcoming scheduled invoice. For standalone invoices, the invoice item won't be automatically added unless you pass
pending_invoice_item_behavior: 'include'when creating the invoice. This is useful when adding invoice items in response to an invoice.created webhook. You can only add invoice items to draft invoices and there is a maximum of 250 items per invoice.metadataobjectSet of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to
metadata.periodobjectThe period associated with this invoice item. When set to different values, the period will be rendered on the invoice. If you have Stripe Revenue Recognition enabled, the period will be used to recognize and defer revenue. See the Revenue Recognition documentation for details.
Show 2 child parameters
endintegerRequiredstartintegerRequired
price_dataobjectData used to generate a new Price object inline.
Show 5 child parameters
currencystringRequiredproductstringRequiredtax_behaviorstringPossible valuesexclusiveinclusiveunspecified
unit_amountintegerunit_amount_decimalstring
pricingobjectThe pricing information for the invoice item.
Show 1 child parameter
pricestring
quantityintegerNon-negative integer. The quantity of units for the invoice item. Use
quantity_decimalinstead to provide decimal precision. This field will be deprecated in favor ofquantity_decimalin a future version.quantity_decimalstringNon-negative decimal with at most 12 decimal places. The quantity of units for the invoice item.
subscriptionstringThe ID of a subscription to add this invoice item to. When left blank, the invoice item is added to the next upcoming scheduled invoice. When set, scheduled invoices for subscriptions other than the specified subscription will ignore the invoice item. Use this when you want to express that an invoice item has been accrued within the context of a particular subscription.
tax_behaviorstringOnly required if a default tax behavior) was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of
inclusive,exclusive, orunspecified. Once specified as eitherinclusiveorexclusive, it cannot be changed.Possible valuesexclusiveinclusiveunspecified
tax_codestringA tax code ID.
tax_ratesarray of stringsThe tax rates which apply to the invoice item. When set, the
default_tax_rateson the invoice do not apply to this invoice item.unit_amount_decimalstringThe decimal unit amount in cents (or local equivalent) of the charge to be applied to the upcoming invoice. This
unit_amount_decimalwill be multiplied by the quantity to get the full amount. Passing in a negativeunit_amount_decimalwill reduce theamount_dueon the invoice. Accepts at most 12 decimal places.
Returns
The invoiceitem object.
curl -X POST https://api.knoxapi.com/v1/invoiceitems \
-H "Authorization: Bearer $KNOX_SECRET_KEY"const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const invoiceitem = await stripe.invoiceItems.create();import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
invoiceitem = client.v1.invoice_items.create()require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
invoiceitem = Stripe::InvoiceItem.create(){
"amount": 1000,
"currency": "usd",
"customer": "cus_QXg1o8vcGmoR32",
"date": 1234567890,
"description": "My First Invoice Item (created for API docs)",
"discountable": true,
"discounts": [],
"id": "ii_1Pgc6sB7WZ01zgkWrG16hkdl",
"invoice": null,
"livemode": false,
"metadata": {},
"object": "invoiceitem",
"period": {
"end": 1721954054,
"start": 1721954054
},
"proration": false,
"quantity": 1,
"tax_rates": [],
"test_clock": null,
"parent": {
"subscription_details": {
"subscription": "subscription"
},
"type": "subscription_details"
},
"pricing": {
"type": "price_details",
"unit_amount_decimal": null
},
"net_amount": 708769478,
"customer_account": null,
"quantity_decimal": "174352450"
}List all invoice items
GET/v1/invoiceitems
Returns a list of your invoice items. Invoice items are returned sorted by creation date, with the most recently created invoice items appearing first.
Query parameters
createdobject | integerOnly return invoice items that were created during the given date interval.
Show 4 child parameters
gtintegergteintegerltintegerlteinteger
customerstringThe identifier of the customer whose invoice items to return. If none is provided, returns all invoice items.
customer_accountstringThe identifier of the account representing the customer whose invoice items to return. If none is provided, returns all invoice items.
ending_beforestringA cursor for use in pagination.
ending_beforeis an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting withobj_bar, your subsequent call can includeending_before=obj_barin order to fetch the previous page of the list.expandarray of stringsSpecifies which fields in the response should be expanded.
invoicestringOnly return invoice items belonging to this invoice. If none is provided, all invoice items will be returned. If specifying an invoice, no customer identifier is needed.
limitintegerA limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
pendingbooleanSet to
trueto only show pending invoice items, which are not yet attached to any invoices. Set tofalseto only show invoice items already attached to invoices. If unspecified, no filter is applied.starting_afterstringA cursor for use in pagination.
starting_afteris an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending withobj_foo, your subsequent call can includestarting_after=obj_fooin order to fetch the next page of the list.
Returns
A list of invoiceitem objects.
curl -G https://api.knoxapi.com/v1/invoiceitems \
-H "Authorization: Bearer $KNOX_SECRET_KEY" \
--data-urlencode limit=3const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const page = await stripe.invoiceItems.list({
limit: 3,
});import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
page = client.v1.invoice_items.list(params={
"limit": 3,
})require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
page = Stripe::InvoiceItem.list({
limit: 3,
}){
"object": "list",
"url": "/v1/invoiceitems",
"has_more": false,
"data": [
{
"amount": 1000,
"currency": "usd",
"customer": "cus_QXg1o8vcGmoR32",
"date": 1234567890,
"description": "My First Invoice Item (created for API docs)",
"discountable": true,
"discounts": [],
"id": "ii_1Pgc6sB7WZ01zgkWrG16hkdl",
"invoice": null,
"livemode": false,
"metadata": {},
"object": "invoiceitem",
"period": {
"end": 1721954054,
"start": 1721954054
},
"proration": false,
"quantity": 1,
"tax_rates": [],
"test_clock": null,
"parent": {
"subscription_details": {
"subscription": "subscription"
},
"type": "subscription_details"
},
"pricing": {
"type": "price_details",
"unit_amount_decimal": null
},
"net_amount": 708769478,
"customer_account": null,
"quantity_decimal": "174352450"
}
]
}Update an invoice item
POST/v1/invoiceitems/{invoiceitem}
Updates the amount or description of an invoice item on an upcoming invoice. Updating an invoice item is only possible before the invoice it’s attached to is closed.
Path parameters
invoiceitemstringRequired
Body parameters
amountintegerThe integer amount in cents (or local equivalent) of the charge to be applied to the upcoming invoice. If you want to apply a credit to the customer's account, pass a negative amount.
descriptionstringAn arbitrary string which you can attach to the invoice item. The description is displayed in the invoice for easy tracking.
discountablebooleanControls whether discounts apply to this invoice item. Defaults to false for prorations or negative invoice items, and true for all other invoice items. Cannot be set to true for prorations.
discountsarray of objectsThe coupons, promotion codes & existing discounts which apply to the invoice item or invoice line item. Item discounts are applied before invoice discounts. Pass an empty string to remove previously-defined discounts.
Show 3 child parameters
couponstringdiscountstringpromotion_codestring
expandarray of stringsSpecifies which fields in the response should be expanded.
metadataobjectSet of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to
metadata.periodobjectThe period associated with this invoice item. When set to different values, the period will be rendered on the invoice. If you have Stripe Revenue Recognition enabled, the period will be used to recognize and defer revenue. See the Revenue Recognition documentation for details.
Show 2 child parameters
endintegerRequiredstartintegerRequired
price_dataobjectData used to generate a new Price object inline.
Show 5 child parameters
currencystringRequiredproductstringRequiredtax_behaviorstringPossible valuesexclusiveinclusiveunspecified
unit_amountintegerunit_amount_decimalstring
pricingobjectThe pricing information for the invoice item.
Show 1 child parameter
pricestring
quantityintegerNon-negative integer. The quantity of units for the invoice item. Use
quantity_decimalinstead to provide decimal precision. This field will be deprecated in favor ofquantity_decimalin a future version.quantity_decimalstringNon-negative decimal with at most 12 decimal places. The quantity of units for the line item.
tax_behaviorstringOnly required if a default tax behavior) was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of
inclusive,exclusive, orunspecified. Once specified as eitherinclusiveorexclusive, it cannot be changed.Possible valuesexclusiveinclusiveunspecified
tax_codestringA tax code ID.
tax_ratesarray of stringsThe tax rates which apply to the invoice item. When set, the
default_tax_rateson the invoice do not apply to this invoice item. Pass an empty string to remove previously-defined tax rates.unit_amount_decimalstringThe decimal unit amount in cents (or local equivalent) of the charge to be applied to the upcoming invoice. This
unit_amount_decimalwill be multiplied by the quantity to get the full amount. Passing in a negativeunit_amount_decimalwill reduce theamount_dueon the invoice. Accepts at most 12 decimal places.
Returns
The invoiceitem object.
curl https://api.knoxapi.com/v1/invoiceitems/ii_1Pgc6sB7WZ01zgkWrG16hkdl \
-H "Authorization: Bearer $KNOX_SECRET_KEY" \
-d "metadata[order_id]=6735"const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const invoiceitem = await stripe.invoiceItems.update('ii_1Pgc6sB7WZ01zgkWrG16hkdl', {
metadata: {
order_id: '6735',
},
});import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
invoiceitem = client.v1.invoice_items.update("ii_1Pgc6sB7WZ01zgkWrG16hkdl", params={
"metadata": {
"order_id": "6735",
},
})require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
invoiceitem = Stripe::InvoiceItem.update('ii_1Pgc6sB7WZ01zgkWrG16hkdl', {
metadata: {
order_id: '6735',
},
}){
"amount": 1000,
"currency": "usd",
"customer": "cus_QXg1o8vcGmoR32",
"date": 1234567890,
"description": "My First Invoice Item (created for API docs)",
"discountable": true,
"discounts": [],
"id": "ii_1Pgc6sB7WZ01zgkWrG16hkdl",
"invoice": null,
"livemode": false,
"metadata": {},
"object": "invoiceitem",
"period": {
"end": 1721954054,
"start": 1721954054
},
"proration": false,
"quantity": 1,
"tax_rates": [],
"test_clock": null,
"parent": {
"subscription_details": {
"subscription": "subscription"
},
"type": "subscription_details"
},
"pricing": {
"type": "price_details",
"unit_amount_decimal": null
},
"net_amount": 708769478,
"customer_account": null,
"quantity_decimal": "174352450"
}Retrieve an invoice item
GET/v1/invoiceitems/{invoiceitem}
Retrieves the invoice item with the given ID.
Path parameters
invoiceitemstringRequired
Query parameters
expandarray of stringsSpecifies which fields in the response should be expanded.
Returns
The invoiceitem object.
curl https://api.knoxapi.com/v1/invoiceitems/ii_1Pgc6sB7WZ01zgkWrG16hkdl \
-H "Authorization: Bearer $KNOX_SECRET_KEY"const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const invoiceitem = await stripe.invoiceItems.retrieve('ii_1Pgc6sB7WZ01zgkWrG16hkdl');import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
invoiceitem = client.v1.invoice_items.retrieve("ii_1Pgc6sB7WZ01zgkWrG16hkdl")require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
invoiceitem = Stripe::InvoiceItem.retrieve('ii_1Pgc6sB7WZ01zgkWrG16hkdl'){
"amount": 1000,
"currency": "usd",
"customer": "cus_QXg1o8vcGmoR32",
"date": 1234567890,
"description": "My First Invoice Item (created for API docs)",
"discountable": true,
"discounts": [],
"id": "ii_1Pgc6sB7WZ01zgkWrG16hkdl",
"invoice": null,
"livemode": false,
"metadata": {},
"object": "invoiceitem",
"period": {
"end": 1721954054,
"start": 1721954054
},
"proration": false,
"quantity": 1,
"tax_rates": [],
"test_clock": null,
"parent": {
"subscription_details": {
"subscription": "subscription"
},
"type": "subscription_details"
},
"pricing": {
"type": "price_details",
"unit_amount_decimal": null
},
"net_amount": 708769478,
"customer_account": null,
"quantity_decimal": "174352450"
}Delete an invoice item
DELETE/v1/invoiceitems/{invoiceitem}
Deletes an invoice item, removing it from an invoice. Deleting invoice items is only possible when they’re not attached to invoices, or if it’s attached to a draft invoice.
Path parameters
invoiceitemstringRequired
Returns
The deleted_invoiceitem object.
curl -X DELETE https://api.knoxapi.com/v1/invoiceitems/ii_1Pgc6sB7WZ01zgkWrG16hkdl \
-H "Authorization: Bearer $KNOX_SECRET_KEY"const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const deletedInvoiceitem = await stripe.invoiceItems.del('ii_1Pgc6sB7WZ01zgkWrG16hkdl');import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
deleted_invoiceitem = client.v1.invoice_items.delete("ii_1Pgc6sB7WZ01zgkWrG16hkdl")require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
deleted_invoiceitem = Stripe::InvoiceItem.delete('ii_1Pgc6sB7WZ01zgkWrG16hkdl'){
"deleted": true,
"id": "ii_1Pgc6sB7WZ01zgkWrG16hkdl",
"object": "invoiceitem"
}Operations and schemas come from the pinned Stripe OpenAPI specification (MIT); response examples from its fixtures. Nested object definitions and enums are in the complete specification.