Tax Registrations API

A store collects sales tax, VAT, or GST only where it has a tax
registration: a country, or one region of it such as a US state or a
Canadian province. With none, checkout charges no tax. Registrations belong
to the store and apply to every site.

Checkout taxes an order going to a place the store is registered, using the
built-in rate for that place unless the registration has a rate of its
own. Shipping and gift options are taxed like the goods. An EU store with
exactly one EU registration charges that country's VAT on sales to other EU
countries it isn't registered in, as distance sales under the €10,000
threshold do.

Built-in US rates are each state's base rate and leave out city, county,
and district taxes. For an accurate rate, set rate to your combined rate.
Countries outside the built-in table need a rate.

Whether prices include tax is the site's price_mode; see
Sites. An order records the tax it charged; see the
Order Tax Object.

Endpoints

• List Tax Registrations - GET /api/v1/tax-registrations/
• Create Tax Registration - POST /api/v1/tax-registrations/
• Get Tax Registration - GET /api/v1/tax-registrations/{tax_registration_id}/
• Update Tax Registration - PUT /api/v1/tax-registrations/{tax_registration_id}/
• Delete Tax Registration - DELETE /api/v1/tax-registrations/{tax_registration_id}/

List Tax Registrations

List where the store collects tax. A store has at most 100 registrations, so
this endpoint is not paginated and has_more is always false.

Endpoint: GET /api/v1/tax-registrations/

Permission Required: Read

Request

curl -X GET "https://studio.easel.engineering/api/v1/tax-registrations/" \
  -H "Authorization: Bearer your_api_key_here"

Response

Status: 200 OK

{
  "data": [
    {
      "id": "txr_d0b6fmv28q6vn14peun0",
      "country_id": 236,
      "country": "US",
      "region": "CA",
      "rate": "9.5",
      "tax_id": null,
      "created_at": "2026-10-19T10:00:00Z",
      "updated_at": "2026-10-19T10:00:00Z"
    }
  ],
  "has_more": false
}

Create Tax Registration

Register the store to collect tax in a country or one region of it.

Endpoint: POST /api/v1/tax-registrations/

Permission Required: Write

Request Body

{
  "country_id": 236,
  "region": "CA",
  "rate": "9.5",
  "tax_id": "SR-123-4567"
}

Request

curl -X POST "https://studio.easel.engineering/api/v1/tax-registrations/" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-request-id-12345" \
  -d '{"country_id": 236, "region": "CA", "rate": "9.5"}'

Response

Status: 201 Created

Returns the Tax Registration Object.

Error Responses

Invalid field

Status: 400 Bad Request

{
  "error": "Rate is required where there's no built-in rate",
  "code": "INVALID_FIELD"
}

The region must be one the built-in table knows for the country, and the
store can register in each place once.

Get Tax Registration

Endpoint: GET /api/v1/tax-registrations/{tax_registration_id}/

Permission Required: Read

Response

Status: 200 OK

Returns the Tax Registration Object.

Update Tax Registration

Replace a registration's rate and tax ID. Its place can't change, since past
orders name it; delete it and create another instead.

Endpoint: PUT /api/v1/tax-registrations/{tax_registration_id}/

Permission Required: Write

Request Body

{
  "rate": null,
  "tax_id": "SR-123-4567"
}

Response

Status: 200 OK

Returns the Tax Registration Object.

Delete Tax Registration

Stop collecting tax in a place. Orders already placed keep the tax they
collected.

Endpoint: DELETE /api/v1/tax-registrations/{tax_registration_id}/

Permission Required: Write

Response

Status: 204 No Content

Tax Registration Object