Tax

Preview tax for a cart before checkout

Estimates the tax for a shipping destination and a set of cart lines without creating an order, so a storefront can show the shopper the final, tax-inclusive total before they pay.

When the store has automatic tax enabled, the response is calculated for the ship_to address and includes a per-jurisdiction breakdown. When automatic tax is not configured, the response is { "tax_source": "fallback" } and you should apply the store’s own tax rate (the same amount the order endpoint would use). The estimate is never recorded for filing — it is a quote only.

Publishable keys are accepted, so the call can be made directly from the browser during checkout. Use the returned tax_amount to compute total_amount (subtotal + tax_amount + shipping − discount) and pass that same total to createOrder.

POST

tax

preview

Preview tax for a cart before checkout

curl --request POST \
  --url https://api.tybritelabs.com/v1/tax/preview \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "ship_to": {
    "line1": "350 Fifth Avenue",
    "city": "New York",
    "region": "NY",
    "country": "US",
    "postal_code": "10118"
  },
  "lines": [
    {
      "quantity": 2,
      "amount": 598,
      "item_code": "SAM-WATCH-6",
      "category_name": "Wearables"
    }
  ],
  "currency": "USD"
}
'

import requests

url = "https://api.tybritelabs.com/v1/tax/preview"

payload = {
    "ship_to": {
        "line1": "350 Fifth Avenue",
        "city": "New York",
        "region": "NY",
        "country": "US",
        "postal_code": "10118"
    },
    "lines": [
        {
            "quantity": 2,
            "amount": 598,
            "item_code": "SAM-WATCH-6",
            "category_name": "Wearables"
        }
    ],
    "currency": "USD"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    ship_to: {
      line1: '350 Fifth Avenue',
      city: 'New York',
      region: 'NY',
      country: 'US',
      postal_code: '10118'
    },
    lines: [
      {quantity: 2, amount: 598, item_code: 'SAM-WATCH-6', category_name: 'Wearables'}
    ],
    currency: 'USD'
  })
};

fetch('https://api.tybritelabs.com/v1/tax/preview', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.tybritelabs.com/v1/tax/preview",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'ship_to' => [
        'line1' => '350 Fifth Avenue',
        'city' => 'New York',
        'region' => 'NY',
        'country' => 'US',
        'postal_code' => '10118'
    ],
    'lines' => [
        [
                'quantity' => 2,
                'amount' => 598,
                'item_code' => 'SAM-WATCH-6',
                'category_name' => 'Wearables'
        ]
    ],
    'currency' => 'USD'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.tybritelabs.com/v1/tax/preview"

	payload := strings.NewReader("{\n  \"ship_to\": {\n    \"line1\": \"350 Fifth Avenue\",\n    \"city\": \"New York\",\n    \"region\": \"NY\",\n    \"country\": \"US\",\n    \"postal_code\": \"10118\"\n  },\n  \"lines\": [\n    {\n      \"quantity\": 2,\n      \"amount\": 598,\n      \"item_code\": \"SAM-WATCH-6\",\n      \"category_name\": \"Wearables\"\n    }\n  ],\n  \"currency\": \"USD\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.tybritelabs.com/v1/tax/preview")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"ship_to\": {\n    \"line1\": \"350 Fifth Avenue\",\n    \"city\": \"New York\",\n    \"region\": \"NY\",\n    \"country\": \"US\",\n    \"postal_code\": \"10118\"\n  },\n  \"lines\": [\n    {\n      \"quantity\": 2,\n      \"amount\": 598,\n      \"item_code\": \"SAM-WATCH-6\",\n      \"category_name\": \"Wearables\"\n    }\n  ],\n  \"currency\": \"USD\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.tybritelabs.com/v1/tax/preview")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"ship_to\": {\n    \"line1\": \"350 Fifth Avenue\",\n    \"city\": \"New York\",\n    \"region\": \"NY\",\n    \"country\": \"US\",\n    \"postal_code\": \"10118\"\n  },\n  \"lines\": [\n    {\n      \"quantity\": 2,\n      \"amount\": 598,\n      \"item_code\": \"SAM-WATCH-6\",\n      \"category_name\": \"Wearables\"\n    }\n  ],\n  \"currency\": \"USD\"\n}"

response = http.request(request)
puts response.read_body

{
  "tax_amount": 53.08,
  "taxable": 598,
  "currency": "USD",
  "tax_source": "automatic",
  "breakdown": [
    {
      "country": "US",
      "region": "NY",
      "jurisName": "NEW YORK",
      "taxName": "NY STATE TAX",
      "rate": 0.04,
      "taxable": 598,
      "tax": 23.92
    },
    {
      "country": "US",
      "region": "NY",
      "jurisName": "NEW YORK CITY",
      "taxName": "NY CITY TAX",
      "rate": 0.045,
      "taxable": 598,
      "tax": 26.91
    },
    {
      "country": "US",
      "region": "NY",
      "jurisName": "METROPOLITAN COMMUTER TRANSPORTATION DISTRICT",
      "taxName": "NY SPECIAL TAX",
      "rate": 0.00375,
      "taxable": 598,
      "tax": 2.25
    }
  ]
}

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request parameters",
    "details": "The 'email' field is required"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid Authorization header"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests for this API key. Please slow down and try again shortly.",
    "remaining": 0,
    "reset": 1706198400
  }
}

Authorizations

Authorization

string

header

required

API Key Authentication

Use your API key in the Authorization header:

Authorization: Bearer tybrite_sk_live_YOUR_KEY

Key Types:

Secret Keys (Server-Side Only):

Format: tybrite_sk_live_* (production) or tybrite_sk_test_* (sandbox)
Full read/write access to all endpoints
⚠️ NEVER expose in client-side code or public repositories
Required for: write operations, authentication, payment verification, AI recommendations

Publishable Keys (Client-Safe):

Format: tybrite_pk_live_* (production) or tybrite_pk_test_* (sandbox)
Read-only access (GET requests only, plus POST semantic search)
✅ Safe for client-side JavaScript, mobile apps, and public code
Allowed for: browsing products, search, CMS content, pricing queries

Endpoint-Specific Requirements:

Authentication endpoints (/v1/auth/*): Secret key required
Payment verification (POST /v1/payments/verify): Secret key required
AI Recommendations (POST /v1/recommendations): Secret key required
Semantic Search (POST /v1/search): Both key types allowed (read-only operation)
All write operations: Secret key required
All read operations: Both key types allowed

Using a publishable key for restricted operations returns 403 Forbidden.

Body

application/json

ship_to

object

required

The shipping destination the tax is calculated for.

Show child attributes

lines

object[]

required

The cart lines to estimate tax for.

Show child attributes

ship_from

object

The origin the goods ship from. Which jurisdictions may tax a sale depends on where it ships from as well as where it ships to, so send this when fulfilling from a location other than the store's own address. Defaults to the store's address.

Show child attributes

customer_code

string

Your identifier for the buyer. Send it when the buyer holds a tax exemption, so the estimate reflects it. Omitted, the cart is priced as an ordinary retail sale.

Example:

"CUST-10432"

doc_code

string

Your own reference for this estimate, echoed back so you can tie it to a cart or quote in your system.

Example:

"QUOTE-10432"

currency

string

ISO 4217 currency code. Defaults to the store currency.

Example:

"USD"

Response

The tax estimate. tax_source is fallback when automatic tax is not configured.

tax_amount

number<float>

Example:

53.08

taxable

number<float>

Example:

598

currency

string

Example:

"USD"

tax_source

enum<string>

Available options:

automatic,

fallback

Example:

"automatic"

breakdown

object[]

Per-jurisdiction detail (present when tax_source is automatic).

Show child attributes

Preview tax for a cart before checkout

curl --request POST \
  --url https://api.tybritelabs.com/v1/tax/preview \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "ship_to": {
    "line1": "350 Fifth Avenue",
    "city": "New York",
    "region": "NY",
    "country": "US",
    "postal_code": "10118"
  },
  "lines": [
    {
      "quantity": 2,
      "amount": 598,
      "item_code": "SAM-WATCH-6",
      "category_name": "Wearables"
    }
  ],
  "currency": "USD"
}
'

import requests

url = "https://api.tybritelabs.com/v1/tax/preview"

payload = {
    "ship_to": {
        "line1": "350 Fifth Avenue",
        "city": "New York",
        "region": "NY",
        "country": "US",
        "postal_code": "10118"
    },
    "lines": [
        {
            "quantity": 2,
            "amount": 598,
            "item_code": "SAM-WATCH-6",
            "category_name": "Wearables"
        }
    ],
    "currency": "USD"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    ship_to: {
      line1: '350 Fifth Avenue',
      city: 'New York',
      region: 'NY',
      country: 'US',
      postal_code: '10118'
    },
    lines: [
      {quantity: 2, amount: 598, item_code: 'SAM-WATCH-6', category_name: 'Wearables'}
    ],
    currency: 'USD'
  })
};

fetch('https://api.tybritelabs.com/v1/tax/preview', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.tybritelabs.com/v1/tax/preview",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'ship_to' => [
        'line1' => '350 Fifth Avenue',
        'city' => 'New York',
        'region' => 'NY',
        'country' => 'US',
        'postal_code' => '10118'
    ],
    'lines' => [
        [
                'quantity' => 2,
                'amount' => 598,
                'item_code' => 'SAM-WATCH-6',
                'category_name' => 'Wearables'
        ]
    ],
    'currency' => 'USD'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.tybritelabs.com/v1/tax/preview"

	payload := strings.NewReader("{\n  \"ship_to\": {\n    \"line1\": \"350 Fifth Avenue\",\n    \"city\": \"New York\",\n    \"region\": \"NY\",\n    \"country\": \"US\",\n    \"postal_code\": \"10118\"\n  },\n  \"lines\": [\n    {\n      \"quantity\": 2,\n      \"amount\": 598,\n      \"item_code\": \"SAM-WATCH-6\",\n      \"category_name\": \"Wearables\"\n    }\n  ],\n  \"currency\": \"USD\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.tybritelabs.com/v1/tax/preview")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"ship_to\": {\n    \"line1\": \"350 Fifth Avenue\",\n    \"city\": \"New York\",\n    \"region\": \"NY\",\n    \"country\": \"US\",\n    \"postal_code\": \"10118\"\n  },\n  \"lines\": [\n    {\n      \"quantity\": 2,\n      \"amount\": 598,\n      \"item_code\": \"SAM-WATCH-6\",\n      \"category_name\": \"Wearables\"\n    }\n  ],\n  \"currency\": \"USD\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.tybritelabs.com/v1/tax/preview")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"ship_to\": {\n    \"line1\": \"350 Fifth Avenue\",\n    \"city\": \"New York\",\n    \"region\": \"NY\",\n    \"country\": \"US\",\n    \"postal_code\": \"10118\"\n  },\n  \"lines\": [\n    {\n      \"quantity\": 2,\n      \"amount\": 598,\n      \"item_code\": \"SAM-WATCH-6\",\n      \"category_name\": \"Wearables\"\n    }\n  ],\n  \"currency\": \"USD\"\n}"

response = http.request(request)
puts response.read_body

{
  "tax_amount": 53.08,
  "taxable": 598,
  "currency": "USD",
  "tax_source": "automatic",
  "breakdown": [
    {
      "country": "US",
      "region": "NY",
      "jurisName": "NEW YORK",
      "taxName": "NY STATE TAX",
      "rate": 0.04,
      "taxable": 598,
      "tax": 23.92
    },
    {
      "country": "US",
      "region": "NY",
      "jurisName": "NEW YORK CITY",
      "taxName": "NY CITY TAX",
      "rate": 0.045,
      "taxable": 598,
      "tax": 26.91
    },
    {
      "country": "US",
      "region": "NY",
      "jurisName": "METROPOLITAN COMMUTER TRANSPORTATION DISTRICT",
      "taxName": "NY SPECIAL TAX",
      "rate": 0.00375,
      "taxable": 598,
      "tax": 2.25
    }
  ]
}

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request parameters",
    "details": "The 'email' field is required"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid Authorization header"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests for this API key. Please slow down and try again shortly.",
    "remaining": 0,
    "reset": 1706198400
  }
}

Reference

System

Products

Taxonomy

Orders

Payments

Cart & Wishlist

Marketplace

Recommendations

Discovery

Events

Tax

Analytics

Search

Authentication

Customers

Gift Cards

Promotions

CMS

Pricing

Messaging

Shipping

GC Connect

Reviews

Returns

Disputes

B2B

Webhooks

Ingestion

Sandbox

Preview tax for a cart before checkout

Authorizations

Body

Response