API reference

Tax

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 Calculation

POST/v1/tax/calculations

Calculates tax based on the input and returns a Tax Calculation object.

Body parameters

  • currencystringRequired

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

  • line_itemsarray of objectsRequired

    A list of items the customer is purchasing. You can pass up to 100 line items, or 1,000 if your account has an increased limit.

    Show 7 child parameters
    • amountintegerRequired
    • metadataobject
    • productstring
    • quantityinteger
    • referencestring
    • tax_behaviorstring
      Possible values
      • exclusive
      • inclusive
    • tax_codestring
  • customerstring

    The ID of an existing customer to use for this calculation. If provided, the customer's address and tax IDs are copied to customer_details.

  • customer_detailsobject

    Details about the customer, including address and tax IDs.

    Show 5 child parameters
    • addressobject
      Show 6 child parameters
      • countrystringRequired
      • citystring
      • line1string
      • line2string
      • postal_codestring
      • statestring
    • address_sourcestring
      Possible values
      • billing
      • shipping
    • ip_addressstring
    • 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
    • taxability_overridestring
      Possible values
      • customer_exempt
      • none
      • reverse_charge
  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • ship_from_detailsobject

    Details about the address from which the goods are being shipped.

    Show 1 child parameter
    • addressobjectRequired
      Show 6 child parameters
      • countrystringRequired
      • citystring
      • line1string
      • line2string
      • postal_codestring
      • statestring
  • shipping_costobject

    Shipping cost details to be used for the calculation.

    Show 4 child parameters
    • amountinteger
    • shipping_ratestring
    • tax_behaviorstring
      Possible values
      • exclusive
      • inclusive
    • tax_codestring
  • tax_dateinteger

    The calculation uses the tax rules and rates that are in effect at this timestamp. You can use a date up to 31 days in the past or up to 31 days in the future. If you use a future date, Stripe doesn't guarantee that the expected tax rules and rate being used match the actual rules and rate that will be in effect on that date. We deploy tax changes before their effective date, but not within a fixed window.

Returns

The tax.calculation object.

POST /v1/tax/calculations
curl https://api.knoxapi.com/v1/tax/calculations \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d currency=usd \
  -d "line_items[0][amount]=1000"
Response
{
  "amount_total": 1947,
  "currency": "usd",
  "customer": null,
  "customer_details": {
    "address": {
      "city": "South San Francisco",
      "country": "US",
      "line1": "354 Oyster Point Blvd",
      "line2": "",
      "postal_code": "94080",
      "state": "CA"
    },
    "address_source": "shipping",
    "ip_address": null,
    "tax_ids": [],
    "taxability_override": "none"
  },
  "expires_at": 1234567890,
  "id": "taxcalc_1Pgc7HB7WZ01zgkW0snEQbxy",
  "livemode": false,
  "object": "tax.calculation",
  "ship_from_details": {
    "address": {
      "city": null,
      "country": "US",
      "line1": null,
      "line2": null,
      "postal_code": "75001",
      "state": "TX"
    }
  },
  "shipping_cost": {
    "amount": 300,
    "amount_tax": 0,
    "tax_behavior": "exclusive",
    "tax_code": "txcd_92010001"
  },
  "tax_amount_exclusive": 148,
  "tax_amount_inclusive": 0,
  "tax_breakdown": [
    {
      "amount": 148,
      "inclusive": false,
      "tax_rate_details": {
        "country": "US",
        "percentage_decimal": "9.875",
        "state": "CA",
        "tax_type": "sales_tax",
        "flat_amount": {
          "amount": 1413853096,
          "currency": "currency"
        },
        "rate_type": null
      },
      "taxability_reason": "standard_rated",
      "taxable_amount": 1499
    },
    {
      "amount": 0,
      "inclusive": false,
      "tax_rate_details": {
        "country": "US",
        "percentage_decimal": "0.0",
        "state": "CA",
        "tax_type": "sales_tax",
        "flat_amount": {
          "amount": 1413853096,
          "currency": "currency"
        },
        "rate_type": null
      },
      "taxability_reason": "product_exempt",
      "taxable_amount": 0
    }
  ],
  "tax_date": 1234567890
}

Create a registration

POST/v1/tax/registrations

Creates a new Tax Registration object.

Body parameters

  • active_fromstring | integerRequired

    Time at which the Tax Registration becomes active. It can be either now to indicate the current time, or a future timestamp measured in seconds since the Unix epoch.

    Possible values
    • now
  • countrystringRequired

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

  • country_optionsobjectRequired

    Specific options for a registration in the specified country.

    Show 101 child parameters
    • aeobject
      Show 2 child parameters
      • typestringRequired
        Possible values
        • standard
      • standardobject

        Child parameters are listed in the OpenAPI document.

    • alobject
      Show 2 child parameters
      • typestringRequired
        Possible values
        • standard
      • standardobject

        Child parameters are listed in the OpenAPI document.

    • amobject
      Show 1 child parameter
      • typestringRequired
        Possible values
        • simplified
    • aoobject
      Show 2 child parameters
      • typestringRequired
        Possible values
        • standard
      • standardobject

        Child parameters are listed in the OpenAPI document.

    • atobject
      Show 3 child parameters
      • typestringRequired
        Possible values
        • ioss
        • oss_non_union
        • oss_union
        • standard
      • igicobject

        Child parameters are listed in the OpenAPI document.

      • standardobject

        Child parameters are listed in the OpenAPI document.

    • auobject
      Show 2 child parameters
      • typestringRequired
        Possible values
        • standard
      • standardobject

        Child parameters are listed in the OpenAPI document.

    • awobject
      Show 2 child parameters
      • typestringRequired
        Possible values
        • standard
      • standardobject

        Child parameters are listed in the OpenAPI document.

    • azobject
      Show 1 child parameter
      • typestringRequired
        Possible values
        • simplified
    • baobject
      Show 2 child parameters
      • typestringRequired
        Possible values
        • standard
      • standardobject

        Child parameters are listed in the OpenAPI document.

    • bbobject
      Show 2 child parameters
      • typestringRequired
        Possible values
        • standard
      • standardobject

        Child parameters are listed in the OpenAPI document.

    • bdobject
      Show 2 child parameters
      • typestringRequired
        Possible values
        • standard
      • standardobject

        Child parameters are listed in the OpenAPI document.

    • beobject
      Show 3 child parameters
      • typestringRequired
        Possible values
        • ioss
        • oss_non_union
        • oss_union
        • standard
      • igicobject

        Child parameters are listed in the OpenAPI document.

      • standardobject

        Child parameters are listed in the OpenAPI document.

    • bfobject
      Show 2 child parameters
      • typestringRequired
        Possible values
        • standard
      • standardobject

        Child parameters are listed in the OpenAPI document.

    • bgobject
      Show 3 child parameters
      • typestringRequired
        Possible values
        • ioss
        • oss_non_union
        • oss_union
        • standard
      • igicobject

        Child parameters are listed in the OpenAPI document.

      • standardobject

        Child parameters are listed in the OpenAPI document.

    • bhobject
      Show 2 child parameters
      • typestringRequired
        Possible values
        • standard
      • standardobject

        Child parameters are listed in the OpenAPI document.

    • bjobject
      Show 1 child parameter
      • typestringRequired
        Possible values
        • simplified
    • bsobject
      Show 2 child parameters
      • typestringRequired
        Possible values
        • standard
      • standardobject

        Child parameters are listed in the OpenAPI document.

    • byobject
      Show 1 child parameter
      • typestringRequired
        Possible values
        • simplified
    • caobject
      Show 2 child parameters
      • typestringRequired
        Possible values
        • province_standard
        • simplified
        • standard
      • province_standardobject

        Child parameters are listed in the OpenAPI document.

    • cdobject
      Show 2 child parameters
      • typestringRequired
        Possible values
        • standard
      • standardobject

        Child parameters are listed in the OpenAPI document.

    • chobject
      Show 2 child parameters
      • typestringRequired
        Possible values
        • standard
      • standardobject

        Child parameters are listed in the OpenAPI document.

    • clobject
      Show 1 child parameter
      • typestringRequired
        Possible values
        • simplified
    • cmobject
      Show 1 child parameter
      • typestringRequired
        Possible values
        • simplified
    • coobject
      Show 1 child parameter
      • typestringRequired
        Possible values
        • simplified
    • crobject
      Show 1 child parameter
      • typestringRequired
        Possible values
        • simplified
    • cvobject
      Show 1 child parameter
      • typestringRequired
        Possible values
        • simplified
    • cyobject
      Show 3 child parameters
      • typestringRequired
        Possible values
        • ioss
        • oss_non_union
        • oss_union
        • standard
      • igicobject

        Child parameters are listed in the OpenAPI document.

      • standardobject

        Child parameters are listed in the OpenAPI document.

    • czobject
      Show 3 child parameters
      • typestringRequired
        Possible values
        • ioss
        • oss_non_union
        • oss_union
        • standard
      • igicobject

        Child parameters are listed in the OpenAPI document.

      • standardobject

        Child parameters are listed in the OpenAPI document.

    • deobject
      Show 3 child parameters
      • typestringRequired
        Possible values
        • ioss
        • oss_non_union
        • oss_union
        • standard
      • igicobject

        Child parameters are listed in the OpenAPI document.

      • standardobject

        Child parameters are listed in the OpenAPI document.

    • dkobject
      Show 3 child parameters
      • typestringRequired
        Possible values
        • ioss
        • oss_non_union
        • oss_union
        • standard
      • igicobject

        Child parameters are listed in the OpenAPI document.

      • standardobject

        Child parameters are listed in the OpenAPI document.

    • ecobject
      Show 1 child parameter
      • typestringRequired
        Possible values
        • simplified
    • eeobject
      Show 3 child parameters
      • typestringRequired
        Possible values
        • ioss
        • oss_non_union
        • oss_union
        • standard
      • igicobject

        Child parameters are listed in the OpenAPI document.

      • standardobject

        Child parameters are listed in the OpenAPI document.

    • egobject
      Show 1 child parameter
      • typestringRequired
        Possible values
        • simplified
    • esobject
      Show 3 child parameters
      • typestringRequired
        Possible values
        • ioss
        • oss_non_union
        • oss_union
        • standard
      • igicobject

        Child parameters are listed in the OpenAPI document.

      • standardobject

        Child parameters are listed in the OpenAPI document.

    • etobject
      Show 2 child parameters
      • typestringRequired
        Possible values
        • standard
      • standardobject

        Child parameters are listed in the OpenAPI document.

    • fiobject
      Show 3 child parameters
      • typestringRequired
        Possible values
        • ioss
        • oss_non_union
        • oss_union
        • standard
      • igicobject

        Child parameters are listed in the OpenAPI document.

      • standardobject

        Child parameters are listed in the OpenAPI document.

    • frobject
      Show 3 child parameters
      • typestringRequired
        Possible values
        • ioss
        • oss_non_union
        • oss_union
        • standard
      • igicobject

        Child parameters are listed in the OpenAPI document.

      • standardobject

        Child parameters are listed in the OpenAPI document.

    • gbobject
      Show 2 child parameters
      • typestringRequired
        Possible values
        • standard
      • standardobject

        Child parameters are listed in the OpenAPI document.

    • geobject
      Show 1 child parameter
      • typestringRequired
        Possible values
        • simplified
    • gnobject
      Show 2 child parameters
      • typestringRequired
        Possible values
        • standard
      • standardobject

        Child parameters are listed in the OpenAPI document.

    • grobject
      Show 3 child parameters
      • typestringRequired
        Possible values
        • ioss
        • oss_non_union
        • oss_union
        • standard
      • igicobject

        Child parameters are listed in the OpenAPI document.

      • standardobject

        Child parameters are listed in the OpenAPI document.

    • hrobject
      Show 3 child parameters
      • typestringRequired
        Possible values
        • ioss
        • oss_non_union
        • oss_union
        • standard
      • igicobject

        Child parameters are listed in the OpenAPI document.

      • standardobject

        Child parameters are listed in the OpenAPI document.

    • huobject
      Show 3 child parameters
      • typestringRequired
        Possible values
        • ioss
        • oss_non_union
        • oss_union
        • standard
      • igicobject

        Child parameters are listed in the OpenAPI document.

      • standardobject

        Child parameters are listed in the OpenAPI document.

    • idobject
      Show 1 child parameter
      • typestringRequired
        Possible values
        • simplified
    • ieobject
      Show 3 child parameters
      • typestringRequired
        Possible values
        • ioss
        • oss_non_union
        • oss_union
        • standard
      • igicobject

        Child parameters are listed in the OpenAPI document.

      • standardobject

        Child parameters are listed in the OpenAPI document.

    • inobject
      Show 1 child parameter
      • typestringRequired
        Possible values
        • simplified
    • isobject
      Show 2 child parameters
      • typestringRequired
        Possible values
        • standard
      • standardobject

        Child parameters are listed in the OpenAPI document.

    • itobject
      Show 3 child parameters
      • typestringRequired
        Possible values
        • ioss
        • oss_non_union
        • oss_union
        • standard
      • igicobject

        Child parameters are listed in the OpenAPI document.

      • standardobject

        Child parameters are listed in the OpenAPI document.

    • jpobject
      Show 2 child parameters
      • typestringRequired
        Possible values
        • standard
      • standardobject

        Child parameters are listed in the OpenAPI document.

    • keobject
      Show 1 child parameter
      • typestringRequired
        Possible values
        • simplified
    • kgobject
      Show 1 child parameter
      • typestringRequired
        Possible values
        • simplified
    • khobject
      Show 1 child parameter
      • typestringRequired
        Possible values
        • simplified
    • krobject
      Show 1 child parameter
      • typestringRequired
        Possible values
        • simplified
    • kzobject
      Show 1 child parameter
      • typestringRequired
        Possible values
        • simplified
    • laobject
      Show 1 child parameter
      • typestringRequired
        Possible values
        • simplified
    • lkobject
      Show 1 child parameter
      • typestringRequired
        Possible values
        • simplified
    • ltobject
      Show 3 child parameters
      • typestringRequired
        Possible values
        • ioss
        • oss_non_union
        • oss_union
        • standard
      • igicobject

        Child parameters are listed in the OpenAPI document.

      • standardobject

        Child parameters are listed in the OpenAPI document.

    • luobject
      Show 3 child parameters
      • typestringRequired
        Possible values
        • ioss
        • oss_non_union
        • oss_union
        • standard
      • igicobject

        Child parameters are listed in the OpenAPI document.

      • standardobject

        Child parameters are listed in the OpenAPI document.

    • lvobject
      Show 3 child parameters
      • typestringRequired
        Possible values
        • ioss
        • oss_non_union
        • oss_union
        • standard
      • igicobject

        Child parameters are listed in the OpenAPI document.

      • standardobject

        Child parameters are listed in the OpenAPI document.

    • maobject
      Show 1 child parameter
      • typestringRequired
        Possible values
        • simplified
    • mdobject
      Show 1 child parameter
      • typestringRequired
        Possible values
        • simplified
    • meobject
      Show 2 child parameters
      • typestringRequired
        Possible values
        • standard
      • standardobject

        Child parameters are listed in the OpenAPI document.

    • mkobject
      Show 2 child parameters
      • typestringRequired
        Possible values
        • standard
      • standardobject

        Child parameters are listed in the OpenAPI document.

    • mrobject
      Show 2 child parameters
      • typestringRequired
        Possible values
        • standard
      • standardobject

        Child parameters are listed in the OpenAPI document.

    • mtobject
      Show 3 child parameters
      • typestringRequired
        Possible values
        • ioss
        • oss_non_union
        • oss_union
        • standard
      • igicobject

        Child parameters are listed in the OpenAPI document.

      • standardobject

        Child parameters are listed in the OpenAPI document.

    • mxobject
      Show 1 child parameter
      • typestringRequired
        Possible values
        • simplified
    • myobject
      Show 1 child parameter
      • typestringRequired
        Possible values
        • simplified
    • ngobject
      Show 1 child parameter
      • typestringRequired
        Possible values
        • simplified
    • nlobject
      Show 3 child parameters
      • typestringRequired
        Possible values
        • ioss
        • oss_non_union
        • oss_union
        • standard
      • igicobject

        Child parameters are listed in the OpenAPI document.

      • standardobject

        Child parameters are listed in the OpenAPI document.

    • noobject
      Show 2 child parameters
      • typestringRequired
        Possible values
        • standard
      • standardobject

        Child parameters are listed in the OpenAPI document.

    • npobject
      Show 1 child parameter
      • typestringRequired
        Possible values
        • simplified
    • nzobject
      Show 2 child parameters
      • typestringRequired
        Possible values
        • standard
      • standardobject

        Child parameters are listed in the OpenAPI document.

    • omobject
      Show 2 child parameters
      • typestringRequired
        Possible values
        • standard
      • standardobject

        Child parameters are listed in the OpenAPI document.

    • peobject
      Show 1 child parameter
      • typestringRequired
        Possible values
        • simplified
    • phobject
      Show 1 child parameter
      • typestringRequired
        Possible values
        • simplified
    • plobject
      Show 3 child parameters
      • typestringRequired
        Possible values
        • ioss
        • oss_non_union
        • oss_union
        • standard
      • igicobject

        Child parameters are listed in the OpenAPI document.

      • standardobject

        Child parameters are listed in the OpenAPI document.

    • ptobject
      Show 3 child parameters
      • typestringRequired
        Possible values
        • ioss
        • oss_non_union
        • oss_union
        • standard
      • igicobject

        Child parameters are listed in the OpenAPI document.

      • standardobject

        Child parameters are listed in the OpenAPI document.

    • roobject
      Show 3 child parameters
      • typestringRequired
        Possible values
        • ioss
        • oss_non_union
        • oss_union
        • standard
      • igicobject

        Child parameters are listed in the OpenAPI document.

      • standardobject

        Child parameters are listed in the OpenAPI document.

    • rsobject
      Show 2 child parameters
      • typestringRequired
        Possible values
        • standard
      • standardobject

        Child parameters are listed in the OpenAPI document.

    • ruobject
      Show 1 child parameter
      • typestringRequired
        Possible values
        • simplified
    • saobject
      Show 1 child parameter
      • typestringRequired
        Possible values
        • simplified
    • seobject
      Show 3 child parameters
      • typestringRequired
        Possible values
        • ioss
        • oss_non_union
        • oss_union
        • standard
      • igicobject

        Child parameters are listed in the OpenAPI document.

      • standardobject

        Child parameters are listed in the OpenAPI document.

    • sgobject
      Show 2 child parameters
      • typestringRequired
        Possible values
        • standard
      • standardobject

        Child parameters are listed in the OpenAPI document.

    • siobject
      Show 3 child parameters
      • typestringRequired
        Possible values
        • ioss
        • oss_non_union
        • oss_union
        • standard
      • igicobject

        Child parameters are listed in the OpenAPI document.

      • standardobject

        Child parameters are listed in the OpenAPI document.

    • skobject
      Show 3 child parameters
      • typestringRequired
        Possible values
        • ioss
        • oss_non_union
        • oss_union
        • standard
      • igicobject

        Child parameters are listed in the OpenAPI document.

      • standardobject

        Child parameters are listed in the OpenAPI document.

    • snobject
      Show 1 child parameter
      • typestringRequired
        Possible values
        • simplified
    • srobject
      Show 2 child parameters
      • typestringRequired
        Possible values
        • standard
      • standardobject

        Child parameters are listed in the OpenAPI document.

    • thobject
      Show 1 child parameter
      • typestringRequired
        Possible values
        • simplified
    • tjobject
      Show 1 child parameter
      • typestringRequired
        Possible values
        • simplified
    • trobject
      Show 1 child parameter
      • typestringRequired
        Possible values
        • simplified
    • twobject
      Show 1 child parameter
      • typestringRequired
        Possible values
        • simplified
    • tzobject
      Show 1 child parameter
      • typestringRequired
        Possible values
        • simplified
    • uaobject
      Show 1 child parameter
      • typestringRequired
        Possible values
        • simplified
    • ugobject
      Show 1 child parameter
      • typestringRequired
        Possible values
        • simplified
    • usobject
      Show 7 child parameters
      • statestringRequired
      • typestringRequired
        Possible values
        • local_amusement_tax
        • local_lease_tax
        • mass_transit_parking_tax
        • parking_tax
        • state_communications_tax
        • state_retail_delivery_fee
        • state_sales_tax
      • local_amusement_taxobject

        Child parameters are listed in the OpenAPI document.

      • local_lease_taxobject

        Child parameters are listed in the OpenAPI document.

      • mass_transit_parking_taxobject

        Child parameters are listed in the OpenAPI document.

      • parking_taxobject

        Child parameters are listed in the OpenAPI document.

      • state_sales_taxobject

        Child parameters are listed in the OpenAPI document.

    • uyobject
      Show 2 child parameters
      • typestringRequired
        Possible values
        • standard
      • standardobject

        Child parameters are listed in the OpenAPI document.

    • uzobject
      Show 1 child parameter
      • typestringRequired
        Possible values
        • simplified
    • vnobject
      Show 1 child parameter
      • typestringRequired
        Possible values
        • simplified
    • zaobject
      Show 2 child parameters
      • typestringRequired
        Possible values
        • standard
      • standardobject

        Child parameters are listed in the OpenAPI document.

    • zmobject
      Show 1 child parameter
      • typestringRequired
        Possible values
        • simplified
    • zwobject
      Show 2 child parameters
      • typestringRequired
        Possible values
        • standard
      • standardobject

        Child parameters are listed in the OpenAPI document.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • expires_atinteger

    If set, the Tax Registration stops being active at this time. If not set, the Tax Registration will be active indefinitely. Timestamp measured in seconds since the Unix epoch.

Returns

The tax.registration object.

POST /v1/tax/registrations
curl https://api.knoxapi.com/v1/tax/registrations \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d active_from=1234567890 \
  -d country=US \
  -d country_options=
Response
{
  "active_from": 1234567890,
  "country": "US",
  "country_options": {
    "us": {
      "state": "CA",
      "type": "state_sales_tax"
    }
  },
  "created": 1234567890,
  "expires_at": 1234567890,
  "id": "taxreg_QXhWPxHxRGhVsh",
  "livemode": false,
  "object": "tax.registration",
  "status": "active"
}

List registrations

GET/v1/tax/registrations

Returns a list of Tax Registration objects.

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.

  • statusstring

    The status of the Tax Registration.

    Possible values
    • active
    • all
    • expired
    • scheduled

Returns

A list of tax.registration objects.

GET /v1/tax/registrations
curl -G https://api.knoxapi.com/v1/tax/registrations \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode limit=3
Response
{
  "object": "list",
  "url": "/v1/tax/registrations",
  "has_more": false,
  "data": [
    {
      "active_from": 1234567890,
      "country": "US",
      "country_options": {
        "us": {
          "state": "CA",
          "type": "state_sales_tax"
        }
      },
      "created": 1234567890,
      "expires_at": 1234567890,
      "id": "taxreg_QXhWPxHxRGhVsh",
      "livemode": false,
      "object": "tax.registration",
      "status": "active"
    }
  ]
}

Update settings

POST/v1/tax/settings

Updates Tax Settings parameters used in tax calculations. All parameters are editable but none can be removed once set.

Body parameters

  • defaultsobject

    Default configuration to be used on Stripe Tax calculations.

    Show 2 child parameters
    • tax_behaviorstring
      Possible values
      • exclusive
      • inclusive
      • inferred_by_currency
    • tax_codestring
  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • head_officeobject

    The place where your business is located.

    Show 1 child parameter
    • addressobjectRequired
      Show 6 child parameters
      • citystring
      • countrystring
      • line1string
      • line2string
      • postal_codestring
      • statestring

Returns

The tax.settings object.

POST /v1/tax/settings
curl -X POST https://api.knoxapi.com/v1/tax/settings \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "defaults": {
    "tax_behavior": null,
    "tax_code": "txcd_10000000",
    "provider": "stripe"
  },
  "head_office": {
    "address": {
      "city": null,
      "country": "US",
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": "CA"
    }
  },
  "livemode": false,
  "object": "tax.settings",
  "status": "active",
  "status_details": {
    "active": {}
  }
}

Retrieve settings

GET/v1/tax/settings

Retrieves Tax Settings for a merchant.

Query parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The tax.settings object.

GET /v1/tax/settings
curl https://api.knoxapi.com/v1/tax/settings \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "defaults": {
    "tax_behavior": null,
    "tax_code": "txcd_10000000",
    "provider": "stripe"
  },
  "head_office": {
    "address": {
      "city": null,
      "country": "US",
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": "CA"
    }
  },
  "livemode": false,
  "object": "tax.settings",
  "status": "active",
  "status_details": {
    "active": {}
  }
}

Retrieve a Calculation

GET/v1/tax/calculations/{calculation}

Retrieves a Tax Calculation object, if the calculation hasn’t expired.

Path parameters

  • calculationstringRequired

Query parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The tax.calculation object.

GET /v1/tax/calculations/{calculation}
curl https://api.knoxapi.com/v1/tax/calculations/taxcalc_1Pgc7HB7WZ01zgkW0snEQbxy \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "amount_total": 1947,
  "currency": "usd",
  "customer": null,
  "customer_details": {
    "address": {
      "city": "South San Francisco",
      "country": "US",
      "line1": "354 Oyster Point Blvd",
      "line2": "",
      "postal_code": "94080",
      "state": "CA"
    },
    "address_source": "shipping",
    "ip_address": null,
    "tax_ids": [],
    "taxability_override": "none"
  },
  "expires_at": 1234567890,
  "id": "taxcalc_1Pgc7HB7WZ01zgkW0snEQbxy",
  "livemode": false,
  "object": "tax.calculation",
  "ship_from_details": {
    "address": {
      "city": null,
      "country": "US",
      "line1": null,
      "line2": null,
      "postal_code": "75001",
      "state": "TX"
    }
  },
  "shipping_cost": {
    "amount": 300,
    "amount_tax": 0,
    "tax_behavior": "exclusive",
    "tax_code": "txcd_92010001"
  },
  "tax_amount_exclusive": 148,
  "tax_amount_inclusive": 0,
  "tax_breakdown": [
    {
      "amount": 148,
      "inclusive": false,
      "tax_rate_details": {
        "country": "US",
        "percentage_decimal": "9.875",
        "state": "CA",
        "tax_type": "sales_tax",
        "flat_amount": {
          "amount": 1413853096,
          "currency": "currency"
        },
        "rate_type": null
      },
      "taxability_reason": "standard_rated",
      "taxable_amount": 1499
    },
    {
      "amount": 0,
      "inclusive": false,
      "tax_rate_details": {
        "country": "US",
        "percentage_decimal": "0.0",
        "state": "CA",
        "tax_type": "sales_tax",
        "flat_amount": {
          "amount": 1413853096,
          "currency": "currency"
        },
        "rate_type": null
      },
      "taxability_reason": "product_exempt",
      "taxable_amount": 0
    }
  ],
  "tax_date": 1234567890
}

Update a registration

POST/v1/tax/registrations/{id}

Updates an existing Tax Registration object. A registration cannot be deleted after it has been created. If you wish to end a registration you may do so by setting expires_at.

Path parameters

  • idstringRequired

Body parameters

  • active_fromstring | integer

    Time at which the registration becomes active. It can be either now to indicate the current time, or a timestamp measured in seconds since the Unix epoch.

    Possible values
    • now
  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • expires_atstring | integer

    If set, the registration stops being active at this time. If not set, the registration will be active indefinitely. It can be either now to indicate the current time, or a timestamp measured in seconds since the Unix epoch.

    Possible values
    • now

Returns

The tax.registration object.

POST /v1/tax/registrations/{id}
curl -X POST https://api.knoxapi.com/v1/tax/registrations/taxreg_QXhWPxHxRGhVsh \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "active_from": 1234567890,
  "country": "US",
  "country_options": {
    "us": {
      "state": "CA",
      "type": "state_sales_tax"
    }
  },
  "created": 1234567890,
  "expires_at": 1234567890,
  "id": "taxreg_QXhWPxHxRGhVsh",
  "livemode": false,
  "object": "tax.registration",
  "status": "active"
}

Retrieve a registration

GET/v1/tax/registrations/{id}

Returns a Tax Registration object.

Path parameters

  • idstringRequired

Query parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The tax.registration object.

GET /v1/tax/registrations/{id}
curl https://api.knoxapi.com/v1/tax/registrations/taxreg_QXhWPxHxRGhVsh \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "active_from": 1234567890,
  "country": "US",
  "country_options": {
    "us": {
      "state": "CA",
      "type": "state_sales_tax"
    }
  },
  "created": 1234567890,
  "expires_at": 1234567890,
  "id": "taxreg_QXhWPxHxRGhVsh",
  "livemode": false,
  "object": "tax.registration",
  "status": "active"
}

Retrieve a Calculation's line items

GET/v1/tax/calculations/{calculation}/line_items

Retrieves the line items of a tax calculation as a collection, if the calculation hasn’t expired.

Path parameters

  • calculationstringRequired

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 tax.calculation_line_item objects.

GET /v1/tax/calculations/{calculation}/line_items
curl -G https://api.knoxapi.com/v1/tax/calculations/calculation_123/line_items \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode limit=3
Response
{
  "object": "list",
  "url": "/v1/tax/calculations",
  "has_more": false,
  "data": [
    {
      "amount": 1499,
      "amount_tax": 148,
      "id": "tax_li_QXhWXb3MbhgP1Q",
      "livemode": false,
      "object": "tax.calculation_line_item",
      "product": null,
      "quantity": 1,
      "reference": "Pepperoni Pizza",
      "tax_behavior": "exclusive",
      "tax_code": "txcd_40060003",
      "metadata": 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.