# Create a tax preset

```http
POST https://secure.yoprint.com/v1/api/store/{team_slug}/setting/tax_type
```

- API version: v1
- Operation ID: `v1_public_custom_tax_store`
- Section: Team settings › [Tax presets](https://developer.yoprint.com/reference/tax-presets.md)
- Web page: https://developer.yoprint.com/reference/tax-presets/v1-custom-tax-store/
- Authentication: `Authorization: Bearer YOUR_API_KEY`

Creates a tax preset and returns it. A `simple` preset (Single Line Tax) has one rate. A `line_tax` preset (Multi Line Tax) has up to 8 named parts, such as state, county and city, and its rate is their sum.

The new preset becomes the team default when you send `default: true`, or when the team has no default yet.

Tax presets are the taxes you apply to invoices. When YoPrint creates an invoice for you, it applies the default preset; on invoices you build yourself, you choose the tax. An invoice stores the rate it used, so changing or deleting a preset doesn't change existing invoices.

## Permission

Needs the Manage Settings permission.

## Business rules

- `type` is `simple` or `line_tax`. `system` presets are made by YoPrint and cannot be created.
- Rates are whole numbers, 0 or more, as a percentage ×1000: `8250` is 8.25%.
- A `line_tax` preset needs 1 to 8 parts, each with a `name` and a `total`. A `total` sent with a `line_tax` preset is ignored.
- The type cannot be changed later.

## Side effects

- With `default: true`, or when the team had no default, it becomes the default, and new invoices YoPrint creates use it.

## Path parameters

- `team_slug` (string, required): Your team slug, shown as Team ID next to your API key in Profile. Example `your-team`.

## Request body

Content type `application/json`, required.

What kind of tax? Send one of these 2 bodies: **Single Line Tax**, **Multi Line Tax**.

Picked by `type`: `simple` Single Line Tax, `line_tax` Multi Line Tax.

### Single Line Tax

Variant 1 of 2. On the web page: https://developer.yoprint.com/reference/tax-presets/v1-custom-tax-store/#variant-single-line-tax

One rate.

Fields:

- `type` (string, required): Always `"simple"`.
- `name` (string, required)
- `total` (integer, required): The rate. A percentage ×1000: `8250` is 8.25%. With `X-Yoprint-Decimal-Format: exact-v1`, a value that isn't a whole number comes back as a string. Minimum 0.
- `apply_before_disc` (boolean, optional): Calculate tax before the discount. Defaults to false. Default `false`.
- `default` (boolean, optional): `true` makes it the team's default tax preset. `false` does nothing.
- `enable` (boolean, optional): Defaults to true. Default `true`.
- `shipping_taxable` (boolean, optional): Tax shipping too. Defaults to true. Default `true`.

Example request (Single Line Tax):

```bash
curl -X POST 'https://secure.yoprint.com/v1/api/store/your-team/setting/tax_type' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: application/json' \
  -H 'X-Yoprint-Decimal-Format: exact-v1' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "State sales tax",
    "shipping_taxable": false,
    "total": 6000,
    "type": "simple"
  }'
```

### Multi Line Tax

Variant 2 of 2. On the web page: https://developer.yoprint.com/reference/tax-presets/v1-custom-tax-store/#variant-multi-line-tax

Named parts whose rates add up.

Fields:

- `type` (string, required): Always `"line_tax"`.
- `line_taxes` (array of objects, required): 1 to 8 parts. YoPrint sets the preset's `total` to their sum. 1 to 8 items.
  - Each item:
    - `name` (string, required): The part's name, such as `State` or `County`.
    - `total` (integer, required): The part's rate. A percentage ×1000: `8250` is 8.25%. With `X-Yoprint-Decimal-Format: exact-v1`, a value that isn't a whole number comes back as a string. Minimum 0.
- `name` (string, required)
- `apply_before_disc` (boolean, optional): Calculate tax before the discount. Defaults to false. Default `false`.
- `default` (boolean, optional): `true` makes it the team's default tax preset. `false` does nothing.
- `enable` (boolean, optional): Defaults to true. Default `true`.
- `shipping_taxable` (boolean, optional): Tax shipping too. Defaults to true. Default `true`.

Example request (Multi Line Tax):

```bash
curl -X POST 'https://secure.yoprint.com/v1/api/store/your-team/setting/tax_type' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: application/json' \
  -H 'X-Yoprint-Decimal-Format: exact-v1' \
  -H 'Content-Type: application/json' \
  -d '{
    "default": true,
    "line_taxes": [
      {
        "name": "State",
        "total": 6000
      },
      {
        "name": "County",
        "total": 2250
      }
    ],
    "name": "State and county",
    "type": "line_tax"
  }'
```

## Response

`200` Successful response.

Fields:

- `data` (object, required)
  - `apply_before_disc` (boolean, required): Whether tax is calculated before the discount (Calculate Taxes Before Discount). Normally false: tax comes after the discount.
  - `default` (boolean, required): Whether it is the team's default tax preset. At most one preset is the default.
  - `enable` (boolean, required)
  - `id` (string, required)
  - `line_taxes` (array of objects, required): The parts of a `line_tax` preset, as they were sent. Empty for the others.
    - Each item:
      - `name` (string, required): The part's name, such as `State` or `County`.
      - `total` (integer, required): The part's rate. A percentage ×1000: `8250` is 8.25%. With `X-Yoprint-Decimal-Format: exact-v1`, a value that isn't a whole number comes back as a string. Minimum 0.
  - `name` (string, required)
  - `secondary_type` (string | null, required): For `system` presets, which one: `auto` is Auto Tax, YoPrint's automatic US sales tax; `other` is a 0% preset some teams have, whose `name` always reads Tax Exempt. Null for your own presets.
  - `shipping_taxable` (boolean, required): Whether shipping is taxed (Tax Shipping).
  - `total` (integer, required): The rate. For `line_tax`, the sum of the parts. Auto Tax shows 0: its rate is looked up per invoice. A percentage ×1000: `8250` is 8.25%. With `X-Yoprint-Decimal-Format: exact-v1`, a value that isn't a whole number comes back as a string. Minimum 0.
  - `trashed` (boolean, required): True for a deleted preset. Restore it with Restore a tax preset.
  - `type` (string, required): `simple` (Single Line Tax): one rate. `line_tax` (Multi Line Tax): parts that add up. `system`: made by YoPrint, such as Auto Tax. One of: `"simple"`, `"line_tax"`, `"system"`.
  - `can_override_rates` (boolean, optional)
  - `can_override_rules` (boolean, optional)
  - `error` (string, optional)
  - `hidden` (boolean, optional)
  - `override_rates` (array of objects, optional)
  - `override_rules` (array of objects, optional)
  - `supported_place` (array of objects, optional)
- `status` (integer, required)
- `success` (boolean, required)

Example response:

```json
{
  "data": {
    "apply_before_disc": false,
    "can_override_rates": false,
    "can_override_rules": false,
    "default": false,
    "enable": true,
    "error": "",
    "hidden": false,
    "id": "Pn8oyZYD9l6qP7",
    "line_taxes": [],
    "name": "State sales tax",
    "override_rates": [],
    "override_rules": [],
    "secondary_type": null,
    "shipping_taxable": false,
    "supported_place": [],
    "total": 6000,
    "trashed": false,
    "type": "simple"
  },
  "status": 200,
  "success": true
}
```

## Errors

- `401` The API key is missing or wrong (`unauthenticated`).
  - When: The API key is missing or wrong. Fix: Send your personal API key as `Authorization: Bearer YOUR_API_KEY`.
- `403` You are not allowed to do this. `api_access_not_in_plan`: your team's plan doesn't include API access (Pro and above, with an active subscription or trial), so every request answers this until the team upgrades. When your role lacks the permission the operation needs, the body is only `{"message": "Insufficient Permission"}`. Other refusals use the error envelope, with `unauthorized` or `user_is_not_authorized`.
  - When: Your permission group lacks Manage Settings. This 403 has a short body, `{"message": "Insufficient Permission"}`, without `success` or `error`. Fix: Ask the team owner to give your permission group Manage Settings.
- `404` Not found. `page_not_found`: the team slug is unknown, you are not a member of the team, or an id in the path is not one of this team's. `code: null`, with a message that starts "No query results for": there is no record with that id.
- `422` The request was refused and changed nothing. `validation_failed` lists what to fix in `error.fields`; other codes name a business rule, explained in `error.message`. A few checks answer with only `{"message": "..."}`. An operation that calls another service (a payment provider, a carrier, an accounting app) can answer `connect_timeout` ("Please retry again") when that service does not answer in time: the change may or may not have happened there, so read the record back before you retry.
  - When: `type` is missing or not `simple` or `line_tax`, a rate is not a whole number of 0 or more, or `line_taxes` has no parts or more than 8. `error.code` is `validation_failed`, and `error.fields` names each field with its messages. Fix: Fix the fields listed in `error.fields` and send the request again.
  - When: The parts of a `line_tax` preset add up to more than YoPrint can store (`error.code` `amount_out_of_range`). Fix: Check the individual rates: they are a percentage ×1000 (`8250` is 8.25%).

## Related

- [List tax presets](https://developer.yoprint.com/reference/tax-presets/v1-custom-tax-index.md): `GET /v1/api/store/{team_slug}/setting/tax_type`
- [Update a tax preset (same as PUT)](https://developer.yoprint.com/reference/tax-presets/v1-custom-tax-update-patch.md): `PATCH /v1/api/store/{team_slug}/setting/tax_type/{hash_id}`