Create a tax preset

POST/v1/api/store/{team_slug}/setting/tax_type

v1Operation ID v1_public_custom_tax_store

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_slugstringrequired
Your team slug, shown as Team ID next to your API key in Profile.
- Example your-team

Request body

application/json, required.

What kind of tax?

Send one of these 2 bodies. Picked by type.

simple: Single Line Tax
line_tax: Multi Line Tax

Single Line TaxsimpleMulti Line Taxline_tax

Single Line Tax

One rate.

typestringrequired
- Always "simple"
namestringrequired
totalintegerrequired
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_discboolean
Calculate tax before the discount. Defaults to false.
- Default false
defaultboolean
true makes it the team's default tax preset. false does nothing.
enableboolean
Defaults to true.
- Default true
shipping_taxableboolean
Tax shipping too. Defaults to true.
- Default true

Example request

curl

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

Named parts whose rates add up.

typestringrequired
- Always "line_tax"
line_taxesarray of objectsrequired
1 to 8 parts. YoPrint sets the preset's total to their sum.
- 1 to 8 items
Fields of each item (2)
- namestringrequired
  The part's name, such as State or County.
- totalintegerrequired
  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
namestringrequired
apply_before_discboolean
Calculate tax before the discount. Defaults to false.
- Default false
defaultboolean
true makes it the team's default tax preset. false does nothing.
enableboolean
Defaults to true.
- Default true
shipping_taxableboolean
Tax shipping too. Defaults to true.
- Default true

Example request

curl

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

200Successful response.

dataobjectrequired
Child fields (18)
- apply_before_discbooleanrequired
  Whether tax is calculated before the discount (Calculate Taxes Before Discount). Normally false: tax comes after the discount.
- defaultbooleanrequired
  Whether it is the team's default tax preset. At most one preset is the default.
- enablebooleanrequired
- idstringrequired
- line_taxesarray of objectsrequired
  The parts of a line_tax preset, as they were sent. Empty for the others.
  Fields of each item (2)
  - namestringrequired
    The part's name, such as State or County.
  - totalintegerrequired
    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
- namestringrequired
- secondary_typestring | nullrequired
  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_taxablebooleanrequired
  Whether shipping is taxed (Tax Shipping).
- totalintegerrequired
  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
- trashedbooleanrequired
  True for a deleted preset. Restore it with Restore a tax preset.
- typestringrequired
  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_ratesboolean
- can_override_rulesboolean
- errorstring
- hiddenboolean
- override_ratesarray of objects
- override_rulesarray of objects
- supported_placearray of objects
statusintegerrequired
successbooleanrequired

Errors

401The 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.
403You 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.
404Not 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.
422The 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%).

GETList tax presets/v1/api/store/{team_slug}/setting/tax_type
PATCHUpdate a tax preset (same as PUT)/v1/api/store/{team_slug}/setting/tax_type/{hash_id}

Example request: Single Line Tax

curl

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"  }'

curl

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"  }'

Example response 200

{
  "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
}

AI agents: read /llms.txt; add .md to any page URL for its Markdown. Guides and concepts in one file: /llms-full.txt.

Download the OpenAPI spec Support: support@yoprint.com yoprint.com

Create a tax preset

Permission

Business rules

Side effects

Path parameters

Request body

Single Line Tax

Multi Line Tax

Response

Errors

Related