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

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

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 strings

    The account tax IDs associated with the invoice. Only editable when the invoice is a draft.

  • application_fee_amountinteger

    A 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_advanceboolean

    Controls 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_taxobject

    Settings for automatic tax lookup for this invoice.

    Show 2 child parameters
    • enabledbooleanRequired
    • liabilityobject
      Show 2 child parameters
      • typestringRequired
        Possible values
        • account
        • self
      • accountstring
  • automatically_finalizes_atinteger

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

    Either charge_automatically, or send_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 to charge_automatically.

    Possible values
    • charge_automatically
    • send_invoice
  • currencystring

    The currency to create this invoice in. Defaults to that of customer if not specified.

  • custom_fieldsarray of objects

    A list of up to 4 custom fields to be displayed on the invoice.

    Show 2 child parameters
    • namestringRequired
    • valuestringRequired
  • customerstring

    The ID of the customer to bill.

  • customer_accountstring

    The ID of the account to bill.

  • days_until_dueinteger

    The number of days from when the invoice is created until it is due. Valid only for invoices where collection_method=send_invoice.

  • default_payment_methodstring

    ID 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_sourcestring

    ID 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 strings

    The tax rates that will apply to any line item that does not have tax_rates set.

  • descriptionstring

    An arbitrary string attached to the object. Often useful for displaying to users. Referenced as 'memo' in the Dashboard.

  • discountsarray of objects

    The 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
    • couponstring
    • discountstring
    • promotion_codestring
  • due_dateinteger

    The date on which payment for this invoice is due. Valid only for invoices where collection_method=send_invoice.

  • effective_atinteger

    The date when this invoice is in effect. Same as finalized_at unless overwritten. When defined, this value replaces the system-generated 'Date of issue' printed on the invoice PDF and receipt.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • footerstring

    Footer to be displayed on the invoice.

  • from_invoiceobject

    Revise an existing invoice. The new invoice will be created in status=draft. See the revision documentation for more details.

    Show 2 child parameters
    • actionstringRequired
      Possible values
      • revision
    • invoicestringRequired
  • issuerobject

    The connected account that issues the invoice. The invoice is presented with the branding and support information of the specified account.

    Show 2 child parameters
    • typestringRequired
      Possible values
      • account
      • self
    • accountstring
  • 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.

  • numberstring

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

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

    Configuration settings for the PaymentIntent that is generated when the invoice is finalized.

    Show 3 child parameters
    • default_mandatestring
    • payment_method_optionsobject
      Show 11 child parameters
    • payment_method_typesarray of strings
  • pending_invoice_items_behaviorstring

    How to handle pending invoice items on invoice creation. Defaults to exclude if the parameter is omitted.

    Possible values
    • exclude
    • include
  • renderingobject

    The 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_displaystring
      Possible values
      • exclude_tax
      • include_inclusive_tax
    • pdfobject
      Show 1 child parameter
      • page_sizestring
        Possible values
        • a4
        • auto
        • letter
    • templatestring
    • template_versioninteger
  • shipping_costobject

    Settings for the cost of shipping for this invoice.

    Show 2 child parameters
    • shipping_ratestring
    • shipping_rate_dataobject
      Show 7 child parameters
      • display_namestringRequired
      • delivery_estimateobject

        Child parameters are listed in the OpenAPI document.

      • fixed_amountobject

        Child parameters are listed in the OpenAPI document.

      • metadataobject
      • tax_behaviorstring
        Possible values
        • exclusive
        • inclusive
        • unspecified
      • tax_codestring
      • typestring
        Possible values
        • fixed_amount
  • shipping_detailsobject

    Shipping details for the invoice. The Invoice PDF will use the shipping_details value if it is set, otherwise the PDF will render the shipping address from the customer.

    Show 3 child parameters
    • addressobjectRequired
      Show 6 child parameters
      • citystring
      • countrystring
      • line1string
      • line2string
      • postal_codestring
      • statestring
    • namestringRequired
    • phonestring
  • statement_descriptorstring

    Extra 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_descriptor will be set to the first subscription item's product's statement_descriptor.

  • subscriptionstring

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

    If 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
    • destinationstringRequired
    • amountinteger

Returns

The invoice object.

POST /v1/invoices
curl -X POST https://api.knoxapi.com/v1/invoices \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "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_methodstring

    The collection method of the invoice to retrieve. Either charge_automatically or send_invoice.

    Possible values
    • charge_automatically
    • send_invoice
  • createdobject | integer

    Only return invoices that were created during the given date interval.

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

    Only return invoices for the customer specified by this customer ID.

  • customer_accountstring

    Only return invoices for the account representing the customer specified by this account ID.

  • due_dateobject | integer
    Show 4 child parameters
    • gtinteger
    • gteinteger
    • ltinteger
    • lteinteger
  • 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.

  • limitinteger

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

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

  • statusstring

    The status of the invoice, one of draft, open, paid, uncollectible, or void. Learn more

    Possible values
    • draft
    • open
    • paid
    • uncollectible
    • void
  • subscriptionstring

    Only return invoices for the subscription specified by this subscription ID.

Returns

A list of invoice objects.

GET /v1/invoices
curl -G https://api.knoxapi.com/v1/invoices \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode limit=3
Response
{
  "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_taxobject

    Settings for automatic tax lookup for this invoice preview.

    Show 2 child parameters
    • enabledbooleanRequired
    • liabilityobject
      Show 2 child parameters
      • typestringRequired
        Possible values
        • account
        • self
      • accountstring
  • currencystring

    The currency to preview this invoice in. Defaults to that of customer if not specified.

  • customerstring

    The identifier of the customer whose upcoming invoice you're retrieving. If automatic_tax is enabled then one of customer, customer_details, subscription, or schedule must be set.

  • customer_accountstring

    The identifier of the account representing the customer whose upcoming invoice you're retrieving. If automatic_tax is enabled then one of customer, customer_account, customer_details, subscription, or schedule must be set.

  • customer_detailsobject

    Details about the customer you want to invoice or overrides for an existing customer. If automatic_tax is enabled then one of customer, customer_details, subscription, or schedule must be set.

    Show 5 child parameters
    • addressobject
      Show 6 child parameters
      • citystring
      • countrystring
      • line1string
      • line2string
      • postal_codestring
      • statestring
    • shippingobject
      Show 3 child parameters
      • addressobjectRequired

        Child parameters are listed in the OpenAPI document.

      • namestringRequired
      • phonestring
    • taxobject
      Show 1 child parameter
      • ip_addressstring
    • tax_exemptstring
      Possible values
      • exempt
      • none
      • reverse
    • tax_idsarray of objects
      Show 2 child parameters
      • typestringRequired
        Possible values
        • ad_nrt
        • ae_trn
        • al_tin
        • am_tin
        • ao_tin
        • ar_cuit
        • au_abn
        • au_arn
        • aw_tin
        • az_tin
        • ba_tin
        • bb_tin
        • bd_bin
        • bf_ifu
        • bg_uic
        • bh_vat
        • and 101 more
      • valuestringRequired
  • discountsarray of objects

    The 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
    • couponstring
    • discountstring
    • promotion_codestring
  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • invoice_itemsarray of objects

    List of invoice items to add or update in the upcoming invoice preview (up to 250).

    Show 17 child parameters
    • amountinteger
    • currencystring
    • descriptionstring
    • discountableboolean
    • discountsarray of objects
      Show 3 child parameters
      • couponstring
      • discountstring
      • promotion_codestring
    • invoiceitemstring
    • metadataobject
    • periodobject
      Show 2 child parameters
      • endintegerRequired
      • startintegerRequired
    • pricestring
    • price_dataobject
      Show 5 child parameters
      • currencystringRequired
      • productstringRequired
      • tax_behaviorstring
        Possible values
        • exclusive
        • inclusive
        • unspecified
      • unit_amountinteger
      • unit_amount_decimalstring
    • quantityinteger
    • quantity_decimalstring
    • tax_behaviorstring
      Possible values
      • exclusive
      • inclusive
      • unspecified
    • tax_codestring
    • tax_ratesarray of strings
    • unit_amountinteger
    • unit_amount_decimalstring
  • issuerobject

    The connected account that issues the invoice. The invoice is presented with the branding and support information of the specified account.

    Show 2 child parameters
    • typestringRequired
      Possible values
      • account
      • self
    • accountstring
  • on_behalf_ofstring

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

    Customizes the types of values to include when calculating the invoice. Defaults to next if unspecified.

    Possible values
    • next
    • recurring
  • schedulestring

    The identifier of the schedule whose upcoming invoice you'd like to retrieve. Cannot be used with subscription or subscription fields.

  • schedule_detailsobject

    The schedule creation or modification params to apply as a preview. Cannot be used with subscription or subscription_ prefixed fields.

    Show 4 child parameters
    • billing_modeobject
      Show 2 child parameters
      • typestringRequired
        Possible values
        • classic
        • flexible
      • flexibleobject

        Child parameters are listed in the OpenAPI document.

    • end_behaviorstring
      Possible values
      • cancel
      • release
    • phasesarray of objects
      Show 21 child parameters
      • itemsarray of objectsRequired

        Child parameters are listed in the OpenAPI document.

      • add_invoice_itemsarray of objects

        Child parameters are listed in the OpenAPI document.

      • application_fee_percentnumber
      • automatic_taxobject

        Child parameters are listed in the OpenAPI document.

      • billing_cycle_anchorstring
        Possible values
        • automatic
        • phase_start
      • billing_thresholdsobject

        Child parameters are listed in the OpenAPI document.

      • collection_methodstring
        Possible values
        • charge_automatically
        • send_invoice
      • default_payment_methodstring
      • default_tax_ratesarray of strings
      • descriptionstring
      • discountsarray of objects

        Child parameters are listed in the OpenAPI document.

      • durationobject

        Child parameters are listed in the OpenAPI document.

      • end_dateinteger | string
        Possible values
        • now
      • invoice_settingsobject

        Child parameters are listed in the OpenAPI document.

      • metadataobject
      • on_behalf_ofstring
      • proration_behaviorstring
        Possible values
        • always_invoice
        • create_prorations
        • none
      • start_dateinteger | string
        Possible values
        • now
      • transfer_dataobject

        Child parameters are listed in the OpenAPI document.

      • trialboolean
      • trial_endinteger | string
        Possible values
        • now
    • proration_behaviorstring
      Possible values
      • always_invoice
      • create_prorations
      • none
  • subscriptionstring

    The identifier of the subscription for which you'd like to retrieve the upcoming invoice. If not provided, but a subscription_details.items is provided, you will preview creating a subscription with those items. If neither subscription nor subscription_details.items is provided, you will retrieve the next upcoming invoice from among the customer's subscriptions.

  • subscription_detailsobject

    The subscription creation or modification params to apply as a preview. Cannot be used with schedule or schedule_details fields.

    Show 14 child parameters
    • billing_cycle_anchorstring | integer
      Possible values
      • now
      • unchanged
    • billing_modeobject
      Show 2 child parameters
      • typestringRequired
        Possible values
        • classic
        • flexible
      • flexibleobject

        Child parameters are listed in the OpenAPI document.

    • billing_schedulesarray of objects
      Show 3 child parameters
    • cancel_atinteger | string
      Possible values
      • max_billed_until
      • max_period_end
      • min_period_end
    • cancel_at_period_endboolean
    • cancel_nowboolean
    • default_tax_ratesarray of strings
    • itemsarray of objects
      Show 10 child parameters
      • billing_thresholdsobject

        Child parameters are listed in the OpenAPI document.

      • clear_usageboolean
      • deletedboolean
      • discountsarray of objects

        Child parameters are listed in the OpenAPI document.

      • idstring
      • metadataobject
      • pricestring
      • price_dataobject

        Child parameters are listed in the OpenAPI document.

      • quantityinteger
      • tax_ratesarray of strings
    • metadataobject
    • proration_behaviorstring
      Possible values
      • always_invoice
      • create_prorations
      • none
    • proration_dateinteger
    • resume_atstring
      Possible values
      • now
    • start_dateinteger
    • trial_endstring | integer
      Possible values
      • now

Returns

The invoice object.

POST /v1/invoices/create_preview
curl -X POST https://api.knoxapi.com/v1/invoices/create_preview \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "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

  • querystringRequired

    The search query string. See search query language and the list of supported query fields for invoices.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • limitinteger

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

  • pagestring

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

GET /v1/invoices/search
curl -G https://api.knoxapi.com/v1/invoices/search \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode "query=metadata['order_id']:'6735'"
Response
{
  "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 strings

    The account tax IDs associated with the invoice. Only editable when the invoice is a draft.

  • application_fee_amountinteger

    A 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_advanceboolean

    Controls whether Stripe performs automatic collection of the invoice.

  • automatic_taxobject

    Settings for automatic tax lookup for this invoice.

    Show 2 child parameters
    • enabledbooleanRequired
    • liabilityobject
      Show 2 child parameters
      • typestringRequired
        Possible values
        • account
        • self
      • accountstring
  • automatically_finalizes_atinteger

    The 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_advance to false.

  • collection_methodstring

    Either charge_automatically or send_invoice. This field can be updated only on draft invoices.

    Possible values
    • charge_automatically
    • send_invoice
  • custom_fieldsarray of objects

    A list of up to 4 custom fields to be displayed on the invoice. If a value for custom_fields is 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
    • namestringRequired
    • valuestringRequired
  • days_until_dueinteger

    The 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 on draft invoices.

  • default_payment_methodstring

    ID 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_sourcestring

    ID 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 strings

    The tax rates that will apply to any line item that does not have tax_rates set. Pass an empty string to remove previously-defined tax rates.

  • descriptionstring

    An arbitrary string attached to the object. Often useful for displaying to users. Referenced as 'memo' in the Dashboard.

  • discountsarray of objects

    The discounts that will apply to the invoice. Pass an empty string to remove previously-defined discounts.

    Show 3 child parameters
    • couponstring
    • discountstring
    • promotion_codestring
  • due_dateinteger

    The date on which payment for this invoice is due. Only valid for invoices where collection_method=send_invoice. This field can only be updated on draft invoices.

  • effective_atinteger

    The date when this invoice is in effect. Same as finalized_at unless overwritten. When defined, this value replaces the system-generated 'Date of issue' printed on the invoice PDF and receipt.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • footerstring

    Footer to be displayed on the invoice.

  • issuerobject

    The connected account that issues the invoice. The invoice is presented with the branding and support information of the specified account.

    Show 2 child parameters
    • typestringRequired
      Possible values
      • account
      • self
    • accountstring
  • 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.

  • numberstring

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

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

    Configuration settings for the PaymentIntent that is generated when the invoice is finalized.

    Show 3 child parameters
    • default_mandatestring
    • payment_method_optionsobject
      Show 11 child parameters
    • payment_method_typesarray of strings
  • renderingobject

    The 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_displaystring
      Possible values
      • exclude_tax
      • include_inclusive_tax
    • pdfobject
      Show 1 child parameter
      • page_sizestring
        Possible values
        • a4
        • auto
        • letter
    • templatestring
    • template_versioninteger
  • shipping_costobject

    Settings for the cost of shipping for this invoice.

    Show 2 child parameters
    • shipping_ratestring
    • shipping_rate_dataobject
      Show 7 child parameters
      • display_namestringRequired
      • delivery_estimateobject

        Child parameters are listed in the OpenAPI document.

      • fixed_amountobject

        Child parameters are listed in the OpenAPI document.

      • metadataobject
      • tax_behaviorstring
        Possible values
        • exclusive
        • inclusive
        • unspecified
      • tax_codestring
      • typestring
        Possible values
        • fixed_amount
  • shipping_detailsobject

    Shipping details for the invoice. The Invoice PDF will use the shipping_details value if it is set, otherwise the PDF will render the shipping address from the customer.

    Show 3 child parameters
    • addressobjectRequired
      Show 6 child parameters
      • citystring
      • countrystring
      • line1string
      • line2string
      • postal_codestring
      • statestring
    • namestringRequired
    • phonestring
  • statement_descriptorstring

    Extra 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_descriptor will be set to the first subscription item's product's statement_descriptor.

  • transfer_dataobject

    If 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
    • destinationstringRequired
    • amountinteger

Returns

The invoice object.

POST /v1/invoices/{invoice}
curl https://api.knoxapi.com/v1/invoices/in_1Pgc6tB7WZ01zgkWu9fdqL6I \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d "metadata[order_id]=6735"
Response
{
  "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 strings

    Specifies which fields in the response should be expanded.

Returns

The invoice object.

GET /v1/invoices/{invoice}
curl https://api.knoxapi.com/v1/invoices/in_1Pgc6tB7WZ01zgkWu9fdqL6I \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "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.

DELETE /v1/invoices/{invoice}
curl -X DELETE https://api.knoxapi.com/v1/invoices/in_1Pgc6tB7WZ01zgkWu9fdqL6I \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "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 objectsRequired

    The line items to add.

    Show 13 child parameters
    • amountinteger
    • descriptionstring
    • discountableboolean
    • discountsarray of objects
      Show 3 child parameters
      • couponstring
      • discountstring
      • promotion_codestring
    • invoice_itemstring
    • metadataobject
    • periodobject
      Show 2 child parameters
      • endintegerRequired
      • startintegerRequired
    • price_dataobject
      Show 6 child parameters
      • currencystringRequired
      • productstring
      • product_dataobject

        Child parameters are listed in the OpenAPI document.

      • tax_behaviorstring
        Possible values
        • exclusive
        • inclusive
        • unspecified
      • unit_amountinteger
      • unit_amount_decimalstring
    • pricingobject
      Show 1 child parameter
      • pricestring
    • quantityinteger
    • quantity_decimalstring
    • tax_amountsarray of objects
      Show 4 child parameters
      • amountintegerRequired
      • tax_rate_dataobjectRequired

        Child parameters are listed in the OpenAPI document.

      • taxable_amountintegerRequired
      • taxability_reasonstring
        Possible values
        • customer_exempt
        • not_collecting
        • not_subject_to_tax
        • not_supported
        • portion_product_exempt
        • portion_reduced_rated
        • portion_standard_rated
        • product_exempt
        • product_exempt_holiday
        • proportionally_rated
        • reduced_rated
        • reverse_charge
        • standard_rated
        • taxable_basis_reduced
        • zero_rated
    • tax_ratesarray of strings
  • expandarray of strings

    Specifies which fields in the response should be expanded.

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

Returns

The invoice object.

POST /v1/invoices/{invoice}/add_lines
curl https://api.knoxapi.com/v1/invoices/in_1Pgc6tB7WZ01zgkWu9fdqL6I/add_lines \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d "lines[0]="
Response
{
  "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 strings

    Specifies which fields in the response should be expanded.

  • payment_intentstring

    The ID of the PaymentIntent to attach to the invoice.

  • payment_recordstring

    The ID of the PaymentRecord to attach to the invoice.

Returns

The invoice object.

POST /v1/invoices/{invoice}/attach_payment
curl -X POST https://api.knoxapi.com/v1/invoices/in_1Pgc6tB7WZ01zgkWu9fdqL6I/attach_payment \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "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_advanceboolean

    Controls whether Stripe performs automatic collection of the invoice. If false, the invoice's state doesn't automatically advance without an explicit action.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The invoice object.

POST /v1/invoices/{invoice}/finalize
curl -X POST https://api.knoxapi.com/v1/invoices/in_1Pgc6tB7WZ01zgkWu9fdqL6I/finalize \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "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_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.

  • limitinteger

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

  • 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 line_item objects.

GET /v1/invoices/{invoice}/lines
curl -G https://api.knoxapi.com/v1/invoices/in_1Pgc6tB7WZ01zgkWu9fdqL6I/lines \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode limit=3
Response
{
  "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 strings

    Specifies which fields in the response should be expanded.

Returns

The invoice object.

POST /v1/invoices/{invoice}/mark_uncollectible
curl -X POST https://api.knoxapi.com/v1/invoices/in_1Pgc6tB7WZ01zgkWu9fdqL6I/mark_uncollectible \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "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 strings

    Specifies which fields in the response should be expanded.

  • forgiveboolean

    In cases where the source used to pay the invoice has insufficient funds, passing forgive=true controls 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. Passing forgive=false will 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 to false.

  • mandatestring

    ID 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_sessionboolean

    Indicates if a customer is on or off-session while an invoice payment is attempted. Defaults to true (off-session).

  • paid_out_of_bandboolean

    Boolean representing whether an invoice is paid outside of Stripe. This will result in no charge being made. Defaults to false.

  • payment_methodstring

    A PaymentMethod to be charged. The PaymentMethod must be the ID of a PaymentMethod belonging to the customer associated with the invoice being paid.

  • sourcestring

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

POST /v1/invoices/{invoice}/pay
curl -X POST https://api.knoxapi.com/v1/invoices/in_1Pgc6tB7WZ01zgkWu9fdqL6I/pay \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "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 objectsRequired

    The line items to remove.

    Show 2 child parameters
    • behaviorstringRequired
      Possible values
      • delete
      • unassign
    • idstringRequired
  • expandarray of strings

    Specifies which fields in the response should be expanded.

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

Returns

The invoice object.

POST /v1/invoices/{invoice}/remove_lines
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"
Response
{
  "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 strings

    Specifies which fields in the response should be expanded.

Returns

The invoice object.

POST /v1/invoices/{invoice}/send
curl -X POST https://api.knoxapi.com/v1/invoices/in_1Pgc6tB7WZ01zgkWu9fdqL6I/send \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "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 objectsRequired

    The line items to update.

    Show 13 child parameters
    • idstringRequired
    • amountinteger
    • descriptionstring
    • discountableboolean
    • discountsarray of objects
      Show 3 child parameters
      • couponstring
      • discountstring
      • promotion_codestring
    • metadataobject
    • periodobject
      Show 2 child parameters
      • endintegerRequired
      • startintegerRequired
    • price_dataobject
      Show 6 child parameters
      • currencystringRequired
      • productstring
      • product_dataobject

        Child parameters are listed in the OpenAPI document.

      • tax_behaviorstring
        Possible values
        • exclusive
        • inclusive
        • unspecified
      • unit_amountinteger
      • unit_amount_decimalstring
    • pricingobject
      Show 1 child parameter
      • pricestring
    • quantityinteger
    • quantity_decimalstring
    • tax_amountsarray of objects
      Show 4 child parameters
      • amountintegerRequired
      • tax_rate_dataobjectRequired

        Child parameters are listed in the OpenAPI document.

      • taxable_amountintegerRequired
      • taxability_reasonstring
        Possible values
        • customer_exempt
        • not_collecting
        • not_subject_to_tax
        • not_supported
        • portion_product_exempt
        • portion_reduced_rated
        • portion_standard_rated
        • product_exempt
        • product_exempt_holiday
        • proportionally_rated
        • reduced_rated
        • reverse_charge
        • standard_rated
        • taxable_basis_reduced
        • zero_rated
    • tax_ratesarray of strings
  • expandarray of strings

    Specifies which fields in the response should be expanded.

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

POST /v1/invoices/{invoice}/update_lines
curl https://api.knoxapi.com/v1/invoices/in_1Pgc6tB7WZ01zgkWu9fdqL6I/update_lines \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d "lines[0][id]=example"
Response
{
  "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 strings

    Specifies which fields in the response should be expanded.

Returns

The invoice object.

POST /v1/invoices/{invoice}/void
curl -X POST https://api.knoxapi.com/v1/invoices/in_1Pgc6tB7WZ01zgkWu9fdqL6I/void \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "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

  • invoicestringRequired

    Invoice ID of line item

  • line_item_idstringRequired

    Invoice line item ID

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 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 objects

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

  • 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 6 child parameters
    • currencystringRequired
    • productstring
    • product_dataobject
      Show 6 child parameters
      • namestringRequired
      • descriptionstring
      • imagesarray of strings
      • metadataobject
      • tax_codestring
      • unit_labelstring
    • 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 line 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_amountsarray of objects

    A 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
    • amountintegerRequired
    • tax_rate_dataobjectRequired
      Show 9 child parameters
      • display_namestringRequired
      • inclusivebooleanRequired
      • percentagenumberRequired
      • countrystring
      • descriptionstring
      • jurisdictionstring
      • jurisdiction_levelstring
        Possible values
        • city
        • country
        • county
        • district
        • multiple
        • state
      • statestring
      • tax_typestring
        Possible values
        • amusement_tax
        • communications_tax
        • gst
        • hst
        • igst
        • jct
        • lease_tax
        • mass_transit_parking_tax
        • parking_tax
        • pst
        • qst
        • retail_delivery_fee
        • rst
        • sales_tax
        • service_tax
        • vat
    • taxable_amountintegerRequired
    • taxability_reasonstring
      Possible values
      • customer_exempt
      • not_collecting
      • not_subject_to_tax
      • not_supported
      • portion_product_exempt
      • portion_reduced_rated
      • portion_standard_rated
      • product_exempt
      • product_exempt_holiday
      • proportionally_rated
      • reduced_rated
      • reverse_charge
      • standard_rated
      • taxable_basis_reduced
      • zero_rated
  • tax_ratesarray of strings

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

Returns

The line_item object.

POST /v1/invoices/{invoice}/lines/{line_item_id}
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"
Response
{
  "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.