Taxes

Tax configuration is managed at the store level with three modes: automatic (Stripe Tax via Connect), manual (flat-rate tables), and disabled. All products and collections are taxable by default — use exemptions to override.

The tax calculation mode is set via PATCH /v1/store with the tax_calculation field. Tax rates and exemptions are managed through dedicated endpoints under /v1/store/tax.

Base URL: https://api.hydrajs.dev

Endpoints

Method	Path	Auth	Description
GET	/v1/store/tax/rates	Secret	List tax rates
POST	/v1/store/tax/rates	Secret	Create a tax rate
PATCH	/v1/store/tax/rates/{id}	Secret	Update a tax rate
DELETE	/v1/store/tax/rates/{id}	Secret	Delete a tax rate
GET	/v1/store/tax/exemptions	Secret	List tax exemptions
POST	/v1/store/tax/exemptions	Secret	Create a tax exemption
DELETE	/v1/store/tax/exemptions/{id}	Secret	Delete a tax exemption

---

Set tax calculation mode

The tax mode is a store-level setting, updated via the Store API:

curl -X PATCH https://api.hydrajs.dev/v1/store \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tax_calculation": "automatic"}'

Value	Description
automatic	Tax calculated via payment provider based on customer location. Requires payment processing.
manual	Flat rates defined per country/state in the tax rates table.
disabled	No tax calculated at checkout.

---

List tax rates

GET /v1/store/tax/rates

Returns a paginated list of manual tax rates.

Query parameters

Parameter	Type	Default	Description
limit	integer	25	Results per page (1-250)
cursor	string	-	Pagination cursor from a previous response
order	string	desc	Sort direction: asc, desc
country	string	-	Filter by ISO 3166-1 alpha-2 country code

Request

curl https://api.hydrajs.dev/v1/store/tax/rates?country=US \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 200

{
	"data": [
		{
			"id": "txr_abc123def456ghij",
			"name": "California Sales Tax",
			"country": "US",
			"state": "CA",
			"rate": 7.25,
			"is_shipping_taxed": false,
			"created_at": "2026-08-01T09:30:00.000Z",
			"updated_at": "2026-08-01T09:30:00.000Z"
		}
	],
	"pagination": {
		"cursor": null,
		"has_more": false,
		"total": 1
	}
}

---

Create a tax rate

POST /v1/store/tax/rates

Creates a manual tax rate for a country and optional state. Duplicate country/state combinations are rejected with a 409 Conflict.

Request body

Field	Type	Required	Description
name	string	Yes	Human-readable label (1-255 chars)
country	string	Yes	ISO 3166-1 alpha-2 code (2 chars, uppercased)
state	string	No	State/province code (max 10 chars)
rate	number	Yes	Tax percentage, 0-100 (e.g. 7.25)
is_shipping_taxed	boolean	No	Whether shipping is taxed at this rate. Default false

Request

curl -X POST https://api.hydrajs.dev/v1/store/tax/rates \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New York Combined",
    "country": "US",
    "state": "NY",
    "rate": 8.875,
    "is_shipping_taxed": true
  }'

Response 201

{
	"data": {
		"id": "txr_xyz789abc123defg",
		"name": "New York Combined",
		"country": "US",
		"state": "NY",
		"rate": 8.875,
		"is_shipping_taxed": true,
		"created_at": "2026-08-15T14:00:00.000Z",
		"updated_at": "2026-08-15T14:00:00.000Z"
	}
}

---

Update a tax rate

PATCH /v1/store/tax/rates/{id}

Updates a tax rate. Only provided fields are changed. If country or state is changed and the new combination already exists, returns 409 Conflict.

Request

curl -X PATCH https://api.hydrajs.dev/v1/store/tax/rates/txr_abc123 \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rate": 8.0, "is_shipping_taxed": true}'

Response 200

Returns the updated tax rate object.

---

Delete a tax rate

DELETE /v1/store/tax/rates/{id}

Permanently deletes a tax rate.

Request

curl -X DELETE https://api.hydrajs.dev/v1/store/tax/rates/txr_abc123 \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 204

No body.

---

List tax exemptions

GET /v1/store/tax/exemptions

Returns a paginated list of tax-exempt products and collections. Each exemption includes the resolved resource name for display.

Query parameters

Parameter	Type	Default	Description
limit	integer	25	Results per page (1-250)
cursor	string	-	Pagination cursor from a previous response
order	string	desc	Sort direction: asc, desc
resource_type	string	-	Filter by type: product, collection

Request

curl https://api.hydrajs.dev/v1/store/tax/exemptions?resource_type=product \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 200

{
	"data": [
		{
			"id": "txe_abc123def456ghij",
			"resource_type": "product",
			"resource_id": "prod_abc123",
			"resource_name": "Digital Gift Card",
			"created_at": "2026-08-10T12:00:00.000Z",
			"updated_at": "2026-08-10T12:00:00.000Z"
		}
	],
	"pagination": {
		"cursor": null,
		"has_more": false,
		"total": 1
	}
}

---

Create a tax exemption

POST /v1/store/tax/exemptions

Marks a product or collection as tax-exempt. The referenced resource must exist and not be soft-deleted. Duplicate exemptions return 409 Conflict.

Request body

Field	Type	Required	Description
resource_type	string	Yes	product or collection
resource_id	string	Yes	ID of the product or collection

Request

curl -X POST https://api.hydrajs.dev/v1/store/tax/exemptions \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"resource_type": "collection", "resource_id": "col_abc123"}'

Response 201

{
	"data": {
		"id": "txe_xyz789abc123defg",
		"resource_type": "collection",
		"resource_id": "col_abc123",
		"resource_name": "Digital Downloads",
		"created_at": "2026-08-15T14:30:00.000Z",
		"updated_at": "2026-08-15T14:30:00.000Z"
	}
}

---

Delete a tax exemption

DELETE /v1/store/tax/exemptions/{id}

Removes a tax exemption. The resource will be taxable again.

Request

curl -X DELETE https://api.hydrajs.dev/v1/store/tax/exemptions/txe_abc123 \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 204

No body.

---

Object reference

Tax Rate

Field	Type	Description
id	string	Unique identifier (txr_ prefix)
name	string	Human-readable label
country	string	ISO 3166-1 alpha-2 country code
state	string | null	State/province code, or null for country-wide rates
rate	number	Tax percentage (0-100)
is_shipping_taxed	boolean	Whether shipping is taxed at this rate
created_at	string	ISO 8601 timestamp
updated_at	string	ISO 8601 timestamp

Tax Exemption

Field	Type	Description
id	string	Unique identifier (txe_ prefix)
resource_type	string	product or collection
resource_id	string	ID of the exempted resource
resource_name	string | null	Resolved title of the resource (null if deleted)
created_at	string	ISO 8601 timestamp
updated_at	string	ISO 8601 timestamp