Tax report type
Review the Tax report schema and parameters.
The Tax report returns data related to the tax calculated and charged for your transactions, including information about the tax codes used.
Parameters and schema
The following tables define the required and optional parameters to run the report, as well as the schema of the CSV output.
| Report type | Required run parameters | Optional run parameters |
|---|---|---|
tax.itemized_export.1 Columns | interval_start interval_end | timezone decimal_separator country states taxable is_eu_vat_moss tax_type jurisdiction_key type columns |
tax.summarized_export.1 Columns | interval_start interval_end | currency timezone decimal_separator type country states columns |
tax.transactions.itemized.2 Columns | interval_start interval_end | timezone decimal_separator columns |
Itemized tax transactions
API report type: tax.itemized_export.1
| Column name | Default | Description |
|---|---|---|
| applied_tax_calculation_type | The approach used to arrive at tax amounts for this transaction. Possible values are automatic for Stripe integrated tax calculation and external for amounts supplied directly by the user and imported into Stripe. | |
| country_code | The country of the jurisdiction where tax was imposed. This is a two-letter ISO 3166-1 alpha-2 code that represents the line item’s origin country for origin-based tax collection or the item’s destination country for destination-based tax collection. | |
| credit_note_metadata[key] | Metadata from the Credit Note object. Each selected key appears as a separate column named credit_note_metadata[key]. | |
| currency | The three-letter ISO 4217 code for the currency in which amounts are defined. This is the integration currency, which can differ from both the settlement currency and the tax authority’s local filing currency. | |
| customer_email | The customer’s current email address, only available when customer_id is present. | |
| customer_id | The ID of the customer record associated with the transaction. | |
| customer_name | The customer’s current full name or business name, only available when customer_id is present. | |
| customer_tax_id | The customer’s tax IDs associated with the tax transaction. | |
| customer_taxability_override | The customer’s tax status used for taxability of the tax transaction. | |
| destination_resolved_address_city | The city, district, suburb, town, or village of the customer’s address as determined by Stripe Tax using available customer details. | |
| destination_resolved_address_country | The country of the customer’s address as determined by Stripe Tax using available customer details. This is a two-letter ISO 3166-1 alpha-2 code. | |
| destination_resolved_address_line1 | The line 1 of the customer’s address as determined by Stripe Tax using available customer details (for example, street, PO Box, or company name). | |
| destination_resolved_address_line2 | The line 2 of the customer’s address as determined by Stripe Tax using available customer details (for example, apartment, suite, unit, or building). | |
| destination_resolved_address_postal_code | The ZIP or postal code of the customer’s address as determined by Stripe Tax using available customer details. | |
| destination_resolved_address_state | The state, county, province, or region of the customer’s address as determined by Stripe Tax using available customer details. This is an ISO 3166-2 code without the country prefix. | |
| determination_method | The method used to determine jurisdiction-level amounts and taxability. Possible values are engine_calculated for amounts and taxability calculated by a tax engine and mapped to each jurisdiction, back_calculated for amounts back calculated and taxability determined from the imported tax amount, and proportional_calculated for amounts and taxability allocated proportionally across jurisdictions. | |
| effective_at_utc | The time at which the tax transaction was created, in UTC. Format: the related setting-MM-DD HH:mm:ss. | |
| filing_currency | The three-letter ISO 4217 code for the local currency used by the applicable tax authority. Filing amounts are expressed in this currency. This value may be empty for taxability_reason values of not_supported, not_subject_to_tax, and not_collecting. | |
| filing_exchange_rate | The exchange rate used to convert currency to the tax authority’s local filing currency. This value isn’t guaranteed to be set for taxability_reason values of not_supported, not_subject_to_tax, and not_collecting. | |
| filing_non_taxable_amount | The amount of the line item that is non-taxable, expressed in the tax authority’s local filing currency. This is empty when filing_currency is empty. | |
| filing_tax_amount | The amount of tax calculated for the line item, expressed in the tax authority’s local filing currency. This is empty when filing_currency is empty. | |
| filing_taxable_amount | The amount of the line item that is taxable, expressed in the tax authority’s local filing currency. This is empty when filing_currency is empty. | |
| gross_amount | The gross amount exclusive of tax. | |
| id | The container identifier. This ID represents the object that triggered the creation of the tax transaction. | |
| invoice_id | The ID of the invoice associated with the tax transaction. | |
| invoice_metadata[key] | Metadata from the Invoice object. Each selected key appears as a separate column named invoice_metadata[key]. | |
| invoice_number | A unique, identifying string that appears on emails sent to the customer for the invoice, only available when invoice_id is present. | |
| jurisdiction_level | The level of the jurisdiction that imposed the tax. Possible values are country, state, county, city, and district. | |
| jurisdiction_name | The name of the jurisdiction that imposed the tax. | |
| line_item_id | The ID of the line item associated with the tax transaction line item (for example, an invoice line item ID when the tax transaction type is invoice). | |
| non_taxable_amount | The amount of the line item that is considered non-taxable. | |
| origin_resolved_address_city | The city, district, suburb, town, or village of the tax transaction’s origin address as determined by Stripe Tax. | |
| origin_resolved_address_country | The country of the tax transaction’s origin address as determined by Stripe Tax. This is a two-letter ISO 3166-1 alpha-2 code. | |
| origin_resolved_address_line1 | The line 1 of the tax transaction’s origin address as determined by Stripe Tax (for example, street, PO Box, or company name). | |
| origin_resolved_address_line2 | The line 2 of the tax transaction’s origin address as determined by Stripe Tax (for example, apartment, suite, unit, or building). | |
| origin_resolved_address_postal_code | The ZIP or postal code of the tax transaction’s origin address as determined by Stripe Tax. | |
| origin_resolved_address_state | The state, county, province, or region of the tax transaction’s origin address as determined by Stripe Tax. This is an ISO 3166-2 code without the country prefix. | |
| payment_intent_id | The ID of the Payment Intent associated with the tax transaction. | |
| payment_metadata[key] | Metadata from the Payment Intent object. Each selected key appears as a separate column named payment_metadata[key]. | |
| performance_location_resolved_address_city | The city, district, suburb, town, or village of the tax location address as determined by Stripe Tax. | |
| performance_location_resolved_address_country | The country of the tax location address as determined by Stripe Tax. | |
| performance_location_resolved_address_line1 | The line 1 of the tax location address as determined by Stripe Tax (for example, street, PO Box, or company name). | |
| performance_location_resolved_address_line2 | The line 2 of the tax location address as determined by Stripe Tax (for example, apartment, suite, unit, or building). | |
| performance_location_resolved_address_postal_code | The ZIP or postal code of the tax location address as determined by Stripe Tax. | |
| performance_location_resolved_address_state | The state, county, province, or region of the tax location address as determined by Stripe Tax. | |
| product_id | The ID of the product associated with the transaction line item. | |
| product_name | The current name of the product associated with the transaction line item, only available when product_id is present. | |
| provider | The origin of the tax transaction. This will be stripe for Stripe transactions or the platform specified in an import for third-party transactions. | |
| quantity_decimal | The number of units being purchased or reversed when the transaction_type is reversal. | |
| refund_metadata[key] | Metadata from the Refund object. Each selected key appears as a separate column named refund_metadata[key]. | |
| reversal_original_tax_transaction_id | The ID of the original tax transaction that was reversed when transaction_type is reversal. | |
| state_code | The state, county, province, or region of the jurisdiction where tax was imposed. This is an ISO 3166-2 code without the country prefix that represents the line item’s origin state for origin-based tax collection or destination state for destination-based tax collection. This value isn’t guaranteed to be set when jurisdiction_level is country. | |
| subtotal | The line item subtotal amount. This includes taxes when tax_behavior is inclusive. | |
| tax_amount | The amount of tax calculated for the applicable jurisdiction. | |
| tax_behavior | Taxes are included in subtotal when tax_behavior is inclusive and excluded from subtotal when tax_behavior is exclusive. Possible values are inclusive and exclusive. | |
| tax_code | The product tax code associated with the tax transaction line item. | |
| tax_date | The time used to determine the tax rules and rates, in the requested timezone. Format: the related setting-MM-DD HH:mm:ss. | |
| tax_date_utc | The time used to determine the tax rules and rates, in UTC. Format: the related setting-MM-DD HH:mm:ss. | |
| tax_name | A human-readable name of the imposed tax. | |
| tax_rate | The tax rate percentage as a decimal (for example, 0.08 for 8%). Rounded to 6 decimal places. | |
| tax_transaction_id | The unique identifier for the tax transaction. | |
| tax_transaction_metadata[key] | Metadata from the Tax Transaction object. Each selected key appears as a separate column named tax_transaction_metadata[key]. | |
| tax_type | The type of imposed tax. Possible values include sales_tax, use_tax, vat, gst, pst, hst, qst, ct, sst, rst, jct, igst, lease_tax, communications_tax, amusement_tax, service_tax, gross_receipts_communications_tax, and service_communications_tax. This value isn’t guaranteed to be set for taxability_reason values of not_collecting, not_subject_to_tax, reverse_charge, or not_supported. | |
| taxability | Indicates whether the line item is taxable in the applicable jurisdiction. Possible values are taxable and nontaxable. | |
| taxability_reason | The reason for the taxability in the applicable jurisdiction. Possible values include customer_exempt, not_collecting, not_subject_to_tax, jurisdiction_unsupported, not_supported, product_exempt, product_exempt_holiday, reduced_rated, standard_rated, reverse_charge, zero_rated, taxable_basis_reduced, portion_standard_rated, portion_reduced_rated, portion_product_exempt, proportionally_rated, and merchant_override_nontaxable. | |
| taxable_amount | The amount of the line item that is considered taxable. | |
| total | The line item total amount inclusive of tax. | |
| transaction_date | The time at which the tax liability is assumed or reduced, in the requested timezone. Format: the related setting-MM-DD HH:mm:ss. | |
| transaction_date_utc | The time at which the tax liability is assumed or reduced, in UTC. Format: the related setting-MM-DD HH:mm:ss. | |
| transaction_type | The type of tax transaction. The transaction reverses an earlier transaction when transaction_type is reversal. Possible values are transaction and reversal. | |
| type | The type of object that triggered the creation of the tax transaction. Possible values are checkout, credit_note, external, invoice, payment_intent, and refund. |
Summarized tax transactions
API report type: tax.summarized_export.1
| Column name | Default | Description |
|---|---|---|
| country_code | The country of the jurisdiction where tax was imposed. This is a two-letter ISO 3166-1 alpha-2 code that represents the line item’s origin country for origin-based tax collection or the item’s destination country for destination-based tax collection. | |
| filing_currency | The three-letter ISO 4217 code for the local currency used by the applicable tax authority. Filing amounts are expressed in this currency. | |
| filing_tax_payable | The net tax liability (tax collected minus tax refunded) expressed in the tax authority’s local filing currency. This represents the amount owed to or refundable from the tax authority. | |
| filing_total_nontaxable_sales | The sum of non-taxable amounts expressed in the tax authority’s local filing currency. This represents the portion of sales that were not subject to tax. Aggregates transaction transactions only. | |
| filing_total_sales | The sum of sales amounts excluding tax expressed in the tax authority’s local filing currency. This represents the total gross sales for the jurisdiction in the filing currency. Aggregates transaction transactions only. | |
| filing_total_sales_refunded | The sum of refund amounts excluding tax expressed in the tax authority’s local filing currency. This represents the total amount refunded to customers, not including the tax portion. Aggregates reversal transactions only. | |
| filing_total_tax_collected | The sum of tax amounts collected expressed in the tax authority’s local filing currency. This represents the total tax liability before refunds. Aggregates transaction transactions only. | |
| filing_total_tax_refunded | The sum of tax amounts refunded expressed in the tax authority’s local filing currency. This represents the total tax portion of refunds. Aggregates reversal transactions only. | |
| filing_total_taxable_refunded | The sum of taxable refund amounts expressed in the tax authority’s local filing currency. This represents the taxable portion of refunds. Aggregates reversal transactions only. | |
| filing_total_taxable_sales | The sum of taxable amounts expressed in the tax authority’s local filing currency. This represents the portion of sales that were subject to tax. Aggregates transaction transactions only. | |
| jurisdiction_level | The level of the jurisdiction that imposed the tax. Possible values are country, state, county, city, and district. Transactions are grouped by jurisdiction level for aggregation. | |
| jurisdiction_name | The name of the jurisdiction that imposed the tax. Transactions are grouped by jurisdiction for aggregation. | |
| state_code | The state, county, province, or region of the jurisdiction where tax was imposed. This is an ISO 3166-2 code without the country prefix that represents the line item’s origin state for origin-based tax collection or destination state for destination-based tax collection. This value isn’t guaranteed to be set when jurisdiction_level is country. | |
| tax_rate | The tax rate percentage as a decimal (for example, 0.08 for 8%). Rounded to 6 decimal places. | |
| total | The sum of sales transaction amounts including tax. This represents the total amount charged to customers. Aggregates transaction transactions only. | |
| total_nontaxable_sales | The sum of non-taxable amounts. This represents the portion of sales that were not subject to tax. Aggregates transaction transactions only. | |
| total_sales | The sum of sales amounts excluding tax. This represents the total gross sales for the jurisdiction. Aggregates transaction transactions only. | |
| total_sales_refunded | The sum of refund amounts excluding tax. This represents the total amount refunded to customers, not including the tax portion. Aggregates reversal transactions only. | |
| total_tax_collected | The sum of tax amounts collected. This represents the total tax liability before refunds. Aggregates transaction transactions only. | |
| total_tax_refunded | The sum of tax amounts refunded. This represents the total tax portion of refunds. Aggregates reversal transactions only. | |
| total_taxable_sales | The sum of taxable amounts. This represents the portion of sales that were subject to tax. Aggregates transaction transactions only. | |
| transaction_currency | The three-letter ISO 4217 code for the currency in which amounts are defined. This is the integration currency, which can differ from both the settlement currency and the tax authority’s local filing currency. | |
| transaction_date_end | The end of the date range for tax transactions included in this aggregation, in the requested timezone. Format: the related setting-MM-DD HH:mm:ss. | |
| transaction_date_end_utc | The end of the date range for tax transactions included in this aggregation, in UTC. Format: the related setting-MM-DD HH:mm:ss. | |
| transaction_date_start | The start of the date range for tax transactions included in this aggregation, in the requested timezone. Format: the related setting-MM-DD HH:mm:ss. | |
| transaction_date_start_utc | The start of the date range for tax transactions included in this aggregation, in UTC. Format: the related setting-MM-DD HH:mm:ss. |
Connect platform itemized tax transactions
API report type: tax.transactions.itemized.2
| Column name | Default | Description |
|---|---|---|
| country_code | Two-letter ISO code representing the situs country. | |
| credit_note_metadata[key] | Metadata associated with a Credit Note object | |
| currency | Transaction currency presented to the buyer. | |
| customer_tax_id | List of tax ID type-value pairs for the customer. | |
| destination_resolved_address_country | Two-letter ISO code representing the customer country. | |
| destination_resolved_address_state | Two-letter ISO code representing the customer country subdivision. | |
| filing_currency | Filing currency for applicable registration jurisdiction. | |
| filing_exchange_rate | Filing exchange rate used. | |
| filing_non_taxable_amount | Non-taxable amount in filing currency. | |
| filing_tax_amount | Tax amount in filing currency. | |
| filing_taxable_amount | Taxable amount in filing currency. | |
| filing_total | Taxable amount plus tax or non-taxable amount in filing currency. | |
| id | Unique ID for the tax transaction. A transaction is identified by reference to an invoice, checkout session, credit note, subscription, or order. | |
| invoice_metadata[key] | Metadata associated with an Invoice object | |
| jurisdiction_level | Jurisdiction level imposing the tax. | |
| jurisdiction_name | Imposing tax jurisdiction name. | |
| line_item_id | Unique ID for the line item associated with the tax transaction. Multiple sales taxes rates may be applied to a single line item, so you may see several rows with the same line item ID. | |
| non_taxable_amount | Non-taxable amount in the transaction currency. | |
| origin_resolved_address_country | Two-letter ISO code representing the merchant country. | |
| origin_resolved_address_state | Two-letter ISO code representing the merchant country subdivision. | |
| quantity | Units sold as per the invoice. | |
| quantity_decimal | Units sold as per the invoice expressed in decimal. | |
| refund_metadata[key] | Metadata associated with a Refund object | |
| state_code | Two-letter ISO code representing the situs country subdivision. | |
| subtotal | Taxable or non-taxable amount. | |
| tax_amount | Tax amount in the transaction currency. | |
| tax_code | Unique ID for the product tax code assigned to the line item. | |
| tax_date | Date used to determine the tax rules and rates. It is usually the same date as the transaction date; however, it can be different in the context of refunds. When a credit note is issued, the transaction_date is the date on which the credit note is issued, but the tax_date is the date when tax was calculated on the original transaction. | |
| tax_name | Local name of the applicable tax. | |
| tax_rate | Tax rate applied to the line item. | |
| tax_transaction_metadata[key] | Metadata associated with a Tax Transaction object | |
| taxability | Indicates whether a line item is taxable or non_taxable. | |
| taxability_reason | Reason for tax collection or non-collection. | |
| taxable_amount | Taxable amount in the transaction currency. | |
| total | Taxable amount plus tax or the non-taxable amount. | |
| transaction_date | Date when the transaction is committed in the requested timezone. | |
| type | This refers to how a transaction is processed by Stripe. Possible values are: invoice, checkout, payment_link, payment_intent, order, refund, credit_note. |
API key permissions
To request Tax reports using a restricted API key, your key must have the Tax Transaction Reports permission. This permission allows your key to create and retrieve Tax report runs. Navigate to the API keys page in the Dashboard to view and manage permissions for your restricted keys.