API reference
Invoices
Invoices are statements of amounts owed by a customer, and are either generated one-off, or generated periodically from a subscription. They contain invoice items, and proration adjustments that may be caused by subscription upgrades/downgrades (if necessary). If your invoice is configured to be billed through automatic charges, Stripe automatically finalizes your invoice and attempts payment. Note that finalizing the invoice, when automatic, does not happen immediately as the invoice is created. Stripe waits until one hour after the last webhook was successfully sent (or the last webhook timed out after failing). If you (and the platforms you may have connected to) have no webhooks configured, Stripe waits one hour after creation to finalize the invoice. If your invoice is configured to be billed by sending an email, then based on your email settings, Stripe will email the invoice to your customer and await payment. These emails can contain a link to a hosted page to pay the invoice. Stripe applies any customer credit on the account before determining the amount due for the invoice (i.e., the amount that will be actually charged). If the amount due for the invoice is less than Stripe's minimum allowed charge per currency, the invoice is automatically marked paid, and we add the amount due to the customer's credit balance which is applied to the next invoice. More details on the customer's credit balance are here. Related guide: Send invoices to customers
https://api.knoxapi.com- POST/
v1/ invoices - GET/
v1/ invoices - POST/
v1/ invoices/ create_preview - GET/
v1/ invoices/ search - POST/
v1/ invoices/ {invoice} - GET/
v1/ invoices/ {invoice} - DELETE/
v1/ invoices/ {invoice} - POST/
v1/ invoices/ {invoice}/ add_lines - POST/
v1/ invoices/ {invoice}/ attach_payment - POST/
v1/ invoices/ {invoice}/ finalize - GET/
v1/ invoices/ {invoice}/ lines - POST/
v1/ invoices/ {invoice}/ mark_uncollectible - POST/
v1/ invoices/ {invoice}/ pay - POST/
v1/ invoices/ {invoice}/ remove_lines - POST/
v1/ invoices/ {invoice}/ send - POST/
v1/ invoices/ {invoice}/ update_lines - POST/
v1/ invoices/ {invoice}/ void - POST/
v1/ invoices/ {invoice}/ lines/ {line_item_id}
Create an invoice
POST/v1/invoices
This endpoint creates a draft invoice for a given customer. The invoice remains a draft until you finalize the invoice, which allows you to pay or send the invoice to your customers.
Body parameters
account_tax_idsarray of stringsThe account tax IDs associated with the invoice. Only editable when the invoice is a draft.
application_fee_amountintegerA fee in cents (or local equivalent) that will be applied to the invoice and transferred to the application owner's Stripe account. The request must be made with an OAuth key or the Stripe-Account header in order to take an application fee. For more information, see the application fees documentation.
auto_advancebooleanControls whether Stripe performs automatic collection of the invoice. If
false, the invoice's state doesn't automatically advance without an explicit action. Defaults to false.automatic_taxobjectSettings for automatic tax lookup for this invoice.
Show 2 child parameters
enabledbooleanRequiredliabilityobjectShow 2 child parameters
typestringRequiredPossible valuesaccountself
accountstring
automatically_finalizes_atintegerThe time when this invoice should be scheduled to finalize (up to 5 years in the future). The invoice is finalized at this time if it's still in draft state.
collection_methodstringEither
charge_automatically, orsend_invoice. When charging automatically, Stripe will attempt to pay this invoice using the default source attached to the customer. When sending an invoice, Stripe will email this invoice to the customer with payment instructions. Defaults tocharge_automatically.Possible valuescharge_automaticallysend_invoice
currencystringThe currency to create this invoice in. Defaults to that of
customerif not specified.custom_fieldsarray of objectsA list of up to 4 custom fields to be displayed on the invoice.
Show 2 child parameters
namestringRequiredvaluestringRequired
customerstringThe ID of the customer to bill.
customer_accountstringThe ID of the account to bill.
days_until_dueintegerThe number of days from when the invoice is created until it is due. Valid only for invoices where
collection_method=send_invoice.default_payment_methodstringID of the default payment method for the invoice. It must belong to the customer associated with the invoice. If not set, defaults to the subscription's default payment method, if any, or to the default payment method in the customer's invoice settings.
default_sourcestringID of the default payment source for the invoice. It must belong to the customer associated with the invoice and be in a chargeable state. If not set, defaults to the subscription's default source, if any, or to the customer's default source.
default_tax_ratesarray of stringsThe tax rates that will apply to any line item that does not have
tax_ratesset.descriptionstringAn arbitrary string attached to the object. Often useful for displaying to users. Referenced as 'memo' in the Dashboard.
discountsarray of objectsThe coupons and promotion codes to redeem into discounts for the invoice. If not specified, inherits the discount from the invoice's customer. Pass an empty string to avoid inheriting any discounts.
Show 3 child parameters
couponstringdiscountstringpromotion_codestring
due_dateintegerThe date on which payment for this invoice is due. Valid only for invoices where
collection_method=send_invoice.effective_atintegerThe date when this invoice is in effect. Same as
finalized_atunless overwritten. When defined, this value replaces the system-generated 'Date of issue' printed on the invoice PDF and receipt.expandarray of stringsSpecifies which fields in the response should be expanded.
footerstringFooter to be displayed on the invoice.
from_invoiceobjectRevise an existing invoice. The new invoice will be created in
status=draft. See the revision documentation for more details.Show 2 child parameters
actionstringRequiredPossible valuesrevision
invoicestringRequired
issuerobjectThe connected account that issues the invoice. The invoice is presented with the branding and support information of the specified account.
Show 2 child parameters
typestringRequiredPossible valuesaccountself
accountstring
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.numberstringSet the number for this invoice. If no number is present then a number will be assigned automatically when the invoice is finalized. In many markets, regulations require invoices to be unique, sequential and / or gapless. You are responsible for ensuring this is true across all your different invoicing systems in the event that you edit the invoice number using our API. If you use only Stripe for your invoices and do not change invoice numbers, Stripe handles this aspect of compliance for you automatically.
on_behalf_ofstringThe account (if any) for which the funds of the invoice payment are intended. If set, the invoice will be presented with the branding and support information of the specified account. See the Invoices with Connect documentation for details.
payment_settingsobjectConfiguration settings for the PaymentIntent that is generated when the invoice is finalized.
Show 3 child parameters
default_mandatestringpayment_method_optionsobjectShow 11 child parameters
acss_debitobjectChild parameters are listed in the OpenAPI document.
bancontactobjectChild parameters are listed in the OpenAPI document.
billieobjectcardobjectChild parameters are listed in the OpenAPI document.
customer_balanceobjectChild parameters are listed in the OpenAPI document.
konbiniobjectpaytoobjectChild parameters are listed in the OpenAPI document.
pixobjectChild parameters are listed in the OpenAPI document.
sepa_debitobjectupiobjectChild parameters are listed in the OpenAPI document.
us_bank_accountobjectChild parameters are listed in the OpenAPI document.
payment_method_typesarray of strings
pending_invoice_items_behaviorstringHow to handle pending invoice items on invoice creation. Defaults to
excludeif the parameter is omitted.Possible valuesexcludeinclude
renderingobjectThe rendering-related settings that control how the invoice is displayed on customer-facing surfaces such as PDF and Hosted Invoice Page.
Show 4 child parameters
amount_tax_displaystringPossible valuesexclude_taxinclude_inclusive_tax
pdfobjectShow 1 child parameter
page_sizestringPossible valuesa4autoletter
templatestringtemplate_versioninteger
shipping_costobjectSettings for the cost of shipping for this invoice.
Show 2 child parameters
shipping_ratestringshipping_rate_dataobjectShow 7 child parameters
display_namestringRequireddelivery_estimateobjectChild parameters are listed in the OpenAPI document.
fixed_amountobjectChild parameters are listed in the OpenAPI document.
metadataobjecttax_behaviorstringPossible valuesexclusiveinclusiveunspecified
tax_codestringtypestringPossible valuesfixed_amount
shipping_detailsobjectShipping details for the invoice. The Invoice PDF will use the
shipping_detailsvalue if it is set, otherwise the PDF will render the shipping address from the customer.Show 3 child parameters
addressobjectRequiredShow 6 child parameters
citystringcountrystringline1stringline2stringpostal_codestringstatestring
namestringRequiredphonestring
statement_descriptorstringExtra information about a charge for the customer's credit card statement. It must contain at least one letter. If not specified and this invoice is part of a subscription, the default
statement_descriptorwill be set to the first subscription item's product'sstatement_descriptor.subscriptionstringThe ID of the subscription to invoice, if any. If set, the created invoice will only include pending invoice items for that subscription. The subscription's billing cycle and regular subscription events won't be affected.
transfer_dataobjectIf specified, the funds from the invoice will be transferred to the destination and the ID of the resulting transfer will be found on the invoice's charge.
Show 2 child parameters
destinationstringRequiredamountinteger
Returns
The invoice object.
curl -X POST https://api.knoxapi.com/v1/invoices \
-H "Authorization: Bearer $KNOX_SECRET_KEY"const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const invoice = await stripe.invoices.create();import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
invoice = client.v1.invoices.create()require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
invoice = Stripe::Invoice.create(){
"account_country": "US",
"account_name": null,
"account_tax_ids": null,
"amount_due": 1000,
"amount_paid": 0,
"amount_remaining": 1000,
"amount_shipping": 0,
"application": null,
"attempt_count": 0,
"attempted": false,
"auto_advance": false,
"automatic_tax": {
"enabled": false,
"liability": {
"type": "account"
},
"status": null,
"disabled_reason": null,
"provider": null
},
"billing_reason": "manual",
"collection_method": "charge_automatically",
"created": 1234567890,
"currency": "usd",
"custom_fields": null,
"customer": "cus_QXg1o8vcGmoR32",
"customer_address": {
"city": null,
"country": null,
"line1": null,
"line2": null,
"postal_code": null,
"state": null
},
"customer_email": null,
"customer_name": null,
"customer_phone": null,
"customer_shipping": {},
"customer_tax_exempt": "none",
"customer_tax_ids": [],
"default_payment_method": null,
"default_source": null,
"default_tax_rates": [],
"description": null,
"discounts": [],
"due_date": 1234567890,
"effective_at": 1234567890,
"ending_balance": null,
"footer": null,
"from_invoice": {
"action": "action",
"invoice": "invoice"
},
"hosted_invoice_url": null,
"id": "in_1Pgc6tB7WZ01zgkWu9fdqL6I",
"invoice_pdf": null,
"issuer": {
"type": "self"
},
"last_finalization_error": {
"type": "idempotency_error"
},
"latest_revision": null,
"lines": {
"data": [
{
"amount": 1000,
"currency": "usd",
"description": "My First Invoice Item (created for API docs)",
"discount_amounts": [],
"discountable": true,
"discounts": [],
"id": "il_1Pgc6sB7WZ01zgkWFnxLrLCq",
"invoice": "in_1Pgc6tB7WZ01zgkWu9fdqL6I",
"livemode": false,
"metadata": {},
"object": "line_item",
"period": {
"end": 1721954054,
"start": 1721954054
},
"quantity": 1,
"subscription": null,
"pretax_credit_amounts": null,
"taxes": null,
"parent": {
"invoice_item_details": {
"invoice_item": "invoice_item",
"proration": true,
"proration_details": {
"credited_items": {
"invoice": "invoice",
"invoice_line_items": [
"invoice_line_items"
]
}
},
"subscription": null
},
"subscription_item_details": {
"invoice_item": null,
"proration": true,
"proration_details": {
"credited_items": {
"invoice": "invoice",
"invoice_line_items": [
"invoice_line_items"
]
}
},
"subscription": "subscription",
"subscription_item": "subscription_item"
},
"type": "invoice_item_details"
},
"pricing": {
"type": "price_details",
"unit_amount_decimal": null
},
"subtotal": 2060319484,
"quantity_decimal": null
}
],
"has_more": false,
"object": "list",
"url": "/v1/invoices/in_1Pgc6tB7WZ01zgkWu9fdqL6I/lines"
},
"livemode": false,
"metadata": {},
"next_payment_attempt": 1234567890,
"number": null,
"object": "invoice",
"on_behalf_of": null,
"payment_settings": {
"default_mandate": null,
"payment_method_options": {
"acss_debit": {},
"bancontact": {
"preferred_language": "fr"
},
"card": {
"request_three_d_secure": null
},
"customer_balance": {
"funding_type": null
},
"konbini": {},
"sepa_debit": {},
"us_bank_account": {},
"payto": {},
"pix": {
"amount_includes_iof": null
},
"upi": {},
"billie": {}
},
"payment_method_types": null
},
"period_end": 1234567890,
"period_start": 1234567890,
"post_payment_credit_notes_amount": 0,
"pre_payment_credit_notes_amount": 0,
"receipt_number": null,
"rendering": {
"amount_tax_display": null,
"pdf": {
"page_size": null
},
"template": null,
"template_version": null
},
"shipping_cost": {
"amount_subtotal": 1555417355,
"amount_tax": 1424534716,
"amount_total": 1117121693,
"shipping_rate": null
},
"shipping_details": {},
"starting_balance": 0,
"statement_descriptor": null,
"status": "draft",
"status_transitions": {
"finalized_at": null,
"marked_uncollectible_at": null,
"paid_at": null,
"voided_at": null
},
"subscription": null,
"subtotal": 1000,
"subtotal_excluding_tax": 1000,
"test_clock": null,
"total": 1000,
"total_discount_amounts": [],
"total_excluding_tax": 1000,
"webhooks_delivered_at": 1234567890,
"automatically_finalizes_at": null,
"total_pretax_credit_amounts": null,
"total_taxes": null,
"amount_overpaid": 149300825,
"parent": {
"quote_details": {
"quote": "quote"
},
"subscription_details": {
"metadata": null,
"subscription": "subscription"
},
"type": "quote_details"
},
"customer_account": null
}List all invoices
GET/v1/invoices
You can list all invoices, or list the invoices for a specific customer. The invoices are returned sorted by creation date, with the most recently created invoices appearing first.
Query parameters
collection_methodstringThe collection method of the invoice to retrieve. Either
charge_automaticallyorsend_invoice.Possible valuescharge_automaticallysend_invoice
createdobject | integerOnly return invoices that were created during the given date interval.
Show 4 child parameters
gtintegergteintegerltintegerlteinteger
customerstringOnly return invoices for the customer specified by this customer ID.
customer_accountstringOnly return invoices for the account representing the customer specified by this account ID.
due_dateobject | integerShow 4 child parameters
gtintegergteintegerltintegerlteinteger
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.
limitintegerA limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
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.statusstringThe status of the invoice, one of
draft,open,paid,uncollectible, orvoid. Learn morePossible valuesdraftopenpaiduncollectiblevoid
subscriptionstringOnly return invoices for the subscription specified by this subscription ID.
Returns
A list of invoice objects.
curl -G https://api.knoxapi.com/v1/invoices \
-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.invoices.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.invoices.list(params={
"limit": 3,
})require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
page = Stripe::Invoice.list({
limit: 3,
}){
"object": "list",
"url": "/v1/invoices",
"has_more": false,
"data": [
{
"account_country": "US",
"account_name": null,
"account_tax_ids": null,
"amount_due": 1000,
"amount_paid": 0,
"amount_remaining": 1000,
"amount_shipping": 0,
"application": null,
"attempt_count": 0,
"attempted": false,
"auto_advance": false,
"automatic_tax": {
"enabled": false,
"liability": {
"type": "account"
},
"status": null,
"disabled_reason": null,
"provider": null
},
"billing_reason": "manual",
"collection_method": "charge_automatically",
"created": 1234567890,
"currency": "usd",
"custom_fields": null,
"customer": "cus_QXg1o8vcGmoR32",
"customer_address": {
"city": null,
"country": null,
"line1": null,
"line2": null,
"postal_code": null,
"state": null
},
"customer_email": null,
"customer_name": null,
"customer_phone": null,
"customer_shipping": {},
"customer_tax_exempt": "none",
"customer_tax_ids": [],
"default_payment_method": null,
"default_source": null,
"default_tax_rates": [],
"description": null,
"discounts": [],
"due_date": 1234567890,
"effective_at": 1234567890,
"ending_balance": null,
"footer": null,
"from_invoice": {
"action": "action",
"invoice": "invoice"
},
"hosted_invoice_url": null,
"id": "in_1Pgc6tB7WZ01zgkWu9fdqL6I",
"invoice_pdf": null,
"issuer": {
"type": "self"
},
"last_finalization_error": {
"type": "idempotency_error"
},
"latest_revision": null,
"lines": {
"data": [
{
"amount": 1000,
"currency": "usd",
"description": "My First Invoice Item (created for API docs)",
"discount_amounts": [],
"discountable": true,
"discounts": [],
"id": "il_1Pgc6sB7WZ01zgkWFnxLrLCq",
"invoice": "in_1Pgc6tB7WZ01zgkWu9fdqL6I",
"livemode": false,
"metadata": {},
"object": "line_item",
"period": {
"end": 1721954054,
"start": 1721954054
},
"quantity": 1,
"subscription": null,
"pretax_credit_amounts": null,
"taxes": null,
"parent": {
"invoice_item_details": {
"invoice_item": "invoice_item",
"proration": true,
"proration_details": {
"credited_items": {
"invoice": "invoice",
"invoice_line_items": [
"invoice_line_items"
]
}
},
"subscription": null
},
"subscription_item_details": {
"invoice_item": null,
"proration": true,
"proration_details": {
"credited_items": {
"invoice": "invoice",
"invoice_line_items": [
"invoice_line_items"
]
}
},
"subscription": "subscription",
"subscription_item": "subscription_item"
},
"type": "invoice_item_details"
},
"pricing": {
"type": "price_details",
"unit_amount_decimal": null
},
"subtotal": 2060319484,
"quantity_decimal": null
}
],
"has_more": false,
"object": "list",
"url": "/v1/invoices/in_1Pgc6tB7WZ01zgkWu9fdqL6I/lines"
},
"livemode": false,
"metadata": {},
"next_payment_attempt": 1234567890,
"number": null,
"object": "invoice",
"on_behalf_of": null,
"payment_settings": {
"default_mandate": null,
"payment_method_options": {
"acss_debit": {},
"bancontact": {
"preferred_language": "fr"
},
"card": {
"request_three_d_secure": null
},
"customer_balance": {
"funding_type": null
},
"konbini": {},
"sepa_debit": {},
"us_bank_account": {},
"payto": {},
"pix": {
"amount_includes_iof": null
},
"upi": {},
"billie": {}
},
"payment_method_types": null
},
"period_end": 1234567890,
"period_start": 1234567890,
"post_payment_credit_notes_amount": 0,
"pre_payment_credit_notes_amount": 0,
"receipt_number": null,
"rendering": {
"amount_tax_display": null,
"pdf": {
"page_size": null
},
"template": null,
"template_version": null
},
"shipping_cost": {
"amount_subtotal": 1555417355,
"amount_tax": 1424534716,
"amount_total": 1117121693,
"shipping_rate": null
},
"shipping_details": {},
"starting_balance": 0,
"statement_descriptor": null,
"status": "draft",
"status_transitions": {
"finalized_at": null,
"marked_uncollectible_at": null,
"paid_at": null,
"voided_at": null
},
"subscription": null,
"subtotal": 1000,
"subtotal_excluding_tax": 1000,
"test_clock": null,
"total": 1000,
"total_discount_amounts": [],
"total_excluding_tax": 1000,
"webhooks_delivered_at": 1234567890,
"automatically_finalizes_at": null,
"total_pretax_credit_amounts": null,
"total_taxes": null,
"amount_overpaid": 149300825,
"parent": {
"quote_details": {
"quote": "quote"
},
"subscription_details": {
"metadata": null,
"subscription": "subscription"
},
"type": "quote_details"
},
"customer_account": null
}
]
}Create a preview invoice
POST/v1/invoices/create_preview
At any time, you can preview the upcoming invoice for a subscription or subscription schedule. This will show you all the charges that are pending, including subscription renewal charges, invoice item charges, etc. It will also show you any discounts that are applicable to the invoice. You can also preview the effects of creating or updating a subscription or subscription schedule, including a preview of any prorations that will take place. To ensure that the actual proration is calculated exactly the same as the previewed proration, you should pass the subscription_details.proration_date parameter when doing the actual subscription update. The recommended way to get only the prorations being previewed on the invoice is to consider line items where parent.subscription_item_details.proration is true. Note that when you are viewing an upcoming invoice, you are simply viewing a preview – the invoice has not yet been created. As such, the upcoming invoice will not show up in invoice listing calls, and you cannot use the API to pay or edit the invoice. If you want to change the amount that your customer will be billed, you can add, remove, or update pending invoice items, or update the customer’s discount. Note: Currency conversion calculations use the latest exchange rates. Exchange rates may vary between the time of the preview and the time of the actual invoice creation. Learn more
Body parameters
automatic_taxobjectSettings for automatic tax lookup for this invoice preview.
Show 2 child parameters
enabledbooleanRequiredliabilityobjectShow 2 child parameters
typestringRequiredPossible valuesaccountself
accountstring
currencystringThe currency to preview this invoice in. Defaults to that of
customerif not specified.customerstringThe identifier of the customer whose upcoming invoice you're retrieving. If
automatic_taxis enabled then one ofcustomer,customer_details,subscription, orschedulemust be set.customer_accountstringThe identifier of the account representing the customer whose upcoming invoice you're retrieving. If
automatic_taxis enabled then one ofcustomer,customer_account,customer_details,subscription, orschedulemust be set.customer_detailsobjectDetails about the customer you want to invoice or overrides for an existing customer. If
automatic_taxis enabled then one ofcustomer,customer_details,subscription, orschedulemust be set.Show 5 child parameters
addressobjectShow 6 child parameters
citystringcountrystringline1stringline2stringpostal_codestringstatestring
shippingobjectShow 3 child parameters
addressobjectRequiredChild parameters are listed in the OpenAPI document.
namestringRequiredphonestring
taxobjectShow 1 child parameter
ip_addressstring
tax_exemptstringPossible valuesexemptnonereverse
tax_idsarray of objectsShow 2 child parameters
typestringRequiredPossible valuesad_nrtae_trnal_tinam_tinao_tinar_cuitau_abnau_arnaw_tinaz_tinba_tinbb_tinbd_binbf_ifubg_uicbh_vat- and 101 more
valuestringRequired
discountsarray of objectsThe coupons to redeem into discounts for the invoice preview. If not specified, inherits the discount from the subscription or customer. This works for both coupons directly applied to an invoice and coupons applied to a subscription. Pass an empty string to avoid inheriting any discounts.
Show 3 child parameters
couponstringdiscountstringpromotion_codestring
expandarray of stringsSpecifies which fields in the response should be expanded.
invoice_itemsarray of objectsList of invoice items to add or update in the upcoming invoice preview (up to 250).
Show 17 child parameters
amountintegercurrencystringdescriptionstringdiscountablebooleandiscountsarray of objectsShow 3 child parameters
couponstringdiscountstringpromotion_codestring
invoiceitemstringmetadataobjectperiodobjectShow 2 child parameters
endintegerRequiredstartintegerRequired
pricestringprice_dataobjectShow 5 child parameters
currencystringRequiredproductstringRequiredtax_behaviorstringPossible valuesexclusiveinclusiveunspecified
unit_amountintegerunit_amount_decimalstring
quantityintegerquantity_decimalstringtax_behaviorstringPossible valuesexclusiveinclusiveunspecified
tax_codestringtax_ratesarray of stringsunit_amountintegerunit_amount_decimalstring
issuerobjectThe connected account that issues the invoice. The invoice is presented with the branding and support information of the specified account.
Show 2 child parameters
typestringRequiredPossible valuesaccountself
accountstring
on_behalf_ofstringThe account (if any) for which the funds of the invoice payment are intended. If set, the invoice will be presented with the branding and support information of the specified account. See the Invoices with Connect documentation for details.
preview_modestringCustomizes the types of values to include when calculating the invoice. Defaults to
nextif unspecified.Possible valuesnextrecurring
schedulestringThe identifier of the schedule whose upcoming invoice you'd like to retrieve. Cannot be used with subscription or subscription fields.
schedule_detailsobjectThe schedule creation or modification params to apply as a preview. Cannot be used with
subscriptionorsubscription_prefixed fields.Show 4 child parameters
billing_modeobjectShow 2 child parameters
typestringRequiredPossible valuesclassicflexible
flexibleobjectChild parameters are listed in the OpenAPI document.
end_behaviorstringPossible valuescancelrelease
phasesarray of objectsShow 21 child parameters
itemsarray of objectsRequiredChild parameters are listed in the OpenAPI document.
add_invoice_itemsarray of objectsChild parameters are listed in the OpenAPI document.
application_fee_percentnumberautomatic_taxobjectChild parameters are listed in the OpenAPI document.
billing_cycle_anchorstringPossible valuesautomaticphase_start
billing_thresholdsobjectChild parameters are listed in the OpenAPI document.
collection_methodstringPossible valuescharge_automaticallysend_invoice
default_payment_methodstringdefault_tax_ratesarray of stringsdescriptionstringdiscountsarray of objectsChild parameters are listed in the OpenAPI document.
durationobjectChild parameters are listed in the OpenAPI document.
end_dateinteger | stringPossible valuesnow
invoice_settingsobjectChild parameters are listed in the OpenAPI document.
metadataobjecton_behalf_ofstringproration_behaviorstringPossible valuesalways_invoicecreate_prorationsnone
start_dateinteger | stringPossible valuesnow
transfer_dataobjectChild parameters are listed in the OpenAPI document.
trialbooleantrial_endinteger | stringPossible valuesnow
proration_behaviorstringPossible valuesalways_invoicecreate_prorationsnone
subscriptionstringThe identifier of the subscription for which you'd like to retrieve the upcoming invoice. If not provided, but a
subscription_details.itemsis provided, you will preview creating a subscription with those items. If neithersubscriptionnorsubscription_details.itemsis provided, you will retrieve the next upcoming invoice from among the customer's subscriptions.subscription_detailsobjectThe subscription creation or modification params to apply as a preview. Cannot be used with
scheduleorschedule_detailsfields.Show 14 child parameters
billing_cycle_anchorstring | integerPossible valuesnowunchanged
billing_modeobjectShow 2 child parameters
typestringRequiredPossible valuesclassicflexible
flexibleobjectChild parameters are listed in the OpenAPI document.
billing_schedulesarray of objectsShow 3 child parameters
applies_toarray of objectsChild parameters are listed in the OpenAPI document.
bill_untilobjectChild parameters are listed in the OpenAPI document.
keystring
cancel_atinteger | stringPossible valuesmax_billed_untilmax_period_endmin_period_end
cancel_at_period_endbooleancancel_nowbooleandefault_tax_ratesarray of stringsitemsarray of objectsShow 10 child parameters
billing_thresholdsobjectChild parameters are listed in the OpenAPI document.
clear_usagebooleandeletedbooleandiscountsarray of objectsChild parameters are listed in the OpenAPI document.
idstringmetadataobjectpricestringprice_dataobjectChild parameters are listed in the OpenAPI document.
quantityintegertax_ratesarray of strings
metadataobjectproration_behaviorstringPossible valuesalways_invoicecreate_prorationsnone
proration_dateintegerresume_atstringPossible valuesnow
start_dateintegertrial_endstring | integerPossible valuesnow
Returns
The invoice object.
curl -X POST https://api.knoxapi.com/v1/invoices/create_preview \
-H "Authorization: Bearer $KNOX_SECRET_KEY"const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const response = await stripe.rawRequest('POST', '/v1/invoices/create_preview');import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
response = client.raw_request("post", "/v1/invoices/create_preview")require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
response = Stripe.raw_request(:post, '/v1/invoices/create_preview'){
"account_country": "US",
"account_name": null,
"account_tax_ids": null,
"amount_due": 1000,
"amount_paid": 0,
"amount_remaining": 1000,
"amount_shipping": 0,
"application": null,
"attempt_count": 0,
"attempted": false,
"auto_advance": false,
"automatic_tax": {
"enabled": false,
"liability": {
"type": "account"
},
"status": null,
"disabled_reason": null,
"provider": null
},
"billing_reason": "manual",
"collection_method": "charge_automatically",
"created": 1234567890,
"currency": "usd",
"custom_fields": null,
"customer": "cus_QXg1o8vcGmoR32",
"customer_address": {
"city": null,
"country": null,
"line1": null,
"line2": null,
"postal_code": null,
"state": null
},
"customer_email": null,
"customer_name": null,
"customer_phone": null,
"customer_shipping": {},
"customer_tax_exempt": "none",
"customer_tax_ids": [],
"default_payment_method": null,
"default_source": null,
"default_tax_rates": [],
"description": null,
"discounts": [],
"due_date": 1234567890,
"effective_at": 1234567890,
"ending_balance": null,
"footer": null,
"from_invoice": {
"action": "action",
"invoice": "invoice"
},
"hosted_invoice_url": null,
"id": "in_1Pgc6tB7WZ01zgkWu9fdqL6I",
"invoice_pdf": null,
"issuer": {
"type": "self"
},
"last_finalization_error": {
"type": "idempotency_error"
},
"latest_revision": null,
"lines": {
"data": [
{
"amount": 1000,
"currency": "usd",
"description": "My First Invoice Item (created for API docs)",
"discount_amounts": [],
"discountable": true,
"discounts": [],
"id": "il_1Pgc6sB7WZ01zgkWFnxLrLCq",
"invoice": "in_1Pgc6tB7WZ01zgkWu9fdqL6I",
"livemode": false,
"metadata": {},
"object": "line_item",
"period": {
"end": 1721954054,
"start": 1721954054
},
"quantity": 1,
"subscription": null,
"pretax_credit_amounts": null,
"taxes": null,
"parent": {
"invoice_item_details": {
"invoice_item": "invoice_item",
"proration": true,
"proration_details": {
"credited_items": {
"invoice": "invoice",
"invoice_line_items": [
"invoice_line_items"
]
}
},
"subscription": null
},
"subscription_item_details": {
"invoice_item": null,
"proration": true,
"proration_details": {
"credited_items": {
"invoice": "invoice",
"invoice_line_items": [
"invoice_line_items"
]
}
},
"subscription": "subscription",
"subscription_item": "subscription_item"
},
"type": "invoice_item_details"
},
"pricing": {
"type": "price_details",
"unit_amount_decimal": null
},
"subtotal": 2060319484,
"quantity_decimal": null
}
],
"has_more": false,
"object": "list",
"url": "/v1/invoices/in_1Pgc6tB7WZ01zgkWu9fdqL6I/lines"
},
"livemode": false,
"metadata": {},
"next_payment_attempt": 1234567890,
"number": null,
"object": "invoice",
"on_behalf_of": null,
"payment_settings": {
"default_mandate": null,
"payment_method_options": {
"acss_debit": {},
"bancontact": {
"preferred_language": "fr"
},
"card": {
"request_three_d_secure": null
},
"customer_balance": {
"funding_type": null
},
"konbini": {},
"sepa_debit": {},
"us_bank_account": {},
"payto": {},
"pix": {
"amount_includes_iof": null
},
"upi": {},
"billie": {}
},
"payment_method_types": null
},
"period_end": 1234567890,
"period_start": 1234567890,
"post_payment_credit_notes_amount": 0,
"pre_payment_credit_notes_amount": 0,
"receipt_number": null,
"rendering": {
"amount_tax_display": null,
"pdf": {
"page_size": null
},
"template": null,
"template_version": null
},
"shipping_cost": {
"amount_subtotal": 1555417355,
"amount_tax": 1424534716,
"amount_total": 1117121693,
"shipping_rate": null
},
"shipping_details": {},
"starting_balance": 0,
"statement_descriptor": null,
"status": "draft",
"status_transitions": {
"finalized_at": null,
"marked_uncollectible_at": null,
"paid_at": null,
"voided_at": null
},
"subscription": null,
"subtotal": 1000,
"subtotal_excluding_tax": 1000,
"test_clock": null,
"total": 1000,
"total_discount_amounts": [],
"total_excluding_tax": 1000,
"webhooks_delivered_at": 1234567890,
"automatically_finalizes_at": null,
"total_pretax_credit_amounts": null,
"total_taxes": null,
"amount_overpaid": 149300825,
"parent": {
"quote_details": {
"quote": "quote"
},
"subscription_details": {
"metadata": null,
"subscription": "subscription"
},
"type": "quote_details"
},
"customer_account": null
}Search invoices
GET/v1/invoices/search
Search for invoices you’ve previously created using Stripe’s Search Query Language. Don’t use search in read-after-write flows where strict consistency is necessary. Under normal operating conditions, data is searchable in less than a minute. Occasionally, propagation of new or updated data can be up to an hour behind during outages. Search functionality is not available to merchants in India.
Query parameters
querystringRequiredThe search query string. See search query language and the list of supported query fields for invoices.
expandarray of stringsSpecifies which fields in the response should be expanded.
limitintegerA limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
pagestringA cursor for pagination across multiple pages of results. Don't include this parameter on the first call. Use the next_page value returned in a previous response to request subsequent results.
Returns
A search result of invoice objects.
curl -G https://api.knoxapi.com/v1/invoices/search \
-H "Authorization: Bearer $KNOX_SECRET_KEY" \
--data-urlencode "query=metadata['order_id']:'6735'"const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const page = await stripe.invoices.search({
query: "metadata['order_id']:'6735'",
});import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
page = client.v1.invoices.search(params={
"query": "metadata['order_id']:'6735'",
})require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
page = Stripe::Invoice.search({
query: "metadata['order_id']:'6735'",
}){
"object": "search_result",
"url": "/v1/invoices/search",
"has_more": false,
"data": [
{
"account_country": "US",
"account_name": null,
"account_tax_ids": null,
"amount_due": 1000,
"amount_paid": 0,
"amount_remaining": 1000,
"amount_shipping": 0,
"application": null,
"attempt_count": 0,
"attempted": false,
"auto_advance": false,
"automatic_tax": {
"enabled": false,
"liability": {
"type": "account"
},
"status": null,
"disabled_reason": null,
"provider": null
},
"billing_reason": "manual",
"collection_method": "charge_automatically",
"created": 1234567890,
"currency": "usd",
"custom_fields": null,
"customer": "cus_QXg1o8vcGmoR32",
"customer_address": {
"city": null,
"country": null,
"line1": null,
"line2": null,
"postal_code": null,
"state": null
},
"customer_email": null,
"customer_name": null,
"customer_phone": null,
"customer_shipping": {},
"customer_tax_exempt": "none",
"customer_tax_ids": [],
"default_payment_method": null,
"default_source": null,
"default_tax_rates": [],
"description": null,
"discounts": [],
"due_date": 1234567890,
"effective_at": 1234567890,
"ending_balance": null,
"footer": null,
"from_invoice": {
"action": "action",
"invoice": "invoice"
},
"hosted_invoice_url": null,
"id": "in_1Pgc6tB7WZ01zgkWu9fdqL6I",
"invoice_pdf": null,
"issuer": {
"type": "self"
},
"last_finalization_error": {
"type": "idempotency_error"
},
"latest_revision": null,
"lines": {
"data": [
{
"amount": 1000,
"currency": "usd",
"description": "My First Invoice Item (created for API docs)",
"discount_amounts": [],
"discountable": true,
"discounts": [],
"id": "il_1Pgc6sB7WZ01zgkWFnxLrLCq",
"invoice": "in_1Pgc6tB7WZ01zgkWu9fdqL6I",
"livemode": false,
"metadata": {},
"object": "line_item",
"period": {
"end": 1721954054,
"start": 1721954054
},
"quantity": 1,
"subscription": null,
"pretax_credit_amounts": null,
"taxes": null,
"parent": {
"invoice_item_details": {
"invoice_item": "invoice_item",
"proration": true,
"proration_details": {
"credited_items": {
"invoice": "invoice",
"invoice_line_items": [
"invoice_line_items"
]
}
},
"subscription": null
},
"subscription_item_details": {
"invoice_item": null,
"proration": true,
"proration_details": {
"credited_items": {
"invoice": "invoice",
"invoice_line_items": [
"invoice_line_items"
]
}
},
"subscription": "subscription",
"subscription_item": "subscription_item"
},
"type": "invoice_item_details"
},
"pricing": {
"type": "price_details",
"unit_amount_decimal": null
},
"subtotal": 2060319484,
"quantity_decimal": null
}
],
"has_more": false,
"object": "list",
"url": "/v1/invoices/in_1Pgc6tB7WZ01zgkWu9fdqL6I/lines"
},
"livemode": false,
"metadata": {},
"next_payment_attempt": 1234567890,
"number": null,
"object": "invoice",
"on_behalf_of": null,
"payment_settings": {
"default_mandate": null,
"payment_method_options": {
"acss_debit": {},
"bancontact": {
"preferred_language": "fr"
},
"card": {
"request_three_d_secure": null
},
"customer_balance": {
"funding_type": null
},
"konbini": {},
"sepa_debit": {},
"us_bank_account": {},
"payto": {},
"pix": {
"amount_includes_iof": null
},
"upi": {},
"billie": {}
},
"payment_method_types": null
},
"period_end": 1234567890,
"period_start": 1234567890,
"post_payment_credit_notes_amount": 0,
"pre_payment_credit_notes_amount": 0,
"receipt_number": null,
"rendering": {
"amount_tax_display": null,
"pdf": {
"page_size": null
},
"template": null,
"template_version": null
},
"shipping_cost": {
"amount_subtotal": 1555417355,
"amount_tax": 1424534716,
"amount_total": 1117121693,
"shipping_rate": null
},
"shipping_details": {},
"starting_balance": 0,
"statement_descriptor": null,
"status": "draft",
"status_transitions": {
"finalized_at": null,
"marked_uncollectible_at": null,
"paid_at": null,
"voided_at": null
},
"subscription": null,
"subtotal": 1000,
"subtotal_excluding_tax": 1000,
"test_clock": null,
"total": 1000,
"total_discount_amounts": [],
"total_excluding_tax": 1000,
"webhooks_delivered_at": 1234567890,
"automatically_finalizes_at": null,
"total_pretax_credit_amounts": null,
"total_taxes": null,
"amount_overpaid": 149300825,
"parent": {
"quote_details": {
"quote": "quote"
},
"subscription_details": {
"metadata": null,
"subscription": "subscription"
},
"type": "quote_details"
},
"customer_account": null
}
],
"next_page": null
}Update an invoice
POST/v1/invoices/{invoice}
Draft invoices are fully editable. Once an invoice is finalized, monetary values, as well as collection_method, become uneditable. If you would like to stop the Stripe Billing engine from automatically finalizing, reattempting payments on, sending reminders for, or automatically reconciling invoices, pass auto_advance=false.
Path parameters
invoicestringRequired
Body parameters
account_tax_idsarray of stringsThe account tax IDs associated with the invoice. Only editable when the invoice is a draft.
application_fee_amountintegerA fee in cents (or local equivalent) that will be applied to the invoice and transferred to the application owner's Stripe account. The request must be made with an OAuth key or the Stripe-Account header in order to take an application fee. For more information, see the application fees documentation.
auto_advancebooleanControls whether Stripe performs automatic collection of the invoice.
automatic_taxobjectSettings for automatic tax lookup for this invoice.
Show 2 child parameters
enabledbooleanRequiredliabilityobjectShow 2 child parameters
typestringRequiredPossible valuesaccountself
accountstring
automatically_finalizes_atintegerThe time when this invoice should be scheduled to finalize (up to 5 years in the future). The invoice is finalized at this time if it's still in draft state. To turn off automatic finalization, set
auto_advanceto false.collection_methodstringEither
charge_automaticallyorsend_invoice. This field can be updated only ondraftinvoices.Possible valuescharge_automaticallysend_invoice
custom_fieldsarray of objectsA list of up to 4 custom fields to be displayed on the invoice. If a value for
custom_fieldsis specified, the list specified will replace the existing custom field list on this invoice. Pass an empty string to remove previously-defined fields.Show 2 child parameters
namestringRequiredvaluestringRequired
days_until_dueintegerThe number of days from which the invoice is created until it is due. Only valid for invoices where
collection_method=send_invoice. This field can only be updated ondraftinvoices.default_payment_methodstringID of the default payment method for the invoice. It must belong to the customer associated with the invoice. If not set, defaults to the subscription's default payment method, if any, or to the default payment method in the customer's invoice settings.
default_sourcestringID of the default payment source for the invoice. It must belong to the customer associated with the invoice and be in a chargeable state. If not set, defaults to the subscription's default source, if any, or to the customer's default source.
default_tax_ratesarray of stringsThe tax rates that will apply to any line item that does not have
tax_ratesset. Pass an empty string to remove previously-defined tax rates.descriptionstringAn arbitrary string attached to the object. Often useful for displaying to users. Referenced as 'memo' in the Dashboard.
discountsarray of objectsThe discounts that will apply to the invoice. Pass an empty string to remove previously-defined discounts.
Show 3 child parameters
couponstringdiscountstringpromotion_codestring
due_dateintegerThe date on which payment for this invoice is due. Only valid for invoices where
collection_method=send_invoice. This field can only be updated ondraftinvoices.effective_atintegerThe date when this invoice is in effect. Same as
finalized_atunless overwritten. When defined, this value replaces the system-generated 'Date of issue' printed on the invoice PDF and receipt.expandarray of stringsSpecifies which fields in the response should be expanded.
footerstringFooter to be displayed on the invoice.
issuerobjectThe connected account that issues the invoice. The invoice is presented with the branding and support information of the specified account.
Show 2 child parameters
typestringRequiredPossible valuesaccountself
accountstring
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.numberstringSet the number for this invoice. If no number is present then a number will be assigned automatically when the invoice is finalized. In many markets, regulations require invoices to be unique, sequential and / or gapless. You are responsible for ensuring this is true across all your different invoicing systems in the event that you edit the invoice number using our API. If you use only Stripe for your invoices and do not change invoice numbers, Stripe handles this aspect of compliance for you automatically.
on_behalf_ofstringThe account (if any) for which the funds of the invoice payment are intended. If set, the invoice will be presented with the branding and support information of the specified account. See the Invoices with Connect documentation for details.
payment_settingsobjectConfiguration settings for the PaymentIntent that is generated when the invoice is finalized.
Show 3 child parameters
default_mandatestringpayment_method_optionsobjectShow 11 child parameters
acss_debitobjectChild parameters are listed in the OpenAPI document.
bancontactobjectChild parameters are listed in the OpenAPI document.
billieobjectcardobjectChild parameters are listed in the OpenAPI document.
customer_balanceobjectChild parameters are listed in the OpenAPI document.
konbiniobjectpaytoobjectChild parameters are listed in the OpenAPI document.
pixobjectChild parameters are listed in the OpenAPI document.
sepa_debitobjectupiobjectChild parameters are listed in the OpenAPI document.
us_bank_accountobjectChild parameters are listed in the OpenAPI document.
payment_method_typesarray of strings
renderingobjectThe rendering-related settings that control how the invoice is displayed on customer-facing surfaces such as PDF and Hosted Invoice Page.
Show 4 child parameters
amount_tax_displaystringPossible valuesexclude_taxinclude_inclusive_tax
pdfobjectShow 1 child parameter
page_sizestringPossible valuesa4autoletter
templatestringtemplate_versioninteger
shipping_costobjectSettings for the cost of shipping for this invoice.
Show 2 child parameters
shipping_ratestringshipping_rate_dataobjectShow 7 child parameters
display_namestringRequireddelivery_estimateobjectChild parameters are listed in the OpenAPI document.
fixed_amountobjectChild parameters are listed in the OpenAPI document.
metadataobjecttax_behaviorstringPossible valuesexclusiveinclusiveunspecified
tax_codestringtypestringPossible valuesfixed_amount
shipping_detailsobjectShipping details for the invoice. The Invoice PDF will use the
shipping_detailsvalue if it is set, otherwise the PDF will render the shipping address from the customer.Show 3 child parameters
addressobjectRequiredShow 6 child parameters
citystringcountrystringline1stringline2stringpostal_codestringstatestring
namestringRequiredphonestring
statement_descriptorstringExtra information about a charge for the customer's credit card statement. It must contain at least one letter. If not specified and this invoice is part of a subscription, the default
statement_descriptorwill be set to the first subscription item's product'sstatement_descriptor.transfer_dataobjectIf specified, the funds from the invoice will be transferred to the destination and the ID of the resulting transfer will be found on the invoice's charge. This will be unset if you POST an empty value.
Show 2 child parameters
destinationstringRequiredamountinteger
Returns
The invoice object.
curl https://api.knoxapi.com/v1/invoices/in_1Pgc6tB7WZ01zgkWu9fdqL6I \
-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 invoice = await stripe.invoices.update('in_1Pgc6tB7WZ01zgkWu9fdqL6I', {
metadata: {
order_id: '6735',
},
});import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
invoice = client.v1.invoices.update("in_1Pgc6tB7WZ01zgkWu9fdqL6I", params={
"metadata": {
"order_id": "6735",
},
})require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
invoice = Stripe::Invoice.update('in_1Pgc6tB7WZ01zgkWu9fdqL6I', {
metadata: {
order_id: '6735',
},
}){
"account_country": "US",
"account_name": null,
"account_tax_ids": null,
"amount_due": 1000,
"amount_paid": 0,
"amount_remaining": 1000,
"amount_shipping": 0,
"application": null,
"attempt_count": 0,
"attempted": false,
"auto_advance": false,
"automatic_tax": {
"enabled": false,
"liability": {
"type": "account"
},
"status": null,
"disabled_reason": null,
"provider": null
},
"billing_reason": "manual",
"collection_method": "charge_automatically",
"created": 1234567890,
"currency": "usd",
"custom_fields": null,
"customer": "cus_QXg1o8vcGmoR32",
"customer_address": {
"city": null,
"country": null,
"line1": null,
"line2": null,
"postal_code": null,
"state": null
},
"customer_email": null,
"customer_name": null,
"customer_phone": null,
"customer_shipping": {},
"customer_tax_exempt": "none",
"customer_tax_ids": [],
"default_payment_method": null,
"default_source": null,
"default_tax_rates": [],
"description": null,
"discounts": [],
"due_date": 1234567890,
"effective_at": 1234567890,
"ending_balance": null,
"footer": null,
"from_invoice": {
"action": "action",
"invoice": "invoice"
},
"hosted_invoice_url": null,
"id": "in_1Pgc6tB7WZ01zgkWu9fdqL6I",
"invoice_pdf": null,
"issuer": {
"type": "self"
},
"last_finalization_error": {
"type": "idempotency_error"
},
"latest_revision": null,
"lines": {
"data": [
{
"amount": 1000,
"currency": "usd",
"description": "My First Invoice Item (created for API docs)",
"discount_amounts": [],
"discountable": true,
"discounts": [],
"id": "il_1Pgc6sB7WZ01zgkWFnxLrLCq",
"invoice": "in_1Pgc6tB7WZ01zgkWu9fdqL6I",
"livemode": false,
"metadata": {},
"object": "line_item",
"period": {
"end": 1721954054,
"start": 1721954054
},
"quantity": 1,
"subscription": null,
"pretax_credit_amounts": null,
"taxes": null,
"parent": {
"invoice_item_details": {
"invoice_item": "invoice_item",
"proration": true,
"proration_details": {
"credited_items": {
"invoice": "invoice",
"invoice_line_items": [
"invoice_line_items"
]
}
},
"subscription": null
},
"subscription_item_details": {
"invoice_item": null,
"proration": true,
"proration_details": {
"credited_items": {
"invoice": "invoice",
"invoice_line_items": [
"invoice_line_items"
]
}
},
"subscription": "subscription",
"subscription_item": "subscription_item"
},
"type": "invoice_item_details"
},
"pricing": {
"type": "price_details",
"unit_amount_decimal": null
},
"subtotal": 2060319484,
"quantity_decimal": null
}
],
"has_more": false,
"object": "list",
"url": "/v1/invoices/in_1Pgc6tB7WZ01zgkWu9fdqL6I/lines"
},
"livemode": false,
"metadata": {},
"next_payment_attempt": 1234567890,
"number": null,
"object": "invoice",
"on_behalf_of": null,
"payment_settings": {
"default_mandate": null,
"payment_method_options": {
"acss_debit": {},
"bancontact": {
"preferred_language": "fr"
},
"card": {
"request_three_d_secure": null
},
"customer_balance": {
"funding_type": null
},
"konbini": {},
"sepa_debit": {},
"us_bank_account": {},
"payto": {},
"pix": {
"amount_includes_iof": null
},
"upi": {},
"billie": {}
},
"payment_method_types": null
},
"period_end": 1234567890,
"period_start": 1234567890,
"post_payment_credit_notes_amount": 0,
"pre_payment_credit_notes_amount": 0,
"receipt_number": null,
"rendering": {
"amount_tax_display": null,
"pdf": {
"page_size": null
},
"template": null,
"template_version": null
},
"shipping_cost": {
"amount_subtotal": 1555417355,
"amount_tax": 1424534716,
"amount_total": 1117121693,
"shipping_rate": null
},
"shipping_details": {},
"starting_balance": 0,
"statement_descriptor": null,
"status": "draft",
"status_transitions": {
"finalized_at": null,
"marked_uncollectible_at": null,
"paid_at": null,
"voided_at": null
},
"subscription": null,
"subtotal": 1000,
"subtotal_excluding_tax": 1000,
"test_clock": null,
"total": 1000,
"total_discount_amounts": [],
"total_excluding_tax": 1000,
"webhooks_delivered_at": 1234567890,
"automatically_finalizes_at": null,
"total_pretax_credit_amounts": null,
"total_taxes": null,
"amount_overpaid": 149300825,
"parent": {
"quote_details": {
"quote": "quote"
},
"subscription_details": {
"metadata": null,
"subscription": "subscription"
},
"type": "quote_details"
},
"customer_account": null
}Retrieve an invoice
GET/v1/invoices/{invoice}
Retrieves the invoice with the given ID.
Path parameters
invoicestringRequired
Query parameters
expandarray of stringsSpecifies which fields in the response should be expanded.
Returns
The invoice object.
curl https://api.knoxapi.com/v1/invoices/in_1Pgc6tB7WZ01zgkWu9fdqL6I \
-H "Authorization: Bearer $KNOX_SECRET_KEY"const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const invoice = await stripe.invoices.retrieve('in_1Pgc6tB7WZ01zgkWu9fdqL6I');import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
invoice = client.v1.invoices.retrieve("in_1Pgc6tB7WZ01zgkWu9fdqL6I")require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
invoice = Stripe::Invoice.retrieve('in_1Pgc6tB7WZ01zgkWu9fdqL6I'){
"account_country": "US",
"account_name": null,
"account_tax_ids": null,
"amount_due": 1000,
"amount_paid": 0,
"amount_remaining": 1000,
"amount_shipping": 0,
"application": null,
"attempt_count": 0,
"attempted": false,
"auto_advance": false,
"automatic_tax": {
"enabled": false,
"liability": {
"type": "account"
},
"status": null,
"disabled_reason": null,
"provider": null
},
"billing_reason": "manual",
"collection_method": "charge_automatically",
"created": 1234567890,
"currency": "usd",
"custom_fields": null,
"customer": "cus_QXg1o8vcGmoR32",
"customer_address": {
"city": null,
"country": null,
"line1": null,
"line2": null,
"postal_code": null,
"state": null
},
"customer_email": null,
"customer_name": null,
"customer_phone": null,
"customer_shipping": {},
"customer_tax_exempt": "none",
"customer_tax_ids": [],
"default_payment_method": null,
"default_source": null,
"default_tax_rates": [],
"description": null,
"discounts": [],
"due_date": 1234567890,
"effective_at": 1234567890,
"ending_balance": null,
"footer": null,
"from_invoice": {
"action": "action",
"invoice": "invoice"
},
"hosted_invoice_url": null,
"id": "in_1Pgc6tB7WZ01zgkWu9fdqL6I",
"invoice_pdf": null,
"issuer": {
"type": "self"
},
"last_finalization_error": {
"type": "idempotency_error"
},
"latest_revision": null,
"lines": {
"data": [
{
"amount": 1000,
"currency": "usd",
"description": "My First Invoice Item (created for API docs)",
"discount_amounts": [],
"discountable": true,
"discounts": [],
"id": "il_1Pgc6sB7WZ01zgkWFnxLrLCq",
"invoice": "in_1Pgc6tB7WZ01zgkWu9fdqL6I",
"livemode": false,
"metadata": {},
"object": "line_item",
"period": {
"end": 1721954054,
"start": 1721954054
},
"quantity": 1,
"subscription": null,
"pretax_credit_amounts": null,
"taxes": null,
"parent": {
"invoice_item_details": {
"invoice_item": "invoice_item",
"proration": true,
"proration_details": {
"credited_items": {
"invoice": "invoice",
"invoice_line_items": [
"invoice_line_items"
]
}
},
"subscription": null
},
"subscription_item_details": {
"invoice_item": null,
"proration": true,
"proration_details": {
"credited_items": {
"invoice": "invoice",
"invoice_line_items": [
"invoice_line_items"
]
}
},
"subscription": "subscription",
"subscription_item": "subscription_item"
},
"type": "invoice_item_details"
},
"pricing": {
"type": "price_details",
"unit_amount_decimal": null
},
"subtotal": 2060319484,
"quantity_decimal": null
}
],
"has_more": false,
"object": "list",
"url": "/v1/invoices/in_1Pgc6tB7WZ01zgkWu9fdqL6I/lines"
},
"livemode": false,
"metadata": {},
"next_payment_attempt": 1234567890,
"number": null,
"object": "invoice",
"on_behalf_of": null,
"payment_settings": {
"default_mandate": null,
"payment_method_options": {
"acss_debit": {},
"bancontact": {
"preferred_language": "fr"
},
"card": {
"request_three_d_secure": null
},
"customer_balance": {
"funding_type": null
},
"konbini": {},
"sepa_debit": {},
"us_bank_account": {},
"payto": {},
"pix": {
"amount_includes_iof": null
},
"upi": {},
"billie": {}
},
"payment_method_types": null
},
"period_end": 1234567890,
"period_start": 1234567890,
"post_payment_credit_notes_amount": 0,
"pre_payment_credit_notes_amount": 0,
"receipt_number": null,
"rendering": {
"amount_tax_display": null,
"pdf": {
"page_size": null
},
"template": null,
"template_version": null
},
"shipping_cost": {
"amount_subtotal": 1555417355,
"amount_tax": 1424534716,
"amount_total": 1117121693,
"shipping_rate": null
},
"shipping_details": {},
"starting_balance": 0,
"statement_descriptor": null,
"status": "draft",
"status_transitions": {
"finalized_at": null,
"marked_uncollectible_at": null,
"paid_at": null,
"voided_at": null
},
"subscription": null,
"subtotal": 1000,
"subtotal_excluding_tax": 1000,
"test_clock": null,
"total": 1000,
"total_discount_amounts": [],
"total_excluding_tax": 1000,
"webhooks_delivered_at": 1234567890,
"automatically_finalizes_at": null,
"total_pretax_credit_amounts": null,
"total_taxes": null,
"amount_overpaid": 149300825,
"parent": {
"quote_details": {
"quote": "quote"
},
"subscription_details": {
"metadata": null,
"subscription": "subscription"
},
"type": "quote_details"
},
"customer_account": null
}Delete a draft invoice
DELETE/v1/invoices/{invoice}
Permanently deletes a one-off invoice draft. This cannot be undone. Attempts to delete invoices that are no longer in a draft state will fail; once an invoice has been finalized or if an invoice is for a subscription, it must be voided.
Path parameters
invoicestringRequired
Returns
The deleted_invoice object.
curl -X DELETE https://api.knoxapi.com/v1/invoices/in_1Pgc6tB7WZ01zgkWu9fdqL6I \
-H "Authorization: Bearer $KNOX_SECRET_KEY"const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const deletedInvoice = await stripe.invoices.del('in_1Pgc6tB7WZ01zgkWu9fdqL6I');import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
deleted_invoice = client.v1.invoices.delete("in_1Pgc6tB7WZ01zgkWu9fdqL6I")require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
deleted_invoice = Stripe::Invoice.delete('in_1Pgc6tB7WZ01zgkWu9fdqL6I'){
"deleted": true,
"id": "in_1Pgc6tB7WZ01zgkWu9fdqL6I",
"object": "invoice"
}Bulk add invoice line items
POST/v1/invoices/{invoice}/add_lines
Adds multiple line items to an invoice. This is only possible when an invoice is still a draft.
Path parameters
invoicestringRequired
Body parameters
linesarray of objectsRequiredThe line items to add.
Show 13 child parameters
amountintegerdescriptionstringdiscountablebooleandiscountsarray of objectsShow 3 child parameters
couponstringdiscountstringpromotion_codestring
invoice_itemstringmetadataobjectperiodobjectShow 2 child parameters
endintegerRequiredstartintegerRequired
price_dataobjectShow 6 child parameters
currencystringRequiredproductstringproduct_dataobjectChild parameters are listed in the OpenAPI document.
tax_behaviorstringPossible valuesexclusiveinclusiveunspecified
unit_amountintegerunit_amount_decimalstring
pricingobjectShow 1 child parameter
pricestring
quantityintegerquantity_decimalstringtax_amountsarray of objectsShow 4 child parameters
amountintegerRequiredtax_rate_dataobjectRequiredChild parameters are listed in the OpenAPI document.
taxable_amountintegerRequiredtaxability_reasonstringPossible valuescustomer_exemptnot_collectingnot_subject_to_taxnot_supportedportion_product_exemptportion_reduced_ratedportion_standard_ratedproduct_exemptproduct_exempt_holidayproportionally_ratedreduced_ratedreverse_chargestandard_ratedtaxable_basis_reducedzero_rated
tax_ratesarray of strings
expandarray of stringsSpecifies which fields in the response should be expanded.
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.
Returns
The invoice object.
curl https://api.knoxapi.com/v1/invoices/in_1Pgc6tB7WZ01zgkWu9fdqL6I/add_lines \
-H "Authorization: Bearer $KNOX_SECRET_KEY" \
-d "lines[0]="const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const invoice = await stripe.invoices.addLines('in_1Pgc6tB7WZ01zgkWu9fdqL6I', {
lines: [{}],
});import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
invoice = client.v1.invoices.add_lines("in_1Pgc6tB7WZ01zgkWu9fdqL6I", params={
"lines": [{}],
})require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
invoice = Stripe::Invoice.add_lines('in_1Pgc6tB7WZ01zgkWu9fdqL6I', {
lines: [{}],
}){
"account_country": "US",
"account_name": null,
"account_tax_ids": null,
"amount_due": 1000,
"amount_paid": 0,
"amount_remaining": 1000,
"amount_shipping": 0,
"application": null,
"attempt_count": 0,
"attempted": false,
"auto_advance": false,
"automatic_tax": {
"enabled": false,
"liability": {
"type": "account"
},
"status": null,
"disabled_reason": null,
"provider": null
},
"billing_reason": "manual",
"collection_method": "charge_automatically",
"created": 1234567890,
"currency": "usd",
"custom_fields": null,
"customer": "cus_QXg1o8vcGmoR32",
"customer_address": {
"city": null,
"country": null,
"line1": null,
"line2": null,
"postal_code": null,
"state": null
},
"customer_email": null,
"customer_name": null,
"customer_phone": null,
"customer_shipping": {},
"customer_tax_exempt": "none",
"customer_tax_ids": [],
"default_payment_method": null,
"default_source": null,
"default_tax_rates": [],
"description": null,
"discounts": [],
"due_date": 1234567890,
"effective_at": 1234567890,
"ending_balance": null,
"footer": null,
"from_invoice": {
"action": "action",
"invoice": "invoice"
},
"hosted_invoice_url": null,
"id": "in_1Pgc6tB7WZ01zgkWu9fdqL6I",
"invoice_pdf": null,
"issuer": {
"type": "self"
},
"last_finalization_error": {
"type": "idempotency_error"
},
"latest_revision": null,
"lines": {
"data": [
{
"amount": 1000,
"currency": "usd",
"description": "My First Invoice Item (created for API docs)",
"discount_amounts": [],
"discountable": true,
"discounts": [],
"id": "il_1Pgc6sB7WZ01zgkWFnxLrLCq",
"invoice": "in_1Pgc6tB7WZ01zgkWu9fdqL6I",
"livemode": false,
"metadata": {},
"object": "line_item",
"period": {
"end": 1721954054,
"start": 1721954054
},
"quantity": 1,
"subscription": null,
"pretax_credit_amounts": null,
"taxes": null,
"parent": {
"invoice_item_details": {
"invoice_item": "invoice_item",
"proration": true,
"proration_details": {
"credited_items": {
"invoice": "invoice",
"invoice_line_items": [
"invoice_line_items"
]
}
},
"subscription": null
},
"subscription_item_details": {
"invoice_item": null,
"proration": true,
"proration_details": {
"credited_items": {
"invoice": "invoice",
"invoice_line_items": [
"invoice_line_items"
]
}
},
"subscription": "subscription",
"subscription_item": "subscription_item"
},
"type": "invoice_item_details"
},
"pricing": {
"type": "price_details",
"unit_amount_decimal": null
},
"subtotal": 2060319484,
"quantity_decimal": null
}
],
"has_more": false,
"object": "list",
"url": "/v1/invoices/in_1Pgc6tB7WZ01zgkWu9fdqL6I/lines"
},
"livemode": false,
"metadata": {},
"next_payment_attempt": 1234567890,
"number": null,
"object": "invoice",
"on_behalf_of": null,
"payment_settings": {
"default_mandate": null,
"payment_method_options": {
"acss_debit": {},
"bancontact": {
"preferred_language": "fr"
},
"card": {
"request_three_d_secure": null
},
"customer_balance": {
"funding_type": null
},
"konbini": {},
"sepa_debit": {},
"us_bank_account": {},
"payto": {},
"pix": {
"amount_includes_iof": null
},
"upi": {},
"billie": {}
},
"payment_method_types": null
},
"period_end": 1234567890,
"period_start": 1234567890,
"post_payment_credit_notes_amount": 0,
"pre_payment_credit_notes_amount": 0,
"receipt_number": null,
"rendering": {
"amount_tax_display": null,
"pdf": {
"page_size": null
},
"template": null,
"template_version": null
},
"shipping_cost": {
"amount_subtotal": 1555417355,
"amount_tax": 1424534716,
"amount_total": 1117121693,
"shipping_rate": null
},
"shipping_details": {},
"starting_balance": 0,
"statement_descriptor": null,
"status": "draft",
"status_transitions": {
"finalized_at": null,
"marked_uncollectible_at": null,
"paid_at": null,
"voided_at": null
},
"subscription": null,
"subtotal": 1000,
"subtotal_excluding_tax": 1000,
"test_clock": null,
"total": 1000,
"total_discount_amounts": [],
"total_excluding_tax": 1000,
"webhooks_delivered_at": 1234567890,
"automatically_finalizes_at": null,
"total_pretax_credit_amounts": null,
"total_taxes": null,
"amount_overpaid": 149300825,
"parent": {
"quote_details": {
"quote": "quote"
},
"subscription_details": {
"metadata": null,
"subscription": "subscription"
},
"type": "quote_details"
},
"customer_account": null
}Attach a payment to an Invoice
POST/v1/invoices/{invoice}/attach_payment
Attaches a PaymentIntent or an Out of Band Payment to the invoice, adding it to the list of payments. For the PaymentIntent, when the PaymentIntent’s status changes to succeeded, the payment is credited to the invoice, increasing its amount_paid. When the invoice is fully paid, the invoice’s status becomes paid. If the PaymentIntent’s status is already succeeded when it’s attached, it’s credited to the invoice immediately. See: Partial payments to learn more.
Path parameters
invoicestringRequired
Body parameters
expandarray of stringsSpecifies which fields in the response should be expanded.
payment_intentstringThe ID of the PaymentIntent to attach to the invoice.
payment_recordstringThe ID of the PaymentRecord to attach to the invoice.
Returns
The invoice object.
curl -X POST https://api.knoxapi.com/v1/invoices/in_1Pgc6tB7WZ01zgkWu9fdqL6I/attach_payment \
-H "Authorization: Bearer $KNOX_SECRET_KEY"const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const invoice = await stripe.invoices.attachPayment('in_1Pgc6tB7WZ01zgkWu9fdqL6I');import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
invoice = client.v1.invoices.attach_payment("in_1Pgc6tB7WZ01zgkWu9fdqL6I")require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
invoice = Stripe::Invoice.attach_payment('in_1Pgc6tB7WZ01zgkWu9fdqL6I'){
"account_country": "US",
"account_name": null,
"account_tax_ids": null,
"amount_due": 1000,
"amount_paid": 0,
"amount_remaining": 1000,
"amount_shipping": 0,
"application": null,
"attempt_count": 0,
"attempted": false,
"auto_advance": false,
"automatic_tax": {
"enabled": false,
"liability": {
"type": "account"
},
"status": null,
"disabled_reason": null,
"provider": null
},
"billing_reason": "manual",
"collection_method": "charge_automatically",
"created": 1234567890,
"currency": "usd",
"custom_fields": null,
"customer": "cus_QXg1o8vcGmoR32",
"customer_address": {
"city": null,
"country": null,
"line1": null,
"line2": null,
"postal_code": null,
"state": null
},
"customer_email": null,
"customer_name": null,
"customer_phone": null,
"customer_shipping": {},
"customer_tax_exempt": "none",
"customer_tax_ids": [],
"default_payment_method": null,
"default_source": null,
"default_tax_rates": [],
"description": null,
"discounts": [],
"due_date": 1234567890,
"effective_at": 1234567890,
"ending_balance": null,
"footer": null,
"from_invoice": {
"action": "action",
"invoice": "invoice"
},
"hosted_invoice_url": null,
"id": "in_1Pgc6tB7WZ01zgkWu9fdqL6I",
"invoice_pdf": null,
"issuer": {
"type": "self"
},
"last_finalization_error": {
"type": "idempotency_error"
},
"latest_revision": null,
"lines": {
"data": [
{
"amount": 1000,
"currency": "usd",
"description": "My First Invoice Item (created for API docs)",
"discount_amounts": [],
"discountable": true,
"discounts": [],
"id": "il_1Pgc6sB7WZ01zgkWFnxLrLCq",
"invoice": "in_1Pgc6tB7WZ01zgkWu9fdqL6I",
"livemode": false,
"metadata": {},
"object": "line_item",
"period": {
"end": 1721954054,
"start": 1721954054
},
"quantity": 1,
"subscription": null,
"pretax_credit_amounts": null,
"taxes": null,
"parent": {
"invoice_item_details": {
"invoice_item": "invoice_item",
"proration": true,
"proration_details": {
"credited_items": {
"invoice": "invoice",
"invoice_line_items": [
"invoice_line_items"
]
}
},
"subscription": null
},
"subscription_item_details": {
"invoice_item": null,
"proration": true,
"proration_details": {
"credited_items": {
"invoice": "invoice",
"invoice_line_items": [
"invoice_line_items"
]
}
},
"subscription": "subscription",
"subscription_item": "subscription_item"
},
"type": "invoice_item_details"
},
"pricing": {
"type": "price_details",
"unit_amount_decimal": null
},
"subtotal": 2060319484,
"quantity_decimal": null
}
],
"has_more": false,
"object": "list",
"url": "/v1/invoices/in_1Pgc6tB7WZ01zgkWu9fdqL6I/lines"
},
"livemode": false,
"metadata": {},
"next_payment_attempt": 1234567890,
"number": null,
"object": "invoice",
"on_behalf_of": null,
"payment_settings": {
"default_mandate": null,
"payment_method_options": {
"acss_debit": {},
"bancontact": {
"preferred_language": "fr"
},
"card": {
"request_three_d_secure": null
},
"customer_balance": {
"funding_type": null
},
"konbini": {},
"sepa_debit": {},
"us_bank_account": {},
"payto": {},
"pix": {
"amount_includes_iof": null
},
"upi": {},
"billie": {}
},
"payment_method_types": null
},
"period_end": 1234567890,
"period_start": 1234567890,
"post_payment_credit_notes_amount": 0,
"pre_payment_credit_notes_amount": 0,
"receipt_number": null,
"rendering": {
"amount_tax_display": null,
"pdf": {
"page_size": null
},
"template": null,
"template_version": null
},
"shipping_cost": {
"amount_subtotal": 1555417355,
"amount_tax": 1424534716,
"amount_total": 1117121693,
"shipping_rate": null
},
"shipping_details": {},
"starting_balance": 0,
"statement_descriptor": null,
"status": "draft",
"status_transitions": {
"finalized_at": null,
"marked_uncollectible_at": null,
"paid_at": null,
"voided_at": null
},
"subscription": null,
"subtotal": 1000,
"subtotal_excluding_tax": 1000,
"test_clock": null,
"total": 1000,
"total_discount_amounts": [],
"total_excluding_tax": 1000,
"webhooks_delivered_at": 1234567890,
"automatically_finalizes_at": null,
"total_pretax_credit_amounts": null,
"total_taxes": null,
"amount_overpaid": 149300825,
"parent": {
"quote_details": {
"quote": "quote"
},
"subscription_details": {
"metadata": null,
"subscription": "subscription"
},
"type": "quote_details"
},
"customer_account": null
}Finalize an invoice
POST/v1/invoices/{invoice}/finalize
Stripe automatically finalizes drafts before sending and attempting payment on invoices. However, if you’d like to finalize a draft invoice manually, you can do so using this method.
Path parameters
invoicestringRequired
Body parameters
auto_advancebooleanControls whether Stripe performs automatic collection of the invoice. If
false, the invoice's state doesn't automatically advance without an explicit action.expandarray of stringsSpecifies which fields in the response should be expanded.
Returns
The invoice object.
curl -X POST https://api.knoxapi.com/v1/invoices/in_1Pgc6tB7WZ01zgkWu9fdqL6I/finalize \
-H "Authorization: Bearer $KNOX_SECRET_KEY"const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const invoice = await stripe.invoices.finalizeInvoice('in_1Pgc6tB7WZ01zgkWu9fdqL6I');import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
invoice = client.v1.invoices.finalize_invoice("in_1Pgc6tB7WZ01zgkWu9fdqL6I")require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
invoice = Stripe::Invoice.finalize_invoice('in_1Pgc6tB7WZ01zgkWu9fdqL6I'){
"account_country": "US",
"account_name": null,
"account_tax_ids": null,
"amount_due": 1000,
"amount_paid": 0,
"amount_remaining": 1000,
"amount_shipping": 0,
"application": null,
"attempt_count": 0,
"attempted": false,
"auto_advance": false,
"automatic_tax": {
"enabled": false,
"liability": {
"type": "account"
},
"status": null,
"disabled_reason": null,
"provider": null
},
"billing_reason": "manual",
"collection_method": "charge_automatically",
"created": 1234567890,
"currency": "usd",
"custom_fields": null,
"customer": "cus_QXg1o8vcGmoR32",
"customer_address": {
"city": null,
"country": null,
"line1": null,
"line2": null,
"postal_code": null,
"state": null
},
"customer_email": null,
"customer_name": null,
"customer_phone": null,
"customer_shipping": {},
"customer_tax_exempt": "none",
"customer_tax_ids": [],
"default_payment_method": null,
"default_source": null,
"default_tax_rates": [],
"description": null,
"discounts": [],
"due_date": 1234567890,
"effective_at": 1234567890,
"ending_balance": null,
"footer": null,
"from_invoice": {
"action": "action",
"invoice": "invoice"
},
"hosted_invoice_url": null,
"id": "in_1Pgc6tB7WZ01zgkWu9fdqL6I",
"invoice_pdf": null,
"issuer": {
"type": "self"
},
"last_finalization_error": {
"type": "idempotency_error"
},
"latest_revision": null,
"lines": {
"data": [
{
"amount": 1000,
"currency": "usd",
"description": "My First Invoice Item (created for API docs)",
"discount_amounts": [],
"discountable": true,
"discounts": [],
"id": "il_1Pgc6sB7WZ01zgkWFnxLrLCq",
"invoice": "in_1Pgc6tB7WZ01zgkWu9fdqL6I",
"livemode": false,
"metadata": {},
"object": "line_item",
"period": {
"end": 1721954054,
"start": 1721954054
},
"quantity": 1,
"subscription": null,
"pretax_credit_amounts": null,
"taxes": null,
"parent": {
"invoice_item_details": {
"invoice_item": "invoice_item",
"proration": true,
"proration_details": {
"credited_items": {
"invoice": "invoice",
"invoice_line_items": [
"invoice_line_items"
]
}
},
"subscription": null
},
"subscription_item_details": {
"invoice_item": null,
"proration": true,
"proration_details": {
"credited_items": {
"invoice": "invoice",
"invoice_line_items": [
"invoice_line_items"
]
}
},
"subscription": "subscription",
"subscription_item": "subscription_item"
},
"type": "invoice_item_details"
},
"pricing": {
"type": "price_details",
"unit_amount_decimal": null
},
"subtotal": 2060319484,
"quantity_decimal": null
}
],
"has_more": false,
"object": "list",
"url": "/v1/invoices/in_1Pgc6tB7WZ01zgkWu9fdqL6I/lines"
},
"livemode": false,
"metadata": {},
"next_payment_attempt": 1234567890,
"number": null,
"object": "invoice",
"on_behalf_of": null,
"payment_settings": {
"default_mandate": null,
"payment_method_options": {
"acss_debit": {},
"bancontact": {
"preferred_language": "fr"
},
"card": {
"request_three_d_secure": null
},
"customer_balance": {
"funding_type": null
},
"konbini": {},
"sepa_debit": {},
"us_bank_account": {},
"payto": {},
"pix": {
"amount_includes_iof": null
},
"upi": {},
"billie": {}
},
"payment_method_types": null
},
"period_end": 1234567890,
"period_start": 1234567890,
"post_payment_credit_notes_amount": 0,
"pre_payment_credit_notes_amount": 0,
"receipt_number": null,
"rendering": {
"amount_tax_display": null,
"pdf": {
"page_size": null
},
"template": null,
"template_version": null
},
"shipping_cost": {
"amount_subtotal": 1555417355,
"amount_tax": 1424534716,
"amount_total": 1117121693,
"shipping_rate": null
},
"shipping_details": {},
"starting_balance": 0,
"statement_descriptor": null,
"status": "draft",
"status_transitions": {
"finalized_at": null,
"marked_uncollectible_at": null,
"paid_at": null,
"voided_at": null
},
"subscription": null,
"subtotal": 1000,
"subtotal_excluding_tax": 1000,
"test_clock": null,
"total": 1000,
"total_discount_amounts": [],
"total_excluding_tax": 1000,
"webhooks_delivered_at": 1234567890,
"automatically_finalizes_at": null,
"total_pretax_credit_amounts": null,
"total_taxes": null,
"amount_overpaid": 149300825,
"parent": {
"quote_details": {
"quote": "quote"
},
"subscription_details": {
"metadata": null,
"subscription": "subscription"
},
"type": "quote_details"
},
"customer_account": null
}Retrieve an invoice's line items
GET/v1/invoices/{invoice}/lines
When retrieving an invoice, you’ll get a lines property containing the total count of line items and the first handful of those items. There is also a URL where you can retrieve the full (paginated) list of line items.
Path parameters
invoicestringRequired
Query parameters
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.
limitintegerA limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
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 line_item objects.
curl -G https://api.knoxapi.com/v1/invoices/in_1Pgc6tB7WZ01zgkWu9fdqL6I/lines \
-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 response = await stripe.rawRequest('GET', '/v1/invoices/in_1Pgc6tB7WZ01zgkWu9fdqL6I/lines', {
limit: 3,
});import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
response = client.raw_request("get", "/v1/invoices/in_1Pgc6tB7WZ01zgkWu9fdqL6I/lines", limit=3)require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
response = Stripe.raw_request(:get, '/v1/invoices/in_1Pgc6tB7WZ01zgkWu9fdqL6I/lines', {
limit: 3,
}){
"object": "list",
"url": "/v1/invoices",
"has_more": false,
"data": [
{
"amount": 1000,
"currency": "usd",
"description": "My First Invoice Item (created for API docs)",
"discount_amounts": [],
"discountable": true,
"discounts": [],
"id": "il_tmp_1Pgc6sB7WZ01zgkWrG16hkdl",
"invoice": "in_1Pgc6tB7WZ01zgkWu9fdqL6I",
"livemode": false,
"metadata": {},
"object": "line_item",
"period": {
"end": 1721954054,
"start": 1721954054
},
"quantity": 1,
"subscription": null,
"pretax_credit_amounts": null,
"taxes": null,
"parent": {
"invoice_item_details": {
"invoice_item": "invoice_item",
"proration": true,
"proration_details": {
"credited_items": {
"invoice": "invoice",
"invoice_line_items": [
"invoice_line_items"
]
}
},
"subscription": null
},
"subscription_item_details": {
"invoice_item": null,
"proration": true,
"proration_details": {
"credited_items": {
"invoice": "invoice",
"invoice_line_items": [
"invoice_line_items"
]
}
},
"subscription": "subscription",
"subscription_item": "subscription_item"
},
"type": "invoice_item_details"
},
"pricing": {
"type": "price_details",
"unit_amount_decimal": null
},
"subtotal": 2060319484,
"quantity_decimal": null
}
]
}Mark an invoice as uncollectible
POST/v1/invoices/{invoice}/mark_uncollectible
Marking an invoice as uncollectible is useful for keeping track of bad debts that can be written off for accounting purposes.
Path parameters
invoicestringRequired
Body parameters
expandarray of stringsSpecifies which fields in the response should be expanded.
Returns
The invoice object.
curl -X POST https://api.knoxapi.com/v1/invoices/in_1Pgc6tB7WZ01zgkWu9fdqL6I/mark_uncollectible \
-H "Authorization: Bearer $KNOX_SECRET_KEY"const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const invoice = await stripe.invoices.markUncollectible('in_1Pgc6tB7WZ01zgkWu9fdqL6I');import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
invoice = client.v1.invoices.mark_uncollectible("in_1Pgc6tB7WZ01zgkWu9fdqL6I")require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
invoice = Stripe::Invoice.mark_uncollectible('in_1Pgc6tB7WZ01zgkWu9fdqL6I'){
"account_country": "US",
"account_name": null,
"account_tax_ids": null,
"amount_due": 1000,
"amount_paid": 0,
"amount_remaining": 1000,
"amount_shipping": 0,
"application": null,
"attempt_count": 0,
"attempted": false,
"auto_advance": false,
"automatic_tax": {
"enabled": false,
"liability": {
"type": "account"
},
"status": null,
"disabled_reason": null,
"provider": null
},
"billing_reason": "manual",
"collection_method": "charge_automatically",
"created": 1234567890,
"currency": "usd",
"custom_fields": null,
"customer": "cus_QXg1o8vcGmoR32",
"customer_address": {
"city": null,
"country": null,
"line1": null,
"line2": null,
"postal_code": null,
"state": null
},
"customer_email": null,
"customer_name": null,
"customer_phone": null,
"customer_shipping": {},
"customer_tax_exempt": "none",
"customer_tax_ids": [],
"default_payment_method": null,
"default_source": null,
"default_tax_rates": [],
"description": null,
"discounts": [],
"due_date": 1234567890,
"effective_at": 1234567890,
"ending_balance": null,
"footer": null,
"from_invoice": {
"action": "action",
"invoice": "invoice"
},
"hosted_invoice_url": null,
"id": "in_1Pgc6tB7WZ01zgkWu9fdqL6I",
"invoice_pdf": null,
"issuer": {
"type": "self"
},
"last_finalization_error": {
"type": "idempotency_error"
},
"latest_revision": null,
"lines": {
"data": [
{
"amount": 1000,
"currency": "usd",
"description": "My First Invoice Item (created for API docs)",
"discount_amounts": [],
"discountable": true,
"discounts": [],
"id": "il_1Pgc6sB7WZ01zgkWFnxLrLCq",
"invoice": "in_1Pgc6tB7WZ01zgkWu9fdqL6I",
"livemode": false,
"metadata": {},
"object": "line_item",
"period": {
"end": 1721954054,
"start": 1721954054
},
"quantity": 1,
"subscription": null,
"pretax_credit_amounts": null,
"taxes": null,
"parent": {
"invoice_item_details": {
"invoice_item": "invoice_item",
"proration": true,
"proration_details": {
"credited_items": {
"invoice": "invoice",
"invoice_line_items": [
"invoice_line_items"
]
}
},
"subscription": null
},
"subscription_item_details": {
"invoice_item": null,
"proration": true,
"proration_details": {
"credited_items": {
"invoice": "invoice",
"invoice_line_items": [
"invoice_line_items"
]
}
},
"subscription": "subscription",
"subscription_item": "subscription_item"
},
"type": "invoice_item_details"
},
"pricing": {
"type": "price_details",
"unit_amount_decimal": null
},
"subtotal": 2060319484,
"quantity_decimal": null
}
],
"has_more": false,
"object": "list",
"url": "/v1/invoices/in_1Pgc6tB7WZ01zgkWu9fdqL6I/lines"
},
"livemode": false,
"metadata": {},
"next_payment_attempt": 1234567890,
"number": null,
"object": "invoice",
"on_behalf_of": null,
"payment_settings": {
"default_mandate": null,
"payment_method_options": {
"acss_debit": {},
"bancontact": {
"preferred_language": "fr"
},
"card": {
"request_three_d_secure": null
},
"customer_balance": {
"funding_type": null
},
"konbini": {},
"sepa_debit": {},
"us_bank_account": {},
"payto": {},
"pix": {
"amount_includes_iof": null
},
"upi": {},
"billie": {}
},
"payment_method_types": null
},
"period_end": 1234567890,
"period_start": 1234567890,
"post_payment_credit_notes_amount": 0,
"pre_payment_credit_notes_amount": 0,
"receipt_number": null,
"rendering": {
"amount_tax_display": null,
"pdf": {
"page_size": null
},
"template": null,
"template_version": null
},
"shipping_cost": {
"amount_subtotal": 1555417355,
"amount_tax": 1424534716,
"amount_total": 1117121693,
"shipping_rate": null
},
"shipping_details": {},
"starting_balance": 0,
"statement_descriptor": null,
"status": "draft",
"status_transitions": {
"finalized_at": null,
"marked_uncollectible_at": null,
"paid_at": null,
"voided_at": null
},
"subscription": null,
"subtotal": 1000,
"subtotal_excluding_tax": 1000,
"test_clock": null,
"total": 1000,
"total_discount_amounts": [],
"total_excluding_tax": 1000,
"webhooks_delivered_at": 1234567890,
"automatically_finalizes_at": null,
"total_pretax_credit_amounts": null,
"total_taxes": null,
"amount_overpaid": 149300825,
"parent": {
"quote_details": {
"quote": "quote"
},
"subscription_details": {
"metadata": null,
"subscription": "subscription"
},
"type": "quote_details"
},
"customer_account": null
}Pay an invoice
POST/v1/invoices/{invoice}/pay
Stripe automatically creates and then attempts to collect payment on invoices for customers on subscriptions according to your subscriptions settings. However, if you’d like to attempt payment on an invoice out of the normal collection schedule or for some other reason, you can do so.
Path parameters
invoicestringRequired
Body parameters
expandarray of stringsSpecifies which fields in the response should be expanded.
forgivebooleanIn cases where the source used to pay the invoice has insufficient funds, passing
forgive=truecontrols whether a charge should be attempted for the full amount available on the source, up to the amount to fully pay the invoice. This effectively forgives the difference between the amount available on the source and the amount due. Passingforgive=falsewill fail the charge if the source hasn't been pre-funded with the right amount. An example for this case is with ACH Credit Transfers and wires: if the amount wired is less than the amount due by a small amount, you might want to forgive the difference. Defaults tofalse.mandatestringID of the mandate to be used for this invoice. It must correspond to the payment method used to pay the invoice, including the payment_method param or the invoice's default_payment_method or default_source, if set.
off_sessionbooleanIndicates if a customer is on or off-session while an invoice payment is attempted. Defaults to
true(off-session).paid_out_of_bandbooleanBoolean representing whether an invoice is paid outside of Stripe. This will result in no charge being made. Defaults to
false.payment_methodstringA PaymentMethod to be charged. The PaymentMethod must be the ID of a PaymentMethod belonging to the customer associated with the invoice being paid.
sourcestringA payment source to be charged. The source must be the ID of a source belonging to the customer associated with the invoice being paid.
Returns
The invoice object.
curl -X POST https://api.knoxapi.com/v1/invoices/in_1Pgc6tB7WZ01zgkWu9fdqL6I/pay \
-H "Authorization: Bearer $KNOX_SECRET_KEY"const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const invoice = await stripe.invoices.pay('in_1Pgc6tB7WZ01zgkWu9fdqL6I');import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
invoice = client.v1.invoices.pay("in_1Pgc6tB7WZ01zgkWu9fdqL6I")require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
invoice = Stripe::Invoice.pay('in_1Pgc6tB7WZ01zgkWu9fdqL6I'){
"account_country": "US",
"account_name": null,
"account_tax_ids": null,
"amount_due": 1000,
"amount_paid": 0,
"amount_remaining": 1000,
"amount_shipping": 0,
"application": null,
"attempt_count": 0,
"attempted": false,
"auto_advance": false,
"automatic_tax": {
"enabled": false,
"liability": {
"type": "account"
},
"status": null,
"disabled_reason": null,
"provider": null
},
"billing_reason": "manual",
"collection_method": "charge_automatically",
"created": 1234567890,
"currency": "usd",
"custom_fields": null,
"customer": "cus_QXg1o8vcGmoR32",
"customer_address": {
"city": null,
"country": null,
"line1": null,
"line2": null,
"postal_code": null,
"state": null
},
"customer_email": null,
"customer_name": null,
"customer_phone": null,
"customer_shipping": {},
"customer_tax_exempt": "none",
"customer_tax_ids": [],
"default_payment_method": null,
"default_source": null,
"default_tax_rates": [],
"description": null,
"discounts": [],
"due_date": 1234567890,
"effective_at": 1234567890,
"ending_balance": null,
"footer": null,
"from_invoice": {
"action": "action",
"invoice": "invoice"
},
"hosted_invoice_url": null,
"id": "in_1Pgc6tB7WZ01zgkWu9fdqL6I",
"invoice_pdf": null,
"issuer": {
"type": "self"
},
"last_finalization_error": {
"type": "idempotency_error"
},
"latest_revision": null,
"lines": {
"data": [
{
"amount": 1000,
"currency": "usd",
"description": "My First Invoice Item (created for API docs)",
"discount_amounts": [],
"discountable": true,
"discounts": [],
"id": "il_1Pgc6sB7WZ01zgkWFnxLrLCq",
"invoice": "in_1Pgc6tB7WZ01zgkWu9fdqL6I",
"livemode": false,
"metadata": {},
"object": "line_item",
"period": {
"end": 1721954054,
"start": 1721954054
},
"quantity": 1,
"subscription": null,
"pretax_credit_amounts": null,
"taxes": null,
"parent": {
"invoice_item_details": {
"invoice_item": "invoice_item",
"proration": true,
"proration_details": {
"credited_items": {
"invoice": "invoice",
"invoice_line_items": [
"invoice_line_items"
]
}
},
"subscription": null
},
"subscription_item_details": {
"invoice_item": null,
"proration": true,
"proration_details": {
"credited_items": {
"invoice": "invoice",
"invoice_line_items": [
"invoice_line_items"
]
}
},
"subscription": "subscription",
"subscription_item": "subscription_item"
},
"type": "invoice_item_details"
},
"pricing": {
"type": "price_details",
"unit_amount_decimal": null
},
"subtotal": 2060319484,
"quantity_decimal": null
}
],
"has_more": false,
"object": "list",
"url": "/v1/invoices/in_1Pgc6tB7WZ01zgkWu9fdqL6I/lines"
},
"livemode": false,
"metadata": {},
"next_payment_attempt": 1234567890,
"number": null,
"object": "invoice",
"on_behalf_of": null,
"payment_settings": {
"default_mandate": null,
"payment_method_options": {
"acss_debit": {},
"bancontact": {
"preferred_language": "fr"
},
"card": {
"request_three_d_secure": null
},
"customer_balance": {
"funding_type": null
},
"konbini": {},
"sepa_debit": {},
"us_bank_account": {},
"payto": {},
"pix": {
"amount_includes_iof": null
},
"upi": {},
"billie": {}
},
"payment_method_types": null
},
"period_end": 1234567890,
"period_start": 1234567890,
"post_payment_credit_notes_amount": 0,
"pre_payment_credit_notes_amount": 0,
"receipt_number": null,
"rendering": {
"amount_tax_display": null,
"pdf": {
"page_size": null
},
"template": null,
"template_version": null
},
"shipping_cost": {
"amount_subtotal": 1555417355,
"amount_tax": 1424534716,
"amount_total": 1117121693,
"shipping_rate": null
},
"shipping_details": {},
"starting_balance": 0,
"statement_descriptor": null,
"status": "draft",
"status_transitions": {
"finalized_at": null,
"marked_uncollectible_at": null,
"paid_at": null,
"voided_at": null
},
"subscription": null,
"subtotal": 1000,
"subtotal_excluding_tax": 1000,
"test_clock": null,
"total": 1000,
"total_discount_amounts": [],
"total_excluding_tax": 1000,
"webhooks_delivered_at": 1234567890,
"automatically_finalizes_at": null,
"total_pretax_credit_amounts": null,
"total_taxes": null,
"amount_overpaid": 149300825,
"parent": {
"quote_details": {
"quote": "quote"
},
"subscription_details": {
"metadata": null,
"subscription": "subscription"
},
"type": "quote_details"
},
"customer_account": null
}Bulk remove invoice line items
POST/v1/invoices/{invoice}/remove_lines
Removes multiple line items from an invoice. This is only possible when an invoice is still a draft.
Path parameters
invoicestringRequired
Body parameters
linesarray of objectsRequiredThe line items to remove.
Show 2 child parameters
behaviorstringRequiredPossible valuesdeleteunassign
idstringRequired
expandarray of stringsSpecifies which fields in the response should be expanded.
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.
Returns
The invoice object.
curl https://api.knoxapi.com/v1/invoices/in_1Pgc6tB7WZ01zgkWu9fdqL6I/remove_lines \
-H "Authorization: Bearer $KNOX_SECRET_KEY" \
-d "lines[0][behavior]=delete" \
-d "lines[0][id]=example"const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const invoice = await stripe.invoices.removeLines('in_1Pgc6tB7WZ01zgkWu9fdqL6I', {
lines: [{
behavior: 'delete',
id: 'example',
}],
});import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
invoice = client.v1.invoices.remove_lines("in_1Pgc6tB7WZ01zgkWu9fdqL6I", params={
"lines": [{
"behavior": "delete",
"id": "example",
}],
})require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
invoice = Stripe::Invoice.remove_lines('in_1Pgc6tB7WZ01zgkWu9fdqL6I', {
lines: [{
behavior: 'delete',
id: 'example',
}],
}){
"account_country": "US",
"account_name": null,
"account_tax_ids": null,
"amount_due": 1000,
"amount_paid": 0,
"amount_remaining": 1000,
"amount_shipping": 0,
"application": null,
"attempt_count": 0,
"attempted": false,
"auto_advance": false,
"automatic_tax": {
"enabled": false,
"liability": {
"type": "account"
},
"status": null,
"disabled_reason": null,
"provider": null
},
"billing_reason": "manual",
"collection_method": "charge_automatically",
"created": 1234567890,
"currency": "usd",
"custom_fields": null,
"customer": "cus_QXg1o8vcGmoR32",
"customer_address": {
"city": null,
"country": null,
"line1": null,
"line2": null,
"postal_code": null,
"state": null
},
"customer_email": null,
"customer_name": null,
"customer_phone": null,
"customer_shipping": {},
"customer_tax_exempt": "none",
"customer_tax_ids": [],
"default_payment_method": null,
"default_source": null,
"default_tax_rates": [],
"description": null,
"discounts": [],
"due_date": 1234567890,
"effective_at": 1234567890,
"ending_balance": null,
"footer": null,
"from_invoice": {
"action": "action",
"invoice": "invoice"
},
"hosted_invoice_url": null,
"id": "in_1Pgc6tB7WZ01zgkWu9fdqL6I",
"invoice_pdf": null,
"issuer": {
"type": "self"
},
"last_finalization_error": {
"type": "idempotency_error"
},
"latest_revision": null,
"lines": {
"data": [
{
"amount": 1000,
"currency": "usd",
"description": "My First Invoice Item (created for API docs)",
"discount_amounts": [],
"discountable": true,
"discounts": [],
"id": "il_1Pgc6sB7WZ01zgkWFnxLrLCq",
"invoice": "in_1Pgc6tB7WZ01zgkWu9fdqL6I",
"livemode": false,
"metadata": {},
"object": "line_item",
"period": {
"end": 1721954054,
"start": 1721954054
},
"quantity": 1,
"subscription": null,
"pretax_credit_amounts": null,
"taxes": null,
"parent": {
"invoice_item_details": {
"invoice_item": "invoice_item",
"proration": true,
"proration_details": {
"credited_items": {
"invoice": "invoice",
"invoice_line_items": [
"invoice_line_items"
]
}
},
"subscription": null
},
"subscription_item_details": {
"invoice_item": null,
"proration": true,
"proration_details": {
"credited_items": {
"invoice": "invoice",
"invoice_line_items": [
"invoice_line_items"
]
}
},
"subscription": "subscription",
"subscription_item": "subscription_item"
},
"type": "invoice_item_details"
},
"pricing": {
"type": "price_details",
"unit_amount_decimal": null
},
"subtotal": 2060319484,
"quantity_decimal": null
}
],
"has_more": false,
"object": "list",
"url": "/v1/invoices/in_1Pgc6tB7WZ01zgkWu9fdqL6I/lines"
},
"livemode": false,
"metadata": {},
"next_payment_attempt": 1234567890,
"number": null,
"object": "invoice",
"on_behalf_of": null,
"payment_settings": {
"default_mandate": null,
"payment_method_options": {
"acss_debit": {},
"bancontact": {
"preferred_language": "fr"
},
"card": {
"request_three_d_secure": null
},
"customer_balance": {
"funding_type": null
},
"konbini": {},
"sepa_debit": {},
"us_bank_account": {},
"payto": {},
"pix": {
"amount_includes_iof": null
},
"upi": {},
"billie": {}
},
"payment_method_types": null
},
"period_end": 1234567890,
"period_start": 1234567890,
"post_payment_credit_notes_amount": 0,
"pre_payment_credit_notes_amount": 0,
"receipt_number": null,
"rendering": {
"amount_tax_display": null,
"pdf": {
"page_size": null
},
"template": null,
"template_version": null
},
"shipping_cost": {
"amount_subtotal": 1555417355,
"amount_tax": 1424534716,
"amount_total": 1117121693,
"shipping_rate": null
},
"shipping_details": {},
"starting_balance": 0,
"statement_descriptor": null,
"status": "draft",
"status_transitions": {
"finalized_at": null,
"marked_uncollectible_at": null,
"paid_at": null,
"voided_at": null
},
"subscription": null,
"subtotal": 1000,
"subtotal_excluding_tax": 1000,
"test_clock": null,
"total": 1000,
"total_discount_amounts": [],
"total_excluding_tax": 1000,
"webhooks_delivered_at": 1234567890,
"automatically_finalizes_at": null,
"total_pretax_credit_amounts": null,
"total_taxes": null,
"amount_overpaid": 149300825,
"parent": {
"quote_details": {
"quote": "quote"
},
"subscription_details": {
"metadata": null,
"subscription": "subscription"
},
"type": "quote_details"
},
"customer_account": null
}Send an invoice for manual payment
POST/v1/invoices/{invoice}/send
Stripe will automatically send invoices to customers according to your subscriptions settings. However, if you’d like to manually send an invoice to your customer out of the normal schedule, you can do so. When sending invoices that have already been paid, there will be no reference to the payment in the email. Requests made in test-mode result in no emails being sent, despite sending an invoice.sent event.
Path parameters
invoicestringRequired
Body parameters
expandarray of stringsSpecifies which fields in the response should be expanded.
Returns
The invoice object.
curl -X POST https://api.knoxapi.com/v1/invoices/in_1Pgc6tB7WZ01zgkWu9fdqL6I/send \
-H "Authorization: Bearer $KNOX_SECRET_KEY"const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const invoice = await stripe.invoices.sendInvoice('in_1Pgc6tB7WZ01zgkWu9fdqL6I');import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
invoice = client.v1.invoices.send_invoice("in_1Pgc6tB7WZ01zgkWu9fdqL6I")require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
invoice = Stripe::Invoice.send_invoice('in_1Pgc6tB7WZ01zgkWu9fdqL6I'){
"account_country": "US",
"account_name": null,
"account_tax_ids": null,
"amount_due": 1000,
"amount_paid": 0,
"amount_remaining": 1000,
"amount_shipping": 0,
"application": null,
"attempt_count": 0,
"attempted": false,
"auto_advance": false,
"automatic_tax": {
"enabled": false,
"liability": {
"type": "account"
},
"status": null,
"disabled_reason": null,
"provider": null
},
"billing_reason": "manual",
"collection_method": "charge_automatically",
"created": 1234567890,
"currency": "usd",
"custom_fields": null,
"customer": "cus_QXg1o8vcGmoR32",
"customer_address": {
"city": null,
"country": null,
"line1": null,
"line2": null,
"postal_code": null,
"state": null
},
"customer_email": null,
"customer_name": null,
"customer_phone": null,
"customer_shipping": {},
"customer_tax_exempt": "none",
"customer_tax_ids": [],
"default_payment_method": null,
"default_source": null,
"default_tax_rates": [],
"description": null,
"discounts": [],
"due_date": 1234567890,
"effective_at": 1234567890,
"ending_balance": null,
"footer": null,
"from_invoice": {
"action": "action",
"invoice": "invoice"
},
"hosted_invoice_url": null,
"id": "in_1Pgc6tB7WZ01zgkWu9fdqL6I",
"invoice_pdf": null,
"issuer": {
"type": "self"
},
"last_finalization_error": {
"type": "idempotency_error"
},
"latest_revision": null,
"lines": {
"data": [
{
"amount": 1000,
"currency": "usd",
"description": "My First Invoice Item (created for API docs)",
"discount_amounts": [],
"discountable": true,
"discounts": [],
"id": "il_1Pgc6sB7WZ01zgkWFnxLrLCq",
"invoice": "in_1Pgc6tB7WZ01zgkWu9fdqL6I",
"livemode": false,
"metadata": {},
"object": "line_item",
"period": {
"end": 1721954054,
"start": 1721954054
},
"quantity": 1,
"subscription": null,
"pretax_credit_amounts": null,
"taxes": null,
"parent": {
"invoice_item_details": {
"invoice_item": "invoice_item",
"proration": true,
"proration_details": {
"credited_items": {
"invoice": "invoice",
"invoice_line_items": [
"invoice_line_items"
]
}
},
"subscription": null
},
"subscription_item_details": {
"invoice_item": null,
"proration": true,
"proration_details": {
"credited_items": {
"invoice": "invoice",
"invoice_line_items": [
"invoice_line_items"
]
}
},
"subscription": "subscription",
"subscription_item": "subscription_item"
},
"type": "invoice_item_details"
},
"pricing": {
"type": "price_details",
"unit_amount_decimal": null
},
"subtotal": 2060319484,
"quantity_decimal": null
}
],
"has_more": false,
"object": "list",
"url": "/v1/invoices/in_1Pgc6tB7WZ01zgkWu9fdqL6I/lines"
},
"livemode": false,
"metadata": {},
"next_payment_attempt": 1234567890,
"number": null,
"object": "invoice",
"on_behalf_of": null,
"payment_settings": {
"default_mandate": null,
"payment_method_options": {
"acss_debit": {},
"bancontact": {
"preferred_language": "fr"
},
"card": {
"request_three_d_secure": null
},
"customer_balance": {
"funding_type": null
},
"konbini": {},
"sepa_debit": {},
"us_bank_account": {},
"payto": {},
"pix": {
"amount_includes_iof": null
},
"upi": {},
"billie": {}
},
"payment_method_types": null
},
"period_end": 1234567890,
"period_start": 1234567890,
"post_payment_credit_notes_amount": 0,
"pre_payment_credit_notes_amount": 0,
"receipt_number": null,
"rendering": {
"amount_tax_display": null,
"pdf": {
"page_size": null
},
"template": null,
"template_version": null
},
"shipping_cost": {
"amount_subtotal": 1555417355,
"amount_tax": 1424534716,
"amount_total": 1117121693,
"shipping_rate": null
},
"shipping_details": {},
"starting_balance": 0,
"statement_descriptor": null,
"status": "draft",
"status_transitions": {
"finalized_at": null,
"marked_uncollectible_at": null,
"paid_at": null,
"voided_at": null
},
"subscription": null,
"subtotal": 1000,
"subtotal_excluding_tax": 1000,
"test_clock": null,
"total": 1000,
"total_discount_amounts": [],
"total_excluding_tax": 1000,
"webhooks_delivered_at": 1234567890,
"automatically_finalizes_at": null,
"total_pretax_credit_amounts": null,
"total_taxes": null,
"amount_overpaid": 149300825,
"parent": {
"quote_details": {
"quote": "quote"
},
"subscription_details": {
"metadata": null,
"subscription": "subscription"
},
"type": "quote_details"
},
"customer_account": null
}Bulk update invoice line items
POST/v1/invoices/{invoice}/update_lines
Updates multiple line items on an invoice. This is only possible when an invoice is still a draft.
Path parameters
invoicestringRequired
Body parameters
linesarray of objectsRequiredThe line items to update.
Show 13 child parameters
idstringRequiredamountintegerdescriptionstringdiscountablebooleandiscountsarray of objectsShow 3 child parameters
couponstringdiscountstringpromotion_codestring
metadataobjectperiodobjectShow 2 child parameters
endintegerRequiredstartintegerRequired
price_dataobjectShow 6 child parameters
currencystringRequiredproductstringproduct_dataobjectChild parameters are listed in the OpenAPI document.
tax_behaviorstringPossible valuesexclusiveinclusiveunspecified
unit_amountintegerunit_amount_decimalstring
pricingobjectShow 1 child parameter
pricestring
quantityintegerquantity_decimalstringtax_amountsarray of objectsShow 4 child parameters
amountintegerRequiredtax_rate_dataobjectRequiredChild parameters are listed in the OpenAPI document.
taxable_amountintegerRequiredtaxability_reasonstringPossible valuescustomer_exemptnot_collectingnot_subject_to_taxnot_supportedportion_product_exemptportion_reduced_ratedportion_standard_ratedproduct_exemptproduct_exempt_holidayproportionally_ratedreduced_ratedreverse_chargestandard_ratedtaxable_basis_reducedzero_rated
tax_ratesarray of strings
expandarray of stringsSpecifies which fields in the response should be expanded.
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. For type=subscription line items, the incoming metadata specified on the request is directly used to set this value, in contrast to type=invoiceitem line items, where any existing metadata on the invoice line is merged with the incoming data.
Returns
The invoice object.
curl https://api.knoxapi.com/v1/invoices/in_1Pgc6tB7WZ01zgkWu9fdqL6I/update_lines \
-H "Authorization: Bearer $KNOX_SECRET_KEY" \
-d "lines[0][id]=example"const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const invoice = await stripe.invoices.updateLines('in_1Pgc6tB7WZ01zgkWu9fdqL6I', {
lines: [{
id: 'example',
}],
});import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
invoice = client.v1.invoices.update_lines("in_1Pgc6tB7WZ01zgkWu9fdqL6I", params={
"lines": [{
"id": "example",
}],
})require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
invoice = Stripe::Invoice.update_lines('in_1Pgc6tB7WZ01zgkWu9fdqL6I', {
lines: [{
id: 'example',
}],
}){
"account_country": "US",
"account_name": null,
"account_tax_ids": null,
"amount_due": 1000,
"amount_paid": 0,
"amount_remaining": 1000,
"amount_shipping": 0,
"application": null,
"attempt_count": 0,
"attempted": false,
"auto_advance": false,
"automatic_tax": {
"enabled": false,
"liability": {
"type": "account"
},
"status": null,
"disabled_reason": null,
"provider": null
},
"billing_reason": "manual",
"collection_method": "charge_automatically",
"created": 1234567890,
"currency": "usd",
"custom_fields": null,
"customer": "cus_QXg1o8vcGmoR32",
"customer_address": {
"city": null,
"country": null,
"line1": null,
"line2": null,
"postal_code": null,
"state": null
},
"customer_email": null,
"customer_name": null,
"customer_phone": null,
"customer_shipping": {},
"customer_tax_exempt": "none",
"customer_tax_ids": [],
"default_payment_method": null,
"default_source": null,
"default_tax_rates": [],
"description": null,
"discounts": [],
"due_date": 1234567890,
"effective_at": 1234567890,
"ending_balance": null,
"footer": null,
"from_invoice": {
"action": "action",
"invoice": "invoice"
},
"hosted_invoice_url": null,
"id": "in_1Pgc6tB7WZ01zgkWu9fdqL6I",
"invoice_pdf": null,
"issuer": {
"type": "self"
},
"last_finalization_error": {
"type": "idempotency_error"
},
"latest_revision": null,
"lines": {
"data": [
{
"amount": 1000,
"currency": "usd",
"description": "My First Invoice Item (created for API docs)",
"discount_amounts": [],
"discountable": true,
"discounts": [],
"id": "il_1Pgc6sB7WZ01zgkWFnxLrLCq",
"invoice": "in_1Pgc6tB7WZ01zgkWu9fdqL6I",
"livemode": false,
"metadata": {},
"object": "line_item",
"period": {
"end": 1721954054,
"start": 1721954054
},
"quantity": 1,
"subscription": null,
"pretax_credit_amounts": null,
"taxes": null,
"parent": {
"invoice_item_details": {
"invoice_item": "invoice_item",
"proration": true,
"proration_details": {
"credited_items": {
"invoice": "invoice",
"invoice_line_items": [
"invoice_line_items"
]
}
},
"subscription": null
},
"subscription_item_details": {
"invoice_item": null,
"proration": true,
"proration_details": {
"credited_items": {
"invoice": "invoice",
"invoice_line_items": [
"invoice_line_items"
]
}
},
"subscription": "subscription",
"subscription_item": "subscription_item"
},
"type": "invoice_item_details"
},
"pricing": {
"type": "price_details",
"unit_amount_decimal": null
},
"subtotal": 2060319484,
"quantity_decimal": null
}
],
"has_more": false,
"object": "list",
"url": "/v1/invoices/in_1Pgc6tB7WZ01zgkWu9fdqL6I/lines"
},
"livemode": false,
"metadata": {},
"next_payment_attempt": 1234567890,
"number": null,
"object": "invoice",
"on_behalf_of": null,
"payment_settings": {
"default_mandate": null,
"payment_method_options": {
"acss_debit": {},
"bancontact": {
"preferred_language": "fr"
},
"card": {
"request_three_d_secure": null
},
"customer_balance": {
"funding_type": null
},
"konbini": {},
"sepa_debit": {},
"us_bank_account": {},
"payto": {},
"pix": {
"amount_includes_iof": null
},
"upi": {},
"billie": {}
},
"payment_method_types": null
},
"period_end": 1234567890,
"period_start": 1234567890,
"post_payment_credit_notes_amount": 0,
"pre_payment_credit_notes_amount": 0,
"receipt_number": null,
"rendering": {
"amount_tax_display": null,
"pdf": {
"page_size": null
},
"template": null,
"template_version": null
},
"shipping_cost": {
"amount_subtotal": 1555417355,
"amount_tax": 1424534716,
"amount_total": 1117121693,
"shipping_rate": null
},
"shipping_details": {},
"starting_balance": 0,
"statement_descriptor": null,
"status": "draft",
"status_transitions": {
"finalized_at": null,
"marked_uncollectible_at": null,
"paid_at": null,
"voided_at": null
},
"subscription": null,
"subtotal": 1000,
"subtotal_excluding_tax": 1000,
"test_clock": null,
"total": 1000,
"total_discount_amounts": [],
"total_excluding_tax": 1000,
"webhooks_delivered_at": 1234567890,
"automatically_finalizes_at": null,
"total_pretax_credit_amounts": null,
"total_taxes": null,
"amount_overpaid": 149300825,
"parent": {
"quote_details": {
"quote": "quote"
},
"subscription_details": {
"metadata": null,
"subscription": "subscription"
},
"type": "quote_details"
},
"customer_account": null
}Void an invoice
POST/v1/invoices/{invoice}/void
Mark a finalized invoice as void. This cannot be undone. Voiding an invoice is similar to deletion, however it only applies to finalized invoices and maintains a papertrail where the invoice can still be found. Consult with local regulations to determine whether and how an invoice might be amended, canceled, or voided in the jurisdiction you’re doing business in. You might need to issue another invoice or credit note instead. Stripe recommends that you consult with your legal counsel for advice specific to your business.
Path parameters
invoicestringRequired
Body parameters
expandarray of stringsSpecifies which fields in the response should be expanded.
Returns
The invoice object.
curl -X POST https://api.knoxapi.com/v1/invoices/in_1Pgc6tB7WZ01zgkWu9fdqL6I/void \
-H "Authorization: Bearer $KNOX_SECRET_KEY"const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const invoice = await stripe.invoices.voidInvoice('in_1Pgc6tB7WZ01zgkWu9fdqL6I');import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
invoice = client.v1.invoices.void_invoice("in_1Pgc6tB7WZ01zgkWu9fdqL6I")require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
invoice = Stripe::Invoice.void_invoice('in_1Pgc6tB7WZ01zgkWu9fdqL6I'){
"account_country": "US",
"account_name": null,
"account_tax_ids": null,
"amount_due": 1000,
"amount_paid": 0,
"amount_remaining": 1000,
"amount_shipping": 0,
"application": null,
"attempt_count": 0,
"attempted": false,
"auto_advance": false,
"automatic_tax": {
"enabled": false,
"liability": {
"type": "account"
},
"status": null,
"disabled_reason": null,
"provider": null
},
"billing_reason": "manual",
"collection_method": "charge_automatically",
"created": 1234567890,
"currency": "usd",
"custom_fields": null,
"customer": "cus_QXg1o8vcGmoR32",
"customer_address": {
"city": null,
"country": null,
"line1": null,
"line2": null,
"postal_code": null,
"state": null
},
"customer_email": null,
"customer_name": null,
"customer_phone": null,
"customer_shipping": {},
"customer_tax_exempt": "none",
"customer_tax_ids": [],
"default_payment_method": null,
"default_source": null,
"default_tax_rates": [],
"description": null,
"discounts": [],
"due_date": 1234567890,
"effective_at": 1234567890,
"ending_balance": null,
"footer": null,
"from_invoice": {
"action": "action",
"invoice": "invoice"
},
"hosted_invoice_url": null,
"id": "in_1Pgc6tB7WZ01zgkWu9fdqL6I",
"invoice_pdf": null,
"issuer": {
"type": "self"
},
"last_finalization_error": {
"type": "idempotency_error"
},
"latest_revision": null,
"lines": {
"data": [
{
"amount": 1000,
"currency": "usd",
"description": "My First Invoice Item (created for API docs)",
"discount_amounts": [],
"discountable": true,
"discounts": [],
"id": "il_1Pgc6sB7WZ01zgkWFnxLrLCq",
"invoice": "in_1Pgc6tB7WZ01zgkWu9fdqL6I",
"livemode": false,
"metadata": {},
"object": "line_item",
"period": {
"end": 1721954054,
"start": 1721954054
},
"quantity": 1,
"subscription": null,
"pretax_credit_amounts": null,
"taxes": null,
"parent": {
"invoice_item_details": {
"invoice_item": "invoice_item",
"proration": true,
"proration_details": {
"credited_items": {
"invoice": "invoice",
"invoice_line_items": [
"invoice_line_items"
]
}
},
"subscription": null
},
"subscription_item_details": {
"invoice_item": null,
"proration": true,
"proration_details": {
"credited_items": {
"invoice": "invoice",
"invoice_line_items": [
"invoice_line_items"
]
}
},
"subscription": "subscription",
"subscription_item": "subscription_item"
},
"type": "invoice_item_details"
},
"pricing": {
"type": "price_details",
"unit_amount_decimal": null
},
"subtotal": 2060319484,
"quantity_decimal": null
}
],
"has_more": false,
"object": "list",
"url": "/v1/invoices/in_1Pgc6tB7WZ01zgkWu9fdqL6I/lines"
},
"livemode": false,
"metadata": {},
"next_payment_attempt": 1234567890,
"number": null,
"object": "invoice",
"on_behalf_of": null,
"payment_settings": {
"default_mandate": null,
"payment_method_options": {
"acss_debit": {},
"bancontact": {
"preferred_language": "fr"
},
"card": {
"request_three_d_secure": null
},
"customer_balance": {
"funding_type": null
},
"konbini": {},
"sepa_debit": {},
"us_bank_account": {},
"payto": {},
"pix": {
"amount_includes_iof": null
},
"upi": {},
"billie": {}
},
"payment_method_types": null
},
"period_end": 1234567890,
"period_start": 1234567890,
"post_payment_credit_notes_amount": 0,
"pre_payment_credit_notes_amount": 0,
"receipt_number": null,
"rendering": {
"amount_tax_display": null,
"pdf": {
"page_size": null
},
"template": null,
"template_version": null
},
"shipping_cost": {
"amount_subtotal": 1555417355,
"amount_tax": 1424534716,
"amount_total": 1117121693,
"shipping_rate": null
},
"shipping_details": {},
"starting_balance": 0,
"statement_descriptor": null,
"status": "draft",
"status_transitions": {
"finalized_at": null,
"marked_uncollectible_at": null,
"paid_at": null,
"voided_at": null
},
"subscription": null,
"subtotal": 1000,
"subtotal_excluding_tax": 1000,
"test_clock": null,
"total": 1000,
"total_discount_amounts": [],
"total_excluding_tax": 1000,
"webhooks_delivered_at": 1234567890,
"automatically_finalizes_at": null,
"total_pretax_credit_amounts": null,
"total_taxes": null,
"amount_overpaid": 149300825,
"parent": {
"quote_details": {
"quote": "quote"
},
"subscription_details": {
"metadata": null,
"subscription": "subscription"
},
"type": "quote_details"
},
"customer_account": null
}Update an invoice's line item
POST/v1/invoices/{invoice}/lines/{line_item_id}
Updates an invoice’s line item. Some fields, such as tax_amounts, only live on the invoice line item, so they can only be updated through this endpoint. Other fields, such as amount, live on both the invoice item and the invoice line item, so updates on this endpoint will propagate to the invoice item as well. Updating an invoice’s line item is only possible before the invoice is finalized.
Path parameters
invoicestringRequiredInvoice ID of line item
line_item_idstringRequiredInvoice line item ID
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 line item. Defaults to false for prorations or negative line items, and true for all other line items. Cannot be set to true for prorations.
discountsarray of objectsThe coupons, promotion codes & existing discounts which apply to the 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. For type=subscription line items, the incoming metadata specified on the request is directly used to set this value, in contrast to type=invoiceitem line items, where any existing metadata on the invoice line is merged with the incoming data.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 6 child parameters
currencystringRequiredproductstringproduct_dataobjectShow 6 child parameters
namestringRequireddescriptionstringimagesarray of stringsmetadataobjecttax_codestringunit_labelstring
tax_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 line 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_amountsarray of objectsA list of up to 20 tax amounts for this line item. This can be useful if you calculate taxes on your own or use a third-party to calculate them. You cannot set tax amounts if any line item has tax_rates or if the invoice has default_tax_rates or uses automatic tax. Pass an empty string to remove previously defined tax amounts.
Show 4 child parameters
amountintegerRequiredtax_rate_dataobjectRequiredShow 9 child parameters
display_namestringRequiredinclusivebooleanRequiredpercentagenumberRequiredcountrystringdescriptionstringjurisdictionstringjurisdiction_levelstringPossible valuescitycountrycountydistrictmultiplestate
statestringtax_typestringPossible valuesamusement_taxcommunications_taxgsthstigstjctlease_taxmass_transit_parking_taxparking_taxpstqstretail_delivery_feerstsales_taxservice_taxvat
taxable_amountintegerRequiredtaxability_reasonstringPossible valuescustomer_exemptnot_collectingnot_subject_to_taxnot_supportedportion_product_exemptportion_reduced_ratedportion_standard_ratedproduct_exemptproduct_exempt_holidayproportionally_ratedreduced_ratedreverse_chargestandard_ratedtaxable_basis_reducedzero_rated
tax_ratesarray of stringsThe tax rates which apply to the line item. When set, the
default_tax_rateson the invoice do not apply to this line item. Pass an empty string to remove previously-defined tax rates.
Returns
The line_item object.
curl https://api.knoxapi.com/v1/invoices/in_1Pgc6tB7WZ01zgkWu9fdqL6I/lines/line_item_id_123 \
-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 response = await stripe.rawRequest('POST', '/v1/invoices/in_1Pgc6tB7WZ01zgkWu9fdqL6I/lines/line_item_id_123', {
metadata: {
order_id: '6735',
},
});import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
response = client.raw_request("post", "/v1/invoices/in_1Pgc6tB7WZ01zgkWu9fdqL6I/lines/line_item_id_123", metadata={
"order_id": "6735",
})require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
response = Stripe.raw_request(:post, '/v1/invoices/in_1Pgc6tB7WZ01zgkWu9fdqL6I/lines/line_item_id_123', {
metadata: {
order_id: '6735',
},
}){
"amount": 1000,
"currency": "usd",
"description": "My First Invoice Item (created for API docs)",
"discount_amounts": [],
"discountable": true,
"discounts": [],
"id": "il_tmp_1Pgc6sB7WZ01zgkWrG16hkdl",
"invoice": "in_1Pgc6tB7WZ01zgkWu9fdqL6I",
"livemode": false,
"metadata": {},
"object": "line_item",
"period": {
"end": 1721954054,
"start": 1721954054
},
"quantity": 1,
"subscription": null,
"pretax_credit_amounts": null,
"taxes": null,
"parent": {
"invoice_item_details": {
"invoice_item": "invoice_item",
"proration": true,
"proration_details": {
"credited_items": {
"invoice": "invoice",
"invoice_line_items": [
"invoice_line_items"
]
}
},
"subscription": null
},
"subscription_item_details": {
"invoice_item": null,
"proration": true,
"proration_details": {
"credited_items": {
"invoice": "invoice",
"invoice_line_items": [
"invoice_line_items"
]
}
},
"subscription": "subscription",
"subscription_item": "subscription_item"
},
"type": "invoice_item_details"
},
"pricing": {
"type": "price_details",
"unit_amount_decimal": null
},
"subtotal": 2060319484,
"quantity_decimal": null
}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.