Skip to content
Search Articles/

less than a minute read • Updated 44 minutes ago

Custom Tax Endpoint Reference

Reference for the Foxy custom tax endpoint, including webhook events, response format, and example payloads.

Overview

This is a lookup reference for the custom tax endpoint. For setup, see Set up a custom tax endpoint.

Events

Each request includes a foxy-webhook-event header identifying the event:

Event

When it is sent

tax/calculate

For cart resources. Mirrors the custom shipping endpoint, which mirrors the API cart resource.

tax/report

When the transaction completes. Body mirrors a zoomed transaction API resource.

tax/refund

When a full refund is issued.

tax/void

When a payment is voided. May need different handling for accounting or reporting.

tax/update

When a partial refund is issued.

A separate header indicates the trigger:

Trigger

Meaning

checkout/submit

Accompanies a tax/calculate event, present only when the customer has clicked submit. Not sent on cart changes or address updates; it fires right before the pre-payment webhook.

Response format

Attribute

Description

ok

true if the tax was calculated normally, false if there was an error.

details

Error details, if any. Shown when ok is false.

name

The tax name shown on the cart and checkout.

expand_taxes

Array of the individual taxes that make up the total (at least one item). Shown individually on the receipt and in the admin.

expand_taxes[].name

Name of the individual tax.

expand_taxes[].amount

Amount for the individual tax.

expand_taxes[].rate

Rate for the individual tax, as a decimal (5% is 0.05).

total_amount

Total tax amount added to the order total. Should equal the sum of the expand_taxes amounts.

total_rate

Total combined rate, as a decimal, shown on the cart and checkout. Should equal the sum of the expand_taxes rates.

Example responses

Successful response with taxes:

{
  "ok": true,
  "details": "",
  "name": "Custom Tax",
  "expand_taxes": [
    { "name": "Super Tax", "amount": 5.00, "rate": 0.05 },
    { "name": "Mega Tax", "amount": 2.00, "rate": 0.02 }
  ],
  "total_amount": 7.00,
  "total_rate": 0.07
}

Successful response with no taxes to display:

{
  "ok": true,
  "details": "",
  "name": "",
  "expand_taxes": [],
  "total_amount": 0,
  "total_rate": 0
}

Error response (prevents checkout). If Foxy does not receive a valid response, it shows a default error and also prevents checkout:

{
  "ok": false,
  "details": "Your error message"
}

Display a tax without a percentage rate by omitting rate:

{
  "ok": true,
  "details": "",
  "name": "Custom Tax",
  "expand_taxes": [
    { "name": "Tax", "amount": 5.00 }
  ],
  "total_amount": 5.00
}

Display a 0% tax by setting the rate to 0:

{
  "ok": true,
  "details": "",
  "name": "Zero Amount",
  "expand_taxes": [
    { "name": "Tax", "rate": 0, "amount": 0 }
  ],
  "total_amount": 0,
  "total_rate": 0
}

Need Help?

Did this article answer your questions? Need help with anything? Please click below to contact us.