---
title: Build a tax app
description: Learn how to build, configure, test and deploy a tax app.
source_url:
  html: https://shopify.dev/docs/apps/build/tax/build-tax-app
  md: https://shopify.dev/docs/apps/build/tax/build-tax-app.md
---

# Build a tax app

**Note:**

Shopify's Tax Platform is available by invitation only to select tax software companies integrating with Shopify.

***

## What you'll learn

* How to create a partner account and dev store.
* How to create and deploy a tax app extension.
* How to test and publish your app.
* How to submit your tax app for review.

***

## Before Starting

* Create a [partner account](https://www.shopify.com/partners) and a [dev store](https://shopify.dev/docs/apps/build/dev-dashboard/development-stores).
  * Shopify will need to grant you access to create a tax app extension via the CLI once completed.
* Create a new app in the [Dev Dashboard](https://shopify.dev/docs/apps/build/dev-dashboard) or [Shopify CLI](https://shopify.dev/docs/apps/build/cli-for-apps).
  * Shopify will need to grant you access to the `write_taxes` access scope once completed.

![A flow diagram of the prerequisite steps to creating a tax app extension](https://cdn.shopify.com/shopifycloud/shopify-dev/production/assets/assets/images/apps/taxes/build-tax-app-create-CXmdoqIS.png)

***

## Step 1: Generate a new tax app

1. Generate a new tax calculation app extension with template files via the [Shopify CLI](https://shopify.dev/docs/apps/build/cli-for-apps)
2. Run the following Shopify CLI command from a terminal inside your app's repository: `shopify app generate extension`

**Note:**

If the terminal prompts you to log into the Shopify Partners portal to authenticate a session from Shopify CLI, press any key to open a page in your browser to log in. You may also be prompted to select a Partners Organization or to create a new app. If your app was previously deployed to your Partner account, choose the organization under which your deployed app is associated with, and connect the app extension to the existing app.

1. When prompted, select `Tax Calculation` as the extension type.

2. Name the new Tax Calculation extension and select `JavaScript React` as the extension's working type.

   * The name you provide is internal and won't be exposed to merchants.
   * The working type is not important, your extension will only be used to contain your tax app's configuration.

3. At this point, newly generated template files will be created for your tax app extension under the directory

```text
extensions/<YOUR_TAX_APP_EXTENSION_NAME>
```

***

## Step 2: Configure your tax app extension

Fill in the following details in the generated extension file

```text
shopify.ui.extension.toml
```

| Field | Description |
| - | - |
| `production_api_base_url` | The base URL of your app that merchants will use. Ex: `https://shopify_app.company.com/` |
| `benchmark_api_base_url` | The base URL of your app that Shopify will use for running load tests. Ex: `https://benchmark_app.company.com/` |
| `calculate_taxes_api_endpoint` | A relative URL path indicating your tax calculation endpoint. Shopify will combine this with your production URL or benchmark URL. For example, if `production_api_base_url` was configured as `https://shopify_app.company.com` and `calculate_taxes_api_endpoint` was configured as `api/calculate_taxes`, the full URL Shopify calls during tax calculations would be `https://shopify_app.company.com/api/calculate_taxes` |
| `metafields` | (Optional) Used for [metafields configuration](https://shopify.dev/docs/apps/build/tax/onboard/configure-metafields). |
| `input.metafield_identifiers` | (Optional) Used for [metafields configuration](https://shopify.dev/docs/apps/build/tax/onboard/configure-metafields). |
| `cart_line_properties` | (Optional) Used for [cart line properties configuration](https://shopify.dev/docs/apps/build/tax/onboard/configure-metafields#cart-line-properties). Available as of API version `2026-04`. |
| `api_version` | (Optional) This indicates the API version of the calculation request specified by the app. |

Here's an example of the configuration:

## shopify.ui.extension.toml

```toml
type = "tax_calculation"
name = "my-tax-calculation-extension"


production_api_base_url = "https://production-api.my-tax-app.com"
benchmark_api_base_url = "https://benchmark-api.my-tax-app.com"
calculate_taxes_api_endpoint = "api/tax_calculation"


[input.metafield_identifiers]
namespace="my_identifier_namespace"
key="my_identifier_key"
```

***

## Step 3: Deploy and release a new version of your Tax App

> Caution: You can't edit a version after it's created. If you want to change the settings on your tax calculation app extension, then you need to create and publish a new version by changing the configuration file that was generated in [Step 1](#step-1-generate-a-new-tax-app), and redeploy the app by following the instructions in this step.
>
> We currently don't support testing the app using `shopify app dev`.

Deploy and release a new version of your tax app and extension using Shopify CLI:

1. Run the following command that will deploy your app and extension as a new version:

## Terminal

```terminal
shopify app deploy
```

At this point, a new version of your tax app has been deployed to Shopify and is now live.

***

## Next step

To get your app reviewed, refer to the [app review process](https://shopify.dev/docs/apps/launch/app-store-review/review-process).

***