# Tax GraphQL (https://developer.godaddy.com/en/docs/references/rest/taxes)

***

title: Tax GraphQL
description: Query and mutate taxes and rates on the commerce tax subgraph.
full: true
----------

Store-scoped tax GraphQL over HTTP. Use `commerce.tax:read` to query,
`commerce.tax:create` / `commerce.tax:write` / `commerce.tax:delete` to mutate
(by operation). See [Commerce API Scopes](https://developer.godaddy.com/docs/references/rest/commerce-scopes).

**Endpoint:** `POST /v2/commerce/stores/{storeId}/tax-subgraph`

Send the same store ID in the `{storeId}` path and the `x-store-id` header. The
header is required. If they differ, the subgraph uses the header. A missing
header returns HTTP 200 `AUTHENTICATION_ERROR` (`Failed to authorize`), not HTTP
401\.

For `SimpleMoneyInput.value`, send `1999` for $19.99 USD, not `19.99`.

Sidebar is grouped by **action/resource**. Expand a resource, then **Query**
(`commerce.tax:read`, 8 fields) or **Mutation**
(38 fields; scope depends on the verb). The live gateway also
exposes `_service`; it is omitted here.

## Example query

query

Requires `commerce.tax:read`. See [`classification`](https://developer.godaddy.com/docs/references/rest/taxes/classification/queries/classification) for the full schema.

```graphql
query GetClassification($id: ID!) {
  classification(id: $id) {
    id
    name
    label
  }
}
```

```bash
curl -X POST "https://api.godaddy.com/v2/commerce/stores/{storeId}/tax-subgraph" \
  -H "Authorization: Bearer $GODADDY_PAT" \
  -H "Content-Type: application/json" \
  -H "x-store-id: {storeId}" \
  -d '{
    "query": "query GetClassification($id: ID!) { classification(id: $id) { id name label } }",
    "variables": { "id": "CLASSIFICATION_ID" }
  }'
```

## Example mutation

mutation

Requires `commerce.tax:create`. See [`createRate`](https://developer.godaddy.com/docs/references/rest/taxes/rate/mutations/createRate) for the full schema.

```graphql
mutation CreateRate($input: MutationCreateRateInput!) {
  createRate(input: $input) {
    id
    name
    status
  }
}
```

```json
{
  "input": {
    "label": "Sales tax",
    "value": { "percentage": "8.5" }
  }
}
```

***

## HTTP reference

OpenAPI contract for the subgraph POST (headers, auth, response envelope):

## POST /stores/{storeId}/tax-subgraph

Tax GraphQL endpoint

Proxies GraphQL to the tax subgraph. Use the `query` field for the GraphQL document and optional `variables` / `operationName`. Send the same store ID in the `{storeId}` path and the `x-store-id` header. The header is required. If they differ, the subgraph uses the header. A missing header returns HTTP 200 with GraphQL `AUTHENTICATION_ERROR` (`Failed to authorize`).

### Path parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `storeId` | unknown | yes |  |

### Header parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `x-store-id` | unknown | yes | Required store ID. Send the same value as `{storeId}` in the path. If they differ, the subgraph uses this header. |

### Request body (required)

Content-Type: `application/json`

```json
{
  "query": "query GetClassification($id: ID!) { classification(id: $id) { id } }",
  "variables": {
    "id": "CLASSIFICATION_ID"
  }
}
```

Schema:

- object
  - `query` (required): string
  - `variables`: object
  - `operationName`: string

### Responses

**200** — GraphQL response

Content-Type: `application/json`

Schema:

- object
  - `data`: object
  - `errors`: array
      - items:

**400** — Invalid request

**401** — Unauthorized

**403** — Forbidden

**404** — Store not found

**500** — Internal server error

**Security:** requires `PAT`; scopes `commerce.tax:read`, `commerce.tax:create`, `commerce.tax:write`, `commerce.tax:delete`.