Skip to content
Create account
 or
Sign in
The Stripe Docs logo
/
Create account
Sign in

Tax for software platforms

Learn how to enable Stripe Tax for your connected accounts, and collect tax when the connected account is liable for paying the tax.

Stripe Tax enables businesses to calculate, collect, and report indirect taxes in over 100 countries, across hundreds of product categories. As a platform, you can use Stripe tax to offer pre-integrated tax compliance to your connected accounts.

Use this guide if your connected accounts are responsible for collecting, filing, and reporting taxes.

  1. Set up your connected accounts for tax
  2. (Optional) Assign tax codes to the product catalog
  3. Integrate tax calculation and collection
  4. Access Stripe Tax Reports

Set up your connected accounts for tax

As a platform, you must make sure that a connected account has their tax settings and registrations set up before enabling tax calculations. This can be achieved by:

Connected account using the Stripe Dashboard

This option is only available to connected accounts with access to the Stripe Dashboard (for example, Standard accounts). Ask your connected accounts to use the Stripe Dashboard to add their head office location, preset tax code, and tax registrations. You can also collect the head office location and the preset tax code by enabling Stripe Tax in the connected account onboarding. You can make this adjustment in the Connect onboarding options in the Dashboard.

Creating a tax interface within your platform

This option allows accounts without access to the Stripe Dashboard (for example, Custom and Express accounts) to configure Stripe Tax.

Your platform must build an interface and use the Tax Settings API to set the head office location and other default values for the connected accounts. And your platform must use the Tax Registrations API to add tax registrations for the locations where the connected accounts have tax obligations.

Using Connect embedded components within your platform

You can use Connect embedded components to provide Stripe tax compliance integration to your connected accounts directly on your website with minimal development. Stripe regularly updates our embedded component integrations, so your tax compliance requirements are always current.

Stripe offers two components for tax:

  • Tax settings: Collect the details a connected account needs to calculate taxes, like the head office address and the preset tax code.
  • Tax registrations: Connected accounts can manage the locations where they have registered with the local tax authority. Adding a registration enables Stripe to calculate and collect taxes in a given location.

To embed tax settings and tax registrations into your website:

  1. Use the embedded components quickstart to set up your environment.

  2. Create an AccountSession with tax_settings: {enabled: true} and/or tax_registrations: {enabled: true}.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/account_sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d account={{CONNECTED_ACCOUNT_ID}} \
  -d "components[tax_settings][enabled]"=true \
  -d "components[tax_registrations][enabled]"=true
  1. Add the tax-settings or tax-registrations component to the DOM.

After creating the account session and initializing ConnectJS, you can render each tax component in the frontend:

taxPage.jsx
React
HTML + JavaScript
No results
// Include this React component
import {
  ConnectTaxSettings,
  ConnectTaxRegistrations,
  ConnectComponentsProvider,
} from "@stripe/react-connect-js";

return (
  <ConnectComponentsProvider connectInstance={stripeConnectInstance}>
    <div>
      {/* You can also use a tab layout */}
      <div>
        <h2>Tax Business Details</h2>
        <ConnectTaxSettings />
      <div>
      <div style={{ marginTop: "12px" }}>
        <h2>Tax Registrations</h2>
        <ConnectTaxRegistrations />
      <div>
    </div>
  </ConnectComponentsProvider>
);

Tax settings component preview

The tax settings component allows connected accounts to set their head office address and a preset tax code. Both attributes are required to calculate taxes for the connected account.

Tax registrations component

The tax registrations component allows a connected account to manage its tax registrations. If a connected account doesn’t add a tax registration, but calculates tax for that jurisdiction, Stripe Tax returns a tax amount of 0.00 and sets the taxability reason to not_collecting.

Your platform must then check whether connected accounts have configured Stripe Tax to enable tax calculations.

Note

Sign in to check if your connected accounts are ready to use Stripe Tax.

On the Connected accounts page in your Dashboard, you can filter the list on accounts that are ready to use Stripe Tax. You can also export those accounts with the following Stripe Tax-related columns:

  • Tax Settings Status: the value active indicates that the account is ready to use Stripe Tax. The value pending indicates that some required fields are missing.
  • Tax Threshold Status: the value exceeded indicates that the account’s calculated sales or transactions are over the location’s threshold, and the business likely needs to register for tax. For more information, see Monitor your obligations.
  • Tax Registration Status: the value active indicates that the account has at least one active tax registration.

You can also check whether an account has configured Stripe Tax by using the Tax Settings API.

Assign tax codes to the product catalog
Optional

To calculate taxes, Stripe Tax requires classifying products into their tax codes. One way to do this is to supply a preset tax code for each connected account, which is probably sufficient if your connected accounts typically sell a single category of items.

However, you might offer your users more control by allowing them to map Tax Codes to each product. You can retrieve a list of supported product tax codes from the Stripe Tax Code API. You can also allow a subset of this list if your connected accounts only sell specific types of products.

Integrate tax calculation and collection

You need to integrate with Stripe Tax to calculate taxes as part of your checkout flow.

Payment Links

Payment Links for one-time payments

Pick one of the currently supported charge types that allow the connected account to be liable for tax with Stripe Payment Links:

For the Payment Links API calls:

  • Include the Stripe-Account header with the value of the connected account ID.
Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/payment_links \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d "line_items[0][price]"=
{{PRICE_ID}}
 \
  -d "line_items[0][quantity]"=2 \
  -d "automatic_tax[enabled]"=true

Payment Links for subscriptions

Pick one of the currently supported charge types that allow the connected account to be liable for tax with Stripe Payment Links:

For the Payment Links API calls:

  • Include the Stripe-Account header with the value of the connected account ID.
Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/payment_links \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d "line_items[0][price]"=
{{PRICE_ID}}
 \
  -d "line_items[0][quantity]"=1 \
  -d "automatic_tax[enabled]"=true

Checkout

Checkout Sessions for one-time payments

Pick one of the currently supported charge types that allow the connected account to be liable for tax with Stripe Checkout:

For the Checkout Sessions API calls:

  • Include the Stripe-Account header with the value of the connected account ID.
Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d "line_items[0][price]"=
{{PRICE_ID}}
 \
  -d "line_items[0][quantity]"=2 \
  -d "automatic_tax[enabled]"=true \
  -d mode=payment \
  --data-urlencode success_url="https://example.com/success" \
  --data-urlencode cancel_url="https://example.com/cancel"

Checkout Sessions for subscriptions

Pick one of the currently supported charge types that allow the connected account to be liable for tax with Stripe Checkout:

For the Checkout Sessions API calls:

  • Include the Stripe-Account header with the value of the connected account ID.
Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d "line_items[0][price]"=
{{PRICE_ID}}
 \
  -d "line_items[0][quantity]"=1 \
  -d "automatic_tax[enabled]"=true \
  -d mode=subscription \
  --data-urlencode success_url="https://example.com/success" \
  --data-urlencode cancel_url="https://example.com/cancel"

Billing

Subscriptions

Pick one of the currently supported charge types that allow the connected account to be liable for tax with Stripe Subscriptions:

For the Subscriptions API calls:

  • Include the Stripe-Account header with the value of the connected account ID.
Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/subscriptions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d "items[0][price]"=
{{PRICE_ID}}
 \
  -d "items[0][quantity]"=1 \
  -d customer=
{{CUSTOMER_ID}}
 \
  -d "automatic_tax[enabled]"=true

Invoicing

Pick one of the currently supported charge types that allow the connected account to be liable for tax with Stripe Invoicing:

For the Invoices API calls:

  • Include the Stripe-Account header with the value of the connected account ID.
Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/invoices \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d customer=
{{CUSTOMER_ID}}
 \
  -d "automatic_tax[enabled]"=true

Custom flows using the Stripe Tax API

Payment Intents

Pick one of the currently supported charge types that allow the connected account to be liable for tax with Stripe Tax API:

For the Tax Calculation API calls:

  • Include the Stripe-Account header with the value of the connected account ID.
Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/tax/calculations \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d currency=usd \
  -d "line_items[0][amount]"=1000 \
  -d "line_items[0][reference]"=L1 \
  -d customer=
{{CUSTOMER_ID}}

For the Payment Intents API calls:

  • Include the Stripe-Account header with the value of the connected account ID.
  • Include amount with the amount_total returned by the tax calculation.
  • Include metadata[tax_calculation] with the id returned by the tax calculation.
Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d amount=1000 \
  -d currency=usd \
  -d customer=
{{CUSTOMER_ID}}
 \
  -d "metadata[tax_calculation]"=
{{CALCULATION_ID}}

You must also create tax transactions to record the tax you collect from customers and account for refunds.

Off-Stripe payments

Check how to integrate using Stripe Tax API and to allow the connected account to be liable for tax, include the Stripe-Account header with the value of the connected account ID in the Tax Calculation API calls:

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/tax/calculations \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d currency=usd \
  -d "line_items[0][amount]"=1000 \
  -d "line_items[0][reference]"=L1 \
  -d customer=
{{CUSTOMER_ID}}

You must also create tax transactions to record the tax you collect from customers and account for refunds.

After you implement it, Stripe automatically starts collecting tax in jurisdictions where the user has an active registration.

Note

Independent of the integration, your connected account receives a credit for the collected tax amount by default.

Access Stripe Tax Reports

Your connected accounts can use Stripe Tax reports to help them correctly file and remit tax.

Connected account use the Stripe Dashboard

This option is only available to accounts with access to the Stripe Dashboard (for example, Standard accounts).

The connected accounts can access their Stripe Tax reports using the Tax Reporting functionality in the Stripe Dashboard.

Use the Stripe API

Use this option for accounts without access to the Stripe Dashboard (for example, Custom and Express accounts).

Platforms can download itemized tax transactions for their connected accounts using the Report API with the connected_account_tax.transactions.itemized.2 report type.

When a platform runs the following command, they download all 2022 transactions from all connected accounts:

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/reporting/report_runs \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d report_type="connected_account_tax.transactions.itemized.2" \
  -d "parameters[interval_start]"=1641013200 \
  -d "parameters[interval_end]"=1672549200

When a platform runs the following command, they download all 2022 transactions from a single connected account:

Note

To generate reports for connected accounts, use the connected_account parameter instead of the Stripe-Account header.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/reporting/report_runs \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d report_type="connected_account_tax.transactions.itemized.2" \
  -d "parameters[interval_start]"=1641013200 \
  -d "parameters[interval_end]"=1672549200 \
  -d "parameters[connected_account]"={{CONNECTED_ACCOUNT_ID}}

Use the Export Tax Transactions Embedded Component

To learn more about this component and integrate it, see export tax transactions.

See also

Was this page helpful?
YesNo