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. An order sold at one of the store’s locations that ships nothing is taxed at the location instead, and any other order that ships nothing at the billing address. Shipping and gift options are taxed like the goods. An EU store, one whose home is in the EU, 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. The threshold is only for a seller established in one EU country (VAT Directive Art. 59c), so a store with EU registrations in several, or established outside the EU, charges the destination’s VAT instead, and only where it’s registered, which it owes through the One-Stop Shop.

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 read-only price_mode, which follows its home country; 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/

Scope Required: taxes: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": "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/

Scope Required: taxes:write

Request Body

{
  "country": "US",
  "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": "US", "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 country must be the code of a country Easel knows, 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}/

Scope Required: taxes: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}/

Scope Required: taxes: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}/

Scope Required: taxes:write

Response

Status: 204 No Content

Tax Registration Object