API reference

Tax Rates

Tax rates can be applied to invoices, subscriptions and Checkout Sessions to collect tax. Related guide: Tax rates

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 a tax rate

POST/v1/tax_rates

Creates a new tax rate.

Body parameters

  • display_namestringRequired

    The display name of the tax rate, which will be shown to users.

  • inclusivebooleanRequired

    This specifies if the tax rate is inclusive or exclusive.

  • percentagenumberRequired

    This represents the tax rate percent out of 100.

  • activeboolean

    Flag determining whether the tax rate is active or inactive (archived). Inactive tax rates cannot be used with new applications or Checkout Sessions, but will still work for subscriptions and invoices that already have it set.

  • countrystring

    Two-letter country code (ISO 3166-1 alpha-2).

  • descriptionstring

    An arbitrary string attached to the tax rate for your internal use only. It will not be visible to your customers.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • jurisdictionstring

    The jurisdiction for the tax rate. You can use this label field for tax reporting purposes. It also appears on your customer’s 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.

  • statestring

    ISO 3166-2 subdivision code, without country prefix. For example, "NY" for New York, United States.

  • tax_typestring

    The high-level tax type, such as vat or sales_tax.

    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

Returns

The tax_rate object.

POST /v1/tax_rates
curl https://api.knoxapi.com/v1/tax_rates \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d display_name=VAT \
  -d inclusive=false \
  -d percentage=19
Response
{
  "active": true,
  "country": "DE",
  "created": 1234567890,
  "description": "VAT Germany",
  "display_name": "VAT",
  "effective_percentage": null,
  "id": "txr_1Pgc7BB7WZ01zgkW4Iwwvf6z",
  "inclusive": false,
  "jurisdiction": "DE",
  "jurisdiction_level": null,
  "livemode": false,
  "metadata": {},
  "object": "tax_rate",
  "percentage": 19,
  "state": null,
  "tax_type": "vat",
  "flat_amount": {
    "amount": 1413853096,
    "currency": "currency"
  },
  "rate_type": null
}

List all tax rates

GET/v1/tax_rates

Returns a list of your tax rates. Tax rates are returned sorted by creation date, with the most recently created tax rates appearing first.

Query parameters

  • activeboolean

    Optional flag to filter by tax rates that are either active or inactive (archived).

  • createdobject | integer

    Optional range for filtering created date.

    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.

  • inclusiveboolean

    Optional flag to filter by tax rates that are inclusive (or those that are not inclusive).

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

GET /v1/tax_rates
curl -G https://api.knoxapi.com/v1/tax_rates \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode limit=3
Response
{
  "object": "list",
  "url": "/v1/tax_rates",
  "has_more": false,
  "data": [
    {
      "active": true,
      "country": "DE",
      "created": 1234567890,
      "description": "VAT Germany",
      "display_name": "VAT",
      "effective_percentage": null,
      "id": "txr_1Pgc7BB7WZ01zgkW4Iwwvf6z",
      "inclusive": false,
      "jurisdiction": "DE",
      "jurisdiction_level": null,
      "livemode": false,
      "metadata": {},
      "object": "tax_rate",
      "percentage": 19,
      "state": null,
      "tax_type": "vat",
      "flat_amount": {
        "amount": 1413853096,
        "currency": "currency"
      },
      "rate_type": null
    }
  ]
}

Update a tax rate

POST/v1/tax_rates/{tax_rate}

Updates an existing tax rate.

Path parameters

  • tax_ratestringRequired

Body parameters

  • activeboolean

    Flag determining whether the tax rate is active or inactive (archived). Inactive tax rates cannot be used with new applications or Checkout Sessions, but will still work for subscriptions and invoices that already have it set.

  • countrystring

    Two-letter country code (ISO 3166-1 alpha-2).

  • descriptionstring

    An arbitrary string attached to the tax rate for your internal use only. It will not be visible to your customers.

  • display_namestring

    The display name of the tax rate, which will be shown to users.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • jurisdictionstring

    The jurisdiction for the tax rate. You can use this label field for tax reporting purposes. It also appears on your customer’s 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.

  • statestring

    ISO 3166-2 subdivision code, without country prefix. For example, "NY" for New York, United States.

  • tax_typestring

    The high-level tax type, such as vat or sales_tax.

    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

Returns

The tax_rate object.

POST /v1/tax_rates/{tax_rate}
curl https://api.knoxapi.com/v1/tax_rates/txr_1Pgc7BB7WZ01zgkW4Iwwvf6z \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d "metadata[order_id]=6735"
Response
{
  "active": true,
  "country": "DE",
  "created": 1234567890,
  "description": "VAT Germany",
  "display_name": "VAT",
  "effective_percentage": null,
  "id": "txr_1Pgc7BB7WZ01zgkW4Iwwvf6z",
  "inclusive": false,
  "jurisdiction": "DE",
  "jurisdiction_level": null,
  "livemode": false,
  "metadata": {},
  "object": "tax_rate",
  "percentage": 19,
  "state": null,
  "tax_type": "vat",
  "flat_amount": {
    "amount": 1413853096,
    "currency": "currency"
  },
  "rate_type": null
}

Retrieve a tax rate

GET/v1/tax_rates/{tax_rate}

Retrieves a tax rate with the given ID

Path parameters

  • tax_ratestringRequired

Query parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The tax_rate object.

GET /v1/tax_rates/{tax_rate}
curl https://api.knoxapi.com/v1/tax_rates/txr_1Pgc7BB7WZ01zgkW4Iwwvf6z \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "active": true,
  "country": "DE",
  "created": 1234567890,
  "description": "VAT Germany",
  "display_name": "VAT",
  "effective_percentage": null,
  "id": "txr_1Pgc7BB7WZ01zgkW4Iwwvf6z",
  "inclusive": false,
  "jurisdiction": "DE",
  "jurisdiction_level": null,
  "livemode": false,
  "metadata": {},
  "object": "tax_rate",
  "percentage": 19,
  "state": null,
  "tax_type": "vat",
  "flat_amount": {
    "amount": 1413853096,
    "currency": "currency"
  },
  "rate_type": 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.