# Query tax data

Use Sigma or Data Pipeline to retrieve tax information.

Stripe Tax data includes various components that work together to provide a comprehensive view of your tax liability through automated calculations with [Payment Links](https://docs.stripe.com/tax/payment-links.md), [Checkout](https://docs.stripe.com/tax/checkout.md), [Subscriptions](https://docs.stripe.com/tax/subscriptions.md), [Invoices](https://docs.stripe.com/tax/invoicing.md), [Custom integrations](https://docs.stripe.com/tax/custom.md) and [as a platform](https://docs.stripe.com/tax/connect.md). All tax-specific data is available in the **Tax** section of the schema, and the primary table is `tax_transactions`.

To explore tax data further, you can use additional tables that represent the components of a `tax_transaction`, such as `tax_transaction_line_items`, `tax_transaction_shipping_costs`, and `tax_transaction_jurisdiction_details`.

This diagram represents all components created during an automated tax calculation and how it relates to the original object that triggered calculation. Amounts in the examples below appear in minor [currency](https://docs.stripe.com/currencies.md) units (for example, cents instead of dollars).
 (See full diagram at https://docs.stripe.com/stripe-data/query-tax-data)
## Tax transactions

Each row in the `tax_transactions` table represents a single [tax_transaction](https://docs.stripe.com/api/tax/transactions/object.md) object. Tax transactions record the assumed or reduced tax liability for a transaction or reversal. You can report on every tax transaction created with automated tax calculations.

This table is our recommended starting point for creating reports on your tax liability. You need to join on the other tax tables below for your tax liability amounts, but this table joins your data to other products like invoices and checkout sessions. Joining to non-tax tables by `source_id` and `source_type` provides the object that triggers the creation of the tax transaction.

Tax transactions have a one-to-one relationship with their original source object. The following example retrieves a list of reportable tax transactions with their original source of invoices, which you can then expand on with [query billing data](https://docs.stripe.com/stripe-data/query-billing-data.md).

```sql
select
  tx.id as tax_transaction_id,
  tx.posted_at as tax_transaction_posted_at,
  inv.id as invoice_id,
  inv.total as invoice_total
from
  tax_transactions tx
  inner join invoices inv on inv.id = tx.source_id
limit
  5
```

| tax_transaction_id  | tax_transaction_posted_at | invoice_id         | invoice_total |
| ------------------- | ------------------------- | ------------------ | ------------- |
| tax_orWziM4j7CiRL8J | 2024-06-18 16:40:16 +0000 | in_orWziM4j7CiRL8J | 20,000        |
| tax_orWziM4j7CiRL8J | 2021-06-28 00:01:21 +0000 | in_orWziM4j7CiRL8J | 189           |
| tax_orWziM4j7CiRL8J | 2024-06-23 23:35:40 +0000 | in_orWziM4j7CiRL8J | 219           |
| tax_orWziM4j7CiRL8J | 2024-06-23 23:35:40 +0000 | in_orWziM4j7CiRL8J | 10,475        |
| tax_orWziM4j7CiRL8J | 2023-07-23 04:03:06 +0000 | in_orWziM4j7CiRL8J | 200           |

### Tax transactions metadata

Tax transactions might have metadata set with your [custom integrations](https://docs.stripe.com/tax/custom.md). Each row in `tax_transactions_metadata` returns one key-value pair.
Tax Transactions Metadata overview (See full diagram at https://docs.stripe.com/stripe-data/query-tax-data)
## Tax transaction items

Tax line items and tax shipping costs make up the total amounts and tax liability for tax transactions. Tax line items and tax shipping costs are in their own tables, but they both contribute to amounts and total tax liability.

### Tax line items

Tax line items represent line items that contribute to the sale of goods for the transaction. Each row in `tax_transaction_line_items` represents a single tax line item associated to the `tax_transaction`.

### Tax shipping costs

Tax shipping costs represent shipping items that contribute to the shipment of goods for the transaction. Each row in `tax_transaction_shipping_costs` represents a single shipping cost associated to the `tax_transaction`.

> These tables provide high level information based on each item. A single tax transaction can have multiple line items and one shipping cost which make up the amounts for a tax transaction.
> 
> **amount**: This is the gross amount of the line item. When `tax_behavior` is `inclusive`, it includes tax liability amounts. When `tax_behavior` is `exclusive` (the default), it excludes tax liability amounts.
> 
> **amount\_tax**: This is the amount of tax liability for the line item.
> 
> **currency**: This is the [presentment currency](https://docs.stripe.com/currencies.md) that defines `amount` and `amount_tax`. Summing across different currencies yields unexpected results.
Tax Transaction Items Overview (See full diagram at https://docs.stripe.com/stripe-data/query-tax-data)
The following example retrieves a list of all amounts and tax liability for a given `tax_transaction`.

```sql
with tax_amounts as (
  select
    li.tax_transaction_id,
    li.id,
    li.amount,
    li.amount_tax,
    li.tax_behavior,
    li.currency,
    'line_item' as item_type
  from
    tax_transaction_line_items li
  union all
  select
    sc.tax_transaction_id,
    sc.id,
    sc.amount,
    sc.amount_tax,
    sc.tax_behavior,
    sc.currency,
    'shipping_cost' as item_type
  from
    tax_transaction_shipping_costs sc
)
select
  id,
  amount,
  amount_tax,
  tax_behavior,
  currency,
  item_type
from
  tax_amounts
where
  tax_transaction_id = 'tax_d2e5470dC63u'
```

| id                     | amount | amount_tax | tax_behavior | currency | item_type     |
| ---------------------- | ------ | ---------- | ------------ | -------- | ------------- |
| tax_li_orWziM4j7CiRL8J | 3,100  | 0          | exclusive    | usd      | line_item     |
| tax_li_orWziM4j7CiRL8J | 1,999  | 190        | exclusive    | usd      | line_item     |
| tax_li_orWziM4j7CiRL8J | 3,500  | 304        | inclusive    | usd      | line_item     |
| tax_li_orWziM4j7CiRL8J | 4,242  | 242        | exclusive    | usd      | line_item     |
| tax_li_orWziM4j7CiRL8J | 799    | 0          | exclusive    | usd      | shipping_cost |

### Tax transaction line items metadata

Tax transaction line items might have metadata set with your [custom integrations](https://docs.stripe.com/tax/custom.md). Each row in `tax_transaction_line_items_metadata` returns one key-value pair.
Tax Transactions Metadata (See full diagram at https://docs.stripe.com/stripe-data/query-tax-data)
## Tax transaction jurisdiction details

Each row in the `tax_transaction_jurisdiction_details` table represents a jurisdiction which makes up the liability for the tax transaction item (`tax_transaction_line_item` or `tax_transaction_shipping_cost`).

### Understanding jurisdiction details

This table provides more in-depth information based on each jurisdiction. A single tax transaction item can have multiple jurisdictions which make up the amounts for a tax transaction item.

Summing `amount_taxable` or `amount_non_taxable` across all jurisdiction details doesn’t always equal the tax transaction item’s `amount`.

**amount\_taxable**: This is the amount up to the tax transaction item’s `amount` that is taxable. Multiple jurisdictions can have the same taxable amount.

**amount\_non\_taxable**: This is the amount up to the tax transaction item `amount` that is non-taxable. Multiple jurisdictions can have the same non-taxable amount.

**amount\_tax**: This is part of the tax transaction item `amount_tax`. Summing this across all jurisdiction details equals the transaction item’s `amount_tax`.

**currency**: This is the [presentment currency](https://docs.stripe.com/currencies.md) that defines `amount_taxable`, `amount_non_taxable` and `amount_tax`. Summing across different currencies yields unexpected results.

**filing\_currency**: This is the [filing currency](https://docs.stripe.com/currencies.md) used by the applicable tax authority which defines `filing_amount_taxable`, `filing_amount_non_taxable` and `filing_amount_tax`. Summing across different filing currencies yields unexpected results.
 (See full diagram at https://docs.stripe.com/stripe-data/query-tax-data)
The following example retrieves all jurisdiction details for a given tax transaction item.

```sql
select
  jd.amount_taxable,
  jd.amount_non_taxable,
  jd.amount_tax,
  jd.taxability_reason,
  jd.jurisdiction_level,
  jd.jurisdiction_name,
  concat(jd.jurisdiction_country, '-', jd.jurisdiction_state) as jurisdiction_location
from
  tax_transaction_jurisdiction_details jd
where
  li.id = 'tax_li_52d37cdd6f7'
```

| amount_taxable | amount_non_taxable | amount_tax | taxability_reason  | jurisdiction_level | jurisdiction_name                         | jurisdiction_location |
| -------------- | ------------------ | ---------- | ------------------ | ------------------ | ----------------------------------------- | --------------------- |
| 0              | 1,299              | 0          | not_subject_to_tax | country            | United States                             |                       |
| 1,299          | 0                  | 77         | standard_rated     | state              | California                                | US-CA                 |
| 1,299          | 0                  | 16         | standard_rated     | county             | San Diego                                 | US-CA                 |
| 1,299          | 0                  | 7          | standard_rated     | district           | Transactions and Use Tax (CLVT)           | US-CA                 |
| 1,299          | 0                  | 7          | standard_rated     | district           | Transactions and Use Tax (CVGT)           | US-CA                 |
| 1,299          | 0                  | 7          | standard_rated     | district           | Regional Transportation Commission (SDCT) | US-CA                 |

## Example queries

For additional examples, please reference the [Tax section of query template library in Sigma sidebar](https://dashboard.stripe.com/sigma/queries).

### Tax liability by month

This example summarizes the tax liability imposed on line items and shipping costs grouped by month and [currency](https://docs.stripe.com/currencies.md).

```sql
with tax_amounts as (
  select
    li.tax_transaction_id,
    li.amount,
    li.amount_tax,
    li.tax_behavior,
    li.currency
  from
    tax_transaction_line_items li
  union all
  select
    sc.tax_transaction_id,
    sc.amount,
    sc.amount_tax,
    sc.tax_behavior,
    sc.currency
  from
    tax_transaction_shipping_costs sc
),
tax_liability as (
  select
    date_format(date_trunc('month', posted_at), '%Y-%m-%d') as month,
    currency as presentment_currency,
    sum(
      (
        case
          when tax_behavior = 'inclusive' then amount - amount_tax
          else amount
        end
      )
    ) as total_sales_excluding_tax,
    sum(amount_tax) as total_tax
  from
    tax_amounts ta
    inner join tax_transactions t on (ta.tax_transaction_id = t.id)
  group by
    1,
    2
)
select
  month,
  presentment_currency,
  total_sales_excluding_tax,
  total_tax
from
  tax_liability
order by
  1 desc,
  2
```

| month      | presentment_currency | total_sales_excluding_tax | total_tax |
| ---------- | -------------------- | ------------------------- | --------- |
| 2026-04-01 | usd                  | 286,600                   | 43,522    |
| 2026-04-01 | eur                  | 30,898                    | 56        |
| 2026-03-01 | usd                  | 79,776                    | 2,565     |
| 2026-03-01 | eur                  | 55,434                    | 3,954     |

### Tax itemized jurisdiction details

This template itemizes tax transaction jurisdiction details for the previous month to produce a customizable version of the [Tax itemized export](https://docs.stripe.com/tax/reports.md#itemized-exports). Review the comments throughout the template to learn more about how it’s customizable for your needs.

```sql
with tax_amounts as (
  select
    li.id,
    li.source_line_item_id,
    li.amount,
    li.amount_tax,
    li.tax_behavior,
    li.tax_code,
    li.currency,
    li.quantity_decimal
  from
    tax_transaction_line_items li
  union all
  select
    sc.id,
    -- Shipping costs do not have source line item IDs
    '' as source_line_item_id,
    sc.amount,
    sc.amount_tax,
    sc.tax_behavior,
    sc.tax_code,
    sc.currency,
    -- Shipping costs do not have a quantity
    '' as quantity_decimal
  from
    tax_transaction_shipping_costs sc
)
select
  t.source_id,
  t.source_type,
  -- Learn more about currencies at Stripe: https://docs.stripe.com/currencies
  tx.currency as presentment_currency,
  t.posted_at,
  t.tax_date,
  tx.source_line_item_id as transaction_source_item_id,
  tx.id as transaction_item_id,
  tx.amount,
  tx.amount_tax,
  tx.tax_behavior,
  tx.tax_code,
  tjd.jurisdiction_name,
  tjd.jurisdiction_level,
  tjd.jurisdiction_country,
  tjd.jurisdiction_state,
  tjd.taxability,
  tx.quantity_decimal,
  tjd.tax_type,
  tjd.amount_tax as jurisdiction_amount_tax,
  tjd.amount_taxable as jurisdiction_amount_taxable,
  tjd.amount_non_taxable as jurisdiction_amount_non_taxable,
  tjd.filing_currency,
  tjd.filing_amount_tax as jurisdiction_filing_amount_tax,
  tjd.filing_amount_taxable as jurisdiction_filing_amount_taxable,
  tjd.filing_amount_non_taxable as jurisdiction_filing_amount_non_taxable,
  tjd.tax_transaction_item_type,
  tjd.tax_rate_percentage
from
  tax_transaction_jurisdiction_details tjd
  inner join tax_transactions t on tjd.tax_transaction_id = t.id
  inner join tax_amounts tx on TJD.tax_transaction_item_id = tx.id
where
  -- Exclude country level jurisdiction details for the US
  -- to be consistent with the Tax itemized export. The excluded
  -- details will always be non-taxable because the US doesn't
  -- have a country level tax.
  not (
    tjd.jurisdiction_level = 'country'
    and tjd.jurisdiction_country = 'US'
  )
  -- Adjust this date range to report on a period other than the previous month.
  and (
    t.posted_at >= date_trunc('month', current_date - interval '1' month)
    and t.posted_at < date_trunc('month', current_date)
  )
  -- Uncomment and adjust to filter results by specific jurisdiction countries.
  -- and tjd.jurisdiction_country in ('CA')
  -- Uncomment and adjust to filter results by specific jurisdiction states.
  -- and tjd.jurisdiction_state in ('AB', 'QC')
order by
  t.posted_at desc,
  t.source_id,
  tx.source_line_item_id,
  tjd.tax_rate_percentage desc,
  tjd.jurisdiction_level,
  tjd.jurisdiction_name
```

| source_id          | source_type | presentment_currency | posted_at  | tax_date,  | transaction_source_item_id | transaction_item_id    | amount | amount_tax | tax_behavior | tax_code      | jurisdiction_name | jurisdiction_level | … |
| ------------------ | ----------- | -------------------- | ---------- | ---------- | -------------------------- | ---------------------- | ------ | ---------- | ------------ | ------------- | ----------------- | ------------------ | - |
| in_orWziM4j7CiRL8J | invoice     | eur                  | 2026-04-05 | 2026-04-05 | il_orWziM4j7CiRL8J         | tax_il_orWziM4j7CiRL8J | -199   | -20        | exclusive    | txcd_99999999 | Ireland           | country            | … |
| in_orWziM4j7CiRL8J | invoice     | usd                  | 2026-04-05 | 2026-04-05 | il_orWziM4j7CiRL8J         | tax_il_orWziM4j7CiRL8J | 10,000 | 1,000      | exclusive    | txcd_99999999 | Rhode Island      | state              | … |
| in_orWziM4j7CiRL8J | invoice     | usd                  | 2026-03-27 | 2026-03-27 | il_orWziM4j7CiRL8J         | tax_il_orWziM4j7CiRL8J | 2,999  | 371        | exclusive    | txcd_99999999 | Fire District 17  | district           | … |