API reference

Invoiceitems

Invoice Items represent the component lines of an invoice. When you create an invoice item with an invoice field, it is attached to the specified invoice and included as an invoice line item within invoice.lines. Invoice Items can be created before you are ready to actually send the invoice. This can be particularly useful when combined with a subscription. Sometimes you want to add a charge or credit to a customer, but actually charge or credit the customer's card only at the end of a regular billing cycle. This is useful for combining several charges (to minimize per-transaction fees), or for having Stripe tabulate your usage-based billing totals. Related guides: Integrate with the Invoicing API, Subscription Invoices.

Knox answers these operations with the same requests and responses as Stripe's API. Authenticate with your secret key, Authorization: Bearer sk_test_..., from your server, and send form-encoded bodies. Test mode only: live processing is currently disabled.

Create an invoice item

POST/v1/invoiceitems

Creates an item to be added to a draft invoice (up to 250 items per invoice). If no invoice is specified, the item will be on the next invoice created for the customer specified.

Body parameters

  • amountinteger

    The integer amount in cents (or local equivalent) of the charge to be applied to the upcoming invoice. Passing in a negative amount will reduce the amount_due on the invoice.

  • currencystring

    Three-letter ISO currency code, in lowercase. Must be a supported currency.

  • customerstring

    The ID of the customer to bill for this invoice item.

  • customer_accountstring

    The ID of the account representing the customer to bill for this invoice item.

  • descriptionstring

    An arbitrary string which you can attach to the invoice item. The description is displayed in the invoice for easy tracking.

  • discountableboolean

    Controls whether discounts apply to this invoice item. Defaults to false for prorations or negative invoice items, and true for all other invoice items.

  • discountsarray of objects

    The coupons and promotion codes to redeem into discounts for the invoice item or invoice line item.

    Show 3 child parameters
    • couponstring
    • discountstring
    • promotion_codestring
  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • invoicestring

    The ID of an existing invoice to add this invoice item to. For subscription invoices, when left blank, the invoice item will be added to the next upcoming scheduled invoice. For standalone invoices, the invoice item won't be automatically added unless you pass pending_invoice_item_behavior: 'include' when creating the invoice. This is useful when adding invoice items in response to an invoice.created webhook. You can only add invoice items to draft invoices and there is a maximum of 250 items per invoice.

  • metadataobject

    Set 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.

  • periodobject

    The 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
    • endintegerRequired
    • startintegerRequired
  • price_dataobject

    Data used to generate a new Price object inline.

    Show 5 child parameters
    • currencystringRequired
    • productstringRequired
    • tax_behaviorstring
      Possible values
      • exclusive
      • inclusive
      • unspecified
    • unit_amountinteger
    • unit_amount_decimalstring
  • pricingobject

    The pricing information for the invoice item.

    Show 1 child parameter
    • pricestring
  • quantityinteger

    Non-negative integer. The quantity of units for the invoice item. Use quantity_decimal instead to provide decimal precision. This field will be deprecated in favor of quantity_decimal in a future version.

  • quantity_decimalstring

    Non-negative decimal with at most 12 decimal places. The quantity of units for the invoice item.

  • subscriptionstring

    The ID of a subscription to add this invoice item to. When left blank, the invoice item is added to the next upcoming scheduled invoice. When set, scheduled invoices for subscriptions other than the specified subscription will ignore the invoice item. Use this when you want to express that an invoice item has been accrued within the context of a particular subscription.

  • tax_behaviorstring

    Only required if a default tax behavior) was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of inclusive, exclusive, or unspecified. Once specified as either inclusive or exclusive, it cannot be changed.

    Possible values
    • exclusive
    • inclusive
    • unspecified
  • tax_codestring

    A tax code ID.

  • tax_ratesarray of strings

    The tax rates which apply to the invoice item. When set, the default_tax_rates on the invoice do not apply to this invoice item.

  • unit_amount_decimalstring

    The decimal unit amount in cents (or local equivalent) of the charge to be applied to the upcoming invoice. This unit_amount_decimal will be multiplied by the quantity to get the full amount. Passing in a negative unit_amount_decimal will reduce the amount_due on the invoice. Accepts at most 12 decimal places.

Returns

The invoiceitem object.

POST /v1/invoiceitems
curl -X POST https://api.knoxapi.com/v1/invoiceitems \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "amount": 1000,
  "currency": "usd",
  "customer": "cus_QXg1o8vcGmoR32",
  "date": 1234567890,
  "description": "My First Invoice Item (created for API docs)",
  "discountable": true,
  "discounts": [],
  "id": "ii_1Pgc6sB7WZ01zgkWrG16hkdl",
  "invoice": null,
  "livemode": false,
  "metadata": {},
  "object": "invoiceitem",
  "period": {
    "end": 1721954054,
    "start": 1721954054
  },
  "proration": false,
  "quantity": 1,
  "tax_rates": [],
  "test_clock": null,
  "parent": {
    "subscription_details": {
      "subscription": "subscription"
    },
    "type": "subscription_details"
  },
  "pricing": {
    "type": "price_details",
    "unit_amount_decimal": null
  },
  "net_amount": 708769478,
  "customer_account": null,
  "quantity_decimal": "174352450"
}

List all invoice items

GET/v1/invoiceitems

Returns a list of your invoice items. Invoice items are returned sorted by creation date, with the most recently created invoice items appearing first.

Query parameters

  • createdobject | integer

    Only return invoice items that were created during the given date interval.

    Show 4 child parameters
    • gtinteger
    • gteinteger
    • ltinteger
    • lteinteger
  • customerstring

    The identifier of the customer whose invoice items to return. If none is provided, returns all invoice items.

  • customer_accountstring

    The identifier of the account representing the customer whose invoice items to return. If none is provided, returns all invoice items.

  • ending_beforestring

    A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • invoicestring

    Only return invoice items belonging to this invoice. If none is provided, all invoice items will be returned. If specifying an invoice, no customer identifier is needed.

  • limitinteger

    A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.

  • pendingboolean

    Set to true to only show pending invoice items, which are not yet attached to any invoices. Set to false to only show invoice items already attached to invoices. If unspecified, no filter is applied.

  • starting_afterstring

    A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.

Returns

A list of invoiceitem objects.

GET /v1/invoiceitems
curl -G https://api.knoxapi.com/v1/invoiceitems \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode limit=3
Response
{
  "object": "list",
  "url": "/v1/invoiceitems",
  "has_more": false,
  "data": [
    {
      "amount": 1000,
      "currency": "usd",
      "customer": "cus_QXg1o8vcGmoR32",
      "date": 1234567890,
      "description": "My First Invoice Item (created for API docs)",
      "discountable": true,
      "discounts": [],
      "id": "ii_1Pgc6sB7WZ01zgkWrG16hkdl",
      "invoice": null,
      "livemode": false,
      "metadata": {},
      "object": "invoiceitem",
      "period": {
        "end": 1721954054,
        "start": 1721954054
      },
      "proration": false,
      "quantity": 1,
      "tax_rates": [],
      "test_clock": null,
      "parent": {
        "subscription_details": {
          "subscription": "subscription"
        },
        "type": "subscription_details"
      },
      "pricing": {
        "type": "price_details",
        "unit_amount_decimal": null
      },
      "net_amount": 708769478,
      "customer_account": null,
      "quantity_decimal": "174352450"
    }
  ]
}

Update an invoice item

POST/v1/invoiceitems/{invoiceitem}

Updates the amount or description of an invoice item on an upcoming invoice. Updating an invoice item is only possible before the invoice it’s attached to is closed.

Path parameters

  • invoiceitemstringRequired

Body parameters

  • amountinteger

    The 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.

  • descriptionstring

    An arbitrary string which you can attach to the invoice item. The description is displayed in the invoice for easy tracking.

  • discountableboolean

    Controls whether discounts apply to this invoice item. Defaults to false for prorations or negative invoice items, and true for all other invoice items. Cannot be set to true for prorations.

  • discountsarray of objects

    The coupons, promotion codes & existing discounts which apply to the invoice item or invoice line item. Item discounts are applied before invoice discounts. Pass an empty string to remove previously-defined discounts.

    Show 3 child parameters
    • couponstring
    • discountstring
    • promotion_codestring
  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • metadataobject

    Set 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.

  • periodobject

    The 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
    • endintegerRequired
    • startintegerRequired
  • price_dataobject

    Data used to generate a new Price object inline.

    Show 5 child parameters
    • currencystringRequired
    • productstringRequired
    • tax_behaviorstring
      Possible values
      • exclusive
      • inclusive
      • unspecified
    • unit_amountinteger
    • unit_amount_decimalstring
  • pricingobject

    The pricing information for the invoice item.

    Show 1 child parameter
    • pricestring
  • quantityinteger

    Non-negative integer. The quantity of units for the invoice item. Use quantity_decimal instead to provide decimal precision. This field will be deprecated in favor of quantity_decimal in a future version.

  • quantity_decimalstring

    Non-negative decimal with at most 12 decimal places. The quantity of units for the line item.

  • tax_behaviorstring

    Only required if a default tax behavior) was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of inclusive, exclusive, or unspecified. Once specified as either inclusive or exclusive, it cannot be changed.

    Possible values
    • exclusive
    • inclusive
    • unspecified
  • tax_codestring

    A tax code ID.

  • tax_ratesarray of strings

    The tax rates which apply to the invoice item. When set, the default_tax_rates on the invoice do not apply to this invoice item. Pass an empty string to remove previously-defined tax rates.

  • unit_amount_decimalstring

    The decimal unit amount in cents (or local equivalent) of the charge to be applied to the upcoming invoice. This unit_amount_decimal will be multiplied by the quantity to get the full amount. Passing in a negative unit_amount_decimal will reduce the amount_due on the invoice. Accepts at most 12 decimal places.

Returns

The invoiceitem object.

POST /v1/invoiceitems/{invoiceitem}
curl https://api.knoxapi.com/v1/invoiceitems/ii_1Pgc6sB7WZ01zgkWrG16hkdl \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d "metadata[order_id]=6735"
Response
{
  "amount": 1000,
  "currency": "usd",
  "customer": "cus_QXg1o8vcGmoR32",
  "date": 1234567890,
  "description": "My First Invoice Item (created for API docs)",
  "discountable": true,
  "discounts": [],
  "id": "ii_1Pgc6sB7WZ01zgkWrG16hkdl",
  "invoice": null,
  "livemode": false,
  "metadata": {},
  "object": "invoiceitem",
  "period": {
    "end": 1721954054,
    "start": 1721954054
  },
  "proration": false,
  "quantity": 1,
  "tax_rates": [],
  "test_clock": null,
  "parent": {
    "subscription_details": {
      "subscription": "subscription"
    },
    "type": "subscription_details"
  },
  "pricing": {
    "type": "price_details",
    "unit_amount_decimal": null
  },
  "net_amount": 708769478,
  "customer_account": null,
  "quantity_decimal": "174352450"
}

Retrieve an invoice item

GET/v1/invoiceitems/{invoiceitem}

Retrieves the invoice item with the given ID.

Path parameters

  • invoiceitemstringRequired

Query parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The invoiceitem object.

GET /v1/invoiceitems/{invoiceitem}
curl https://api.knoxapi.com/v1/invoiceitems/ii_1Pgc6sB7WZ01zgkWrG16hkdl \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "amount": 1000,
  "currency": "usd",
  "customer": "cus_QXg1o8vcGmoR32",
  "date": 1234567890,
  "description": "My First Invoice Item (created for API docs)",
  "discountable": true,
  "discounts": [],
  "id": "ii_1Pgc6sB7WZ01zgkWrG16hkdl",
  "invoice": null,
  "livemode": false,
  "metadata": {},
  "object": "invoiceitem",
  "period": {
    "end": 1721954054,
    "start": 1721954054
  },
  "proration": false,
  "quantity": 1,
  "tax_rates": [],
  "test_clock": null,
  "parent": {
    "subscription_details": {
      "subscription": "subscription"
    },
    "type": "subscription_details"
  },
  "pricing": {
    "type": "price_details",
    "unit_amount_decimal": null
  },
  "net_amount": 708769478,
  "customer_account": null,
  "quantity_decimal": "174352450"
}

Delete an invoice item

DELETE/v1/invoiceitems/{invoiceitem}

Deletes an invoice item, removing it from an invoice. Deleting invoice items is only possible when they’re not attached to invoices, or if it’s attached to a draft invoice.

Path parameters

  • invoiceitemstringRequired

Returns

The deleted_invoiceitem object.

DELETE /v1/invoiceitems/{invoiceitem}
curl -X DELETE https://api.knoxapi.com/v1/invoiceitems/ii_1Pgc6sB7WZ01zgkWrG16hkdl \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "deleted": true,
  "id": "ii_1Pgc6sB7WZ01zgkWrG16hkdl",
  "object": "invoiceitem"
}

Operations and schemas come from the pinned Stripe OpenAPI specification (MIT); response examples from its fixtures. Nested object definitions and enums are in the complete specification.