Import transactions into Stripe TaxPublic preview

Import transaction data from third-party platforms into Stripe Tax using CSV files. Consolidate sales data from multiple platforms to get a unified view of your tax obligations, simplify compliance, and make informed decisions about tax registration requirements.

Importing your transaction data from external platforms into Stripe Tax has several benefits:

• Unified tax obligation monitoring: Monitor thresholds for all sales channels, including non-Stripe transactions.
• Simplified compliance: Avoid manual reconciliation and aggregation of data from different platforms.
• More accurate threshold monitoring: Identify where you need to register for tax collection by consolidating transaction data in one place.
• Manage data flexibly: Import historical data for past obligations or maintain regular imports for ongoing monitoring.

How it works

When you import transaction data into Stripe Tax:

1. You export your transaction data from external platforms.
2. You format the data into a CSV file with one row per line item (not per transaction).
3. You upload the CSV file to Stripe Tax through the Dashboard.
4. Stripe Tax validates and processes your data.
5. Access imported transactions in reports, obligations monitoring, and filing and remittance.

CSV file format requirements

Your CSV file must follow a specific format with required columns. Include a header row in each file. Each row represents a line item, not a complete transaction. If a single transaction consists of multiple products or line items, list each line item as a separate row in the CSV file.

Column Reference

Sample CSV file

Example CSV file with multiple line items and a variety of commonly used fields:

source_transaction_id,transaction_type,provider,liable_transaction_id,transaction_version,tax_rules_at,created_at,posted_at,currency,customer_id,tax_exempt,line_item.id,line_item.tax_behavior,line_item.amount,line_item.product_id,line_item.product_name,line_item.product_description,line_item.product_tax_code,line_item.external_product_id,line_item.external_tax_code,line_item.unit_amount,line_item.quantity,line_item.amount_discount,line_item.taxable_amount,line_item.tax_rate,line_item.amount_tax,shipping_line_item.id,shipping_line_item.tax_behavior,shipping_line_item.description,shipping_line_item.tax_code,shipping_line_item.external_tax_code,shipping_line_item.amount,shipping_line_item.amount_discount,shipping_line_item.taxable_amount,shipping_line_item.tax_rate,shipping_line_item.amount_tax,merchant_address.city,merchant_address.country,merchant_address.line1,merchant_address.line2,merchant_address.postal_code,merchant_address.state,tax_ids.type,tax_ids.country,tax_ids.value,buyer_address.city,buyer_address.country,buyer_address.line1,buyer_address.line2,buyer_address.postal_code,buyer_address.state
1935a6-Sale,Sale,tax_jar,,1,2024-06-07 18:07:21 UTC,2024-06-07 18:07:21 UTC,2024-06-07 18:07:21 UTC,USD,cus_9s6XKzkNRiz8i3,none,LineItem-1,inclusive,42.54,,,Pepperoni Pizza,txcd_40060003,tax_product_id_56,tax_code_99,55.05,1,12.51,,,9.67,ShippingLineItem-8ab3,inclusive,Shipping description 69,txcd_92010001,shipping_tax_code_3,10.33,,,,0,San Francisco,US,510 Townsend St,,94103,CA,us_ein,US,12-3456789,Seattle,US,9205th Ave,,98104,WA
8a54a0-Refund,Refund,tax_jar,1935a6-Sale,1,2024-06-07 18:07:21 UTC,2024-06-07 18:07:21 UTC,2024-06-07 18:07:21 UTC,USD,cus_9s6XKzkNRiz8i3,none,LineItem-1,inclusive,-42.54,,,Pepperoni Pizza,txcd_40060003,tax_product_id_56,tax_code_99,-55.05,1,-12.51,,,-9.67,ShippingLineItem-8ab3,inclusive,Shipping description 69,txcd_92010001,shipping_tax_code_3,-10.33,,,,0,San Francisco,US,510 Townsend St,,94103,CA,us_ein,US,12-3456789,Seattle,US,9205th Ave,,98104,WA
1860e6-Sale,Sale,tax_jar,,1,2024-06-07 18:07:21 UTC,2024-06-07 18:07:21 UTC,2024-06-07 18:07:21 UTC,USD,cus_9s6XKzkNRiz8i3,none,LineItem-1,inclusive,172.58,,,Pepperoni Pizza,txcd_40060003,tax_product_id_56,tax_code_99,45.37,4,8.9,,,7.43,ShippingLineItem-e936,inclusive,Shipping description 69,txcd_92010001,shipping_tax_code_3,8.14,,,,0,San Francisco,US,510 Townsend St,,94103,CA,us_ein,US,12-3456789,Seattle,US,9205th Ave,,98104,WA
e7f7a1-Void,Void,tax_jar,1860e6-Sale,1,2024-06-07 18:07:21 UTC,2024-06-07 18:07:21 UTC,2024-06-07 18:07:21 UTC,USD,cus_9s6XKzkNRiz8i3,none,LineItem-1,inclusive,-172.58,,,Pepperoni Pizza,txcd_40060003,tax_product_id_56,tax_code_99,-45.37,4,-8.9,,,-7.43,ShippingLineItem-e936,inclusive,Shipping description 69,txcd_92010001,shipping_tax_code_3,-8.14,,,,0,San Francisco,US,510 Townsend St,,94103,CA,us_ein,US,12-3456789,Seattle,US,9205th Ave,,98104,WA
6b8059-Sale,Sale,tax_jar,,1,2024-06-07 18:07:21 UTC,2024-06-07 18:07:21 UTC,2024-06-07 18:07:21 UTC,USD,cus_9s6XKzkNRiz8i3,none,LineItem-1,inclusive,195.72,,,Pepperoni Pizza,txcd_40060003,tax_product_id_56,tax_code_99,69.17,3,11.79,,,5.51,ShippingLineItem-3218,inclusive,Shipping description 69,txcd_92010001,shipping_tax_code_3,9.41,,,,0,San Francisco,US,510 Townsend St,,94103,CA,us_ein,US,12-3456789,Seattle,US,9205th Ave,,98104,WA

Guidance for each transaction type

Sale transactions

When importing sale transactions, follow these guidelines to ensure proper processing. You can only include one shipping line item per transaction.

For transactions with a single line item:

• Create one row with all required fields
• Set transaction_type to Sale

For transactions with multiple line items:

• Create a separate row for each line item
• Ensure these fields match exactly across all line items in the same transaction:
  • source_transaction_id
  • transaction_type
  • provider
  • tax_rules_at
  • currency
  • All tax_ids.* fields
  • All shipping_line_item.* fields

Refund and void transactions

When importing refunds or voids, you need to reference the original transaction:

For transactions with a single line item:

• Create one row with all required fields
• Set transaction_type to Refund or Void
• Set liable_transaction_id to the source_transaction_id of the original transaction
• Use the negative values for amount fields (add a minus sign)
• Ensure that currency matches the original transaction

For transactions with multiple line items:

• Create a separate row for each line item
• Set transaction_type to Refund or Void
• Set liable_transaction_id to the source_transaction_id of the original transaction
• Use the negative values for all amount fields
• Ensure these fields match exactly across all line items in the same refund/void transaction:
  • source_transaction_id
  • transaction_type
  • provider
  • tax_rules_at
  • currency
  • All tax_ids.* fields
  • All shipping_line_item.* fields

Correction transactions

To correct any previously imported transaction:

1. Duplicate the transaction you want to correct, using the same:
   • source_transaction_id
   • transaction_type
   • provider
2. Update any fields that need correction
3. Increase the transaction_version value (for example, from 1 to 2)

This approach replaces the original transaction data in your tax calculations rather than reversing it. Stripe Tax uses the version with the highest transaction_version value.

Import limitations

Import your transaction data

To import your third-party transaction data:

1. Go to the Tax section in the Stripe Dashboard.
2. Click Quick actions then select Import transactions.
3. Click Import CSV.
4. Select your prepared CSV file and click Import File.
5. Monitor import status in the drawer that appears. You can close this drawer and return later to check progress or view validation results.

If any errors occur during import, you can download a CSV of all rows with issues and the specific errors that occurred.

Test your imported data using the validation steps in Testing Stripe Tax.

Transaction versioning

You can correct previously imported transactions by using the transaction_version field to handle updates properly. To make corrections to transactions you’ve already imported, follow these steps:

1. Make the necessary corrections to your CSV file.
2. Re-import the transactions with the same identifiers.
3. Set the transaction_version to a higher number than the original import.

Stripe Tax maintains a record of these versions and uses the most recent version in its calculations and reporting.

Additional information

Limitations on use

The transaction import tool has limitations on what you can use it for:

• Scope of data: The tool is for importing external sales data to help monitor tax obligations. Don’t use it to import, VAT reportable purchases. Importing VAT reportable purchases inaccurately inflates gross sales figures and doesn’t correctly adjust tax liability.
• External transactions only: This tool exclusively supports importing transaction data from external sources. Don’t use it to correct or modify transactions that were originally processed through Stripe.

Tax calculation handling

Stripe doesn’t automatically recalculate tax for imported transactions. Imported transactions are reported using the tax amount you provide in the CSV file, regardless of whether you have an active Stripe Tax registration for that location.

While taxable amounts, nontaxable amounts, tax rates, and taxability reasons may appear in Stripe Tax reports and surfaces for imported transactions, these values should be treated only as estimates or approximations.

Visibility limitations

Imported transaction data has limited visibility in some Stripe Tax reports and interfaces:

• Transaction exports: Itemized and summarized exports exclude tax rate information, taxable amounts, and taxability reasons for each jurisdiction for imported transactions.
• Sigma: Tax jurisdiction details (tax_transaction_jurisdiction_details rows) are not available for imported transactions in Sigma reports.
• Tax Overview page: The Tax Overview dashboard does not include imported transactions in its calculations or displays.
• Location reports: Location reports do not show any imported transactions.

You can still view imported transaction details in tax reports and obligations monitoring.

Visibility in other Stripe products

Transactions imported using the import tool only appear in Stripe Tax reports and interfaces. To include third-party transactions in other products like Revenue Recognition, you need to use a separate product-specific import tool.

Data handling

Historical transaction data

You can import historical transaction data for any period on or after October 1, 2023.

Processing time

It takes up to 24 hours for the applicable processed transactions to be reflected in some Stripe Tax reports and interfaces.