Calculate tax in your custom payment flow

In most cases, the tax you collect depends on your customer’s location. Collecting your customer’s full address gives the most accurate tax calculation result. Before collecting an address, you can show your customer an estimate based on their IP address.

The form below collects a full postal address:

<form>
    <label for="address_line1">Address Line 1</label> <input type="text" id="address_line1" />
    <label for="address_city">City</label> <input type="text" id="address_city" />
    <label for="address_state">State</label> <select id="address_state">
      <option value="CA">California</option>
      <!-- add more states here -->
    </select>
    <label for="address_postal_code">Postal code</label> <input type="text" id="address_postal_code" />
    <label for="address_country">Country</label> <select id="address_country">
      <option value="US">United States</option>
      <option value="DE">Germany</option>
      <option value="IE">Ireland</option>
      <!-- add more countries here -->
    </select>
</form>

You might pass the address to your server endpoint like this:

const address = {
  line1: document.getElementById('address_line1').value,
  city: document.getElementById('address_city').value,
  state: document.getElementById('address_state').value,
  postal_code: document.getElementById('address_postal_code').value,
  country: document.getElementById('address_country').value,
};
var response = fetch('/preview-cart', {
  method: 'POST',
  body: JSON.stringify({address: address}),
  headers: {'Content-Type': 'application/json'},
}).then(function(response) {
  return response.json();
}).then(function(responseJson) {
  // Handle errors, or display calculated tax to your customer.
});

The address information required to calculate tax varies by customer country:

• United States: We require your customer’s postal code at a minimum. We recommend providing a full address for the most accurate tax calculation result.
• Canada: We require your customer’s postal code or province.
• Everywhere else: We only require your customer’s country code.

You choose when and how often to calculate tax. For example, you can:

• Show a tax estimate based on your customer’s IP address when they enter your checkout flow
• Recalculate tax as your customer types their billing or shipping address
• Calculate the final tax amount to collect when your customer finishes typing their address

Stripe charges a fee per tax calculation API call. You can throttle tax calculation API calls to manage your costs.

The examples below show how to calculate tax in a variety of scenarios.

curl https://api.stripe.com/v1/tax/calculations \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d currency=usd \
  -d "line_items[0][amount]"=1000 \
  -d "line_items[0][reference]"=L1 \
  -d "customer_details[address][line1]"="354 Oyster Point Blvd" \
  -d "customer_details[address][city]"="South San Francisco" \
  -d "customer_details[address][state]"=CA \
  -d "customer_details[address][postal_code]"=94080 \
  -d "customer_details[address][country]"=US \
  -d "customer_details[address_source]"=shipping \
  -d "expand[0]"="line_items.data.tax_breakdown"

The calculation response contains amounts you can display to your customer, and use to take payment:

You can calculate tax for your customer before collecting payment method details and creating a PaymentIntent. For example, you could display a shopping cart total when they provide their postal code.

In the example below, your server defines a /preview-cart endpoint, where the customer’s address is sent from your client-side form. The server combines the cart’s line items and the customer’s address to calculate tax.

// Set your secret key. Remember to switch to your live secret key in production.
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = require('stripe')('sk_...');
const express = require('express');
const app = express();

// Parse the request body as JSON.
app.use(express.json());

app.get('/preview-cart', async (req, res) => {
  const cart = ...; // Load the cart/order from your system
  const address = req.body.address;
  const calculation = await stripe.tax.calculations.create({
    currency: cart.currency,
    line_items: cart.items.map(
      cartItem => ({
        reference: cartItem.id,
        amount: cartItem.unitPrice * cartItem.quantity,
        quantity: cartItem.quantity
      })
    ),
    customer_details: {
      address: {
        line1: address.line1,
        city: address.city,
        state: address.state,
        postal_code: address.postal_code,
        country: address.country,
      },
      address_source: "billing"
    },
    expand: ['line_items.data.tax_breakdown']
  });
  res.json({tax_amount: calculation.tax_amount_exclusive});
});

app.listen(3000, () => {
  console.log('Running on port 3001');
});

When you’re ready to take payment, create a PaymentIntent from the tax calculation result. Store the tax calculation ID in the PaymentIntent’s metadata or in your own database so you can create a tax transaction when your customer completes payment.

The example below shows a server endpoint that calculates tax, creates (or updates) a PaymentIntent, and returns the result to the client. You can then display the tax to your customer. Use the client_secret to take the payment.

// Set your secret key. Remember to switch to your live secret key in production.
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = require('stripe')('sk_...');
const express = require('express');
const app = express();

// Parse the request body as JSON.
app.use(express.json());

app.get('/calculate-cart', async (req, res) => {
  const cart = ...; // Load the cart/order from your system
  const address = req.body.address;

  const taxCalculation = await stripe.tax.calculations.create({
    // ...
  });

  let paymentIntent;

  // Update the PaymentIntent if one already exists for this cart.
  if (cart.paymentIntent) {
    paymentIntent = await stripe.paymentIntents.update(cart.paymentIntent, {
      amount: taxCalculation.amount_total,
      metadata: {calculation: taxCalculation.id},
    });
  } else {
    paymentIntent = await stripe.paymentIntents.create({
      currency: cart.currency,
      amount: taxCalculation.amount_total,
      metadata: {calculation: taxCalculation.id},
      automatic_payment_methods: {enabled: true},
    });
  }

  // Store PaymentIntent ID in cart or customer session.
  cart.paymentIntent = paymentIntent.id;

  // Return calculated amounts and PaymentIntent secret to the client.
  res.json({
    total: taxCalculation.amount_total,
    tax_amount: taxCalculation.tax_amount_exclusive,
    client_secret: paymentIntent.client_secret
  });
});

app.listen(3000, () => {
  console.log('Running on port 3000');
});

If your integration uses the Payment Element, fetch updates from the server after updating the PaymentIntent.

Handling customer location errors

The calculation returns the customer_tax_location_invalid error code if your customer’s address is invalid or isn’t precise enough to calculate tax:

{
  "error": {
    "doc_url": "https://stripe.com/docs/error-codes/customer-tax-location-invalid",
    "code": "customer_tax_location_invalid",
    "message": "We could not determine the customer's tax location based on the provided customer address.",
    "param": "customer_details[address]",
    "type": "invalid_request_error"
  }
}

When you receive this error, prompt your customer to check the address they’ve entered and fix any typos.

Creating a tax transaction records the tax you’ve collected from your customer, so that later you can download exports and generate reports to help with filing your taxes. You can create a transaction from a calculation until the expires_at timestamp, 48 hours after it’s created. Attempting to use it after this time returns an error.

When creating a tax transaction, you must provide a unique reference for the tax transaction and each line item. The references appear in tax exports to help you reconcile the tax you collected with the orders in your system.

For example, a tax transaction with reference pi_123456789, line item references L1 and L2, and a shipping cost, looks like this in the itemized tax exports:

When your customer pays, use the calculation ID to record the tax collected. Two ways to do this are:

• If your server has an endpoint where your customer submits their order, you can create the tax transaction after the order is successfully submitted.
• Listen for the payment_intent.succeeded webhook event. Retrieve the calculation ID from the PaymentIntent metadata.

The example below creates a transaction and uses the PaymentIntent ID as the unique reference:

curl https://api.stripe.com/v1/tax/transactions/create_from_calculation \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  --data-urlencode calculation="{{TAX_CALCULATION}}" \
  --data-urlencode reference=
{{PAYMENT_INTENT_ID}} \
  -d "expand[]"=line_items

Store the tax transaction ID so that later you can record refunds. You can store the transaction ID in your database or in the PaymentIntent’s metadata:

curl https://api.stripe.com/v1/payment_intents/
{{PAYMENT_INTENT_ID}} \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  --data-urlencode "metadata[tax_transaction]"="{{TAX_TRANSACTION}}"

After creating a tax transaction to record a sale to your customer, you might need to record refunds. These are also represented as tax transactions, with type=reversal. Reversal transactions offset an earlier transaction by having amounts with opposite signs. For example, a transaction that recorded a sale for 50 USD might later have a full reversal of -50 USD.

When you issue a refund (using Stripe or outside of Stripe) you need to create a reversal tax transaction with a unique reference. Common strategies include:

• Append a suffix to the original reference. For example, if the original transaction has reference pi_123456789, then create the reversal transaction with reference pi_123456789-refund.
• Use the ID of the Stripe refund or a refund ID from your system. For example, re_3MoslRBUZ691iUZ41bsYVkOg or myRefund_456.

Choose the approach that works best for how you reconcile your customer orders with your tax exports.

Fully refund a sale

When you fully refund a sale in your system, create a reversal transaction with mode=full.

In the example below, tax_1MEFAAI6rIcR421eB1YOzACZ is the tax transaction recording the sale to your customer:

curl https://api.stripe.com/v1/tax/transactions/create_reversal \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d mode=full \
  -d original_transaction=tax_1MEFAAI6rIcR421eB1YOzACZ \
  -d reference=pi_123456789-cancel

This returns the full reversal transaction that’s created:

{
  "id": "tax_1MEFtXI6rIcR421e0KTGXvCK",
  "object": "tax.transaction",
  "created": 1670866467,
  "currency": "eur",
  "customer": null,
  "customer_details": {
    "address": {
      "city": null,
      "country": "IE",

Fully reversing a transaction doesn’t affect previous partial reversals. When you record a full reversal, make sure you fully reverse any previous partial reversals for the same transaction to avoid duplicate refunds.

Partially refund a sale

After issuing a refund to your customer, create a reversal tax transaction with mode=partial. This allows you to record a partial refund by providing the line item amounts refunded. You can create up to 10 partial reversals for each sale. Reversing more than the amount of tax you collected returns an error.

The example below records a refund of only the first line item in the original transaction:

curl https://api.stripe.com/v1/tax/transactions/create_reversal \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d mode=partial \
  -d original_transaction=tax_1MEFAAI6rIcR421eB1YOzACZ \
  -d reference=pi_123456789-refund_1 \
  -d "line_items[0][original_line_item]"=tax_li_MyBXPByrSUwm6r \
  -d "line_items[0][reference]"=L1 \
  -d "line_items[0][amount]"=-4999 \
  -d "line_items[0][amount_tax]"=-1150 \
  --data-urlencode "metadata[refund]"=
{{REFUND_ID}} \
  --data-urlencode "metadata[refund_reason]"="Refunded line 1 of pi_123456789 (customer was unhappy)" \
  -d "expand[0]"=line_items

This returns the partial reversal transaction that’s created:

{
  "id": "tax_1MEFACI6rIcR421eHrjXCSmD",
  "object": "tax.transaction",
  "created": 1670863656,
  "currency": "eur",
  ...
  "line_items": {
    "object": "list",
    "data": [
      {

For each line item reversed you need to provide the amount and amount_tax reversed. The amount is tax-inclusive if the original calculation line item was tax-inclusive.

How amount and amount_tax are determined depends on your situation:

• If your transactions always have a single line item, use full reversals instead.
• If you always refund entire line items, use the original transaction line item amount and amount_tax, but with negative signs.
• If you refund parts of line items, you need to calculate the amounts refunded. For example, for a sale transaction with amount=5000 and amount_tax=500, after refunding half the line item you’d create a partial reversal with line item amount=-2500 and amount_tax=-250.

We’re building support for reversing a line item by passing a single after-tax amount, instead of having to provide amount and amount_tax separately.

Undo a partial refund

Tax transactions are immutable but you can cancel out a partial refund by creating a full reversal of it.

You might need to do this when:

• The payment refund fails and you haven’t provided the good or service to your customer
• The wrong order is refunded or the wrong amounts are refunded
• The original sale is fully refunded and the partial refunds are no longer valid

In the example below, tax_1MEFACI6rIcR421eHrjXCSmD is the transaction representing the partial refund:

curl https://api.stripe.com/v1/tax/transactions/create_reversal \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d mode=full \
  -d original_transaction=tax_1MEFACI6rIcR421eHrjXCSmD \
  -d reference=pi_123456789-refund_1-cancel \
  -d "metadata[refund_reason]"="User called to cancel because they picked the wrong item"

This returns the full reversal transaction that’s created:

{
  "id": "tax_1MEFADI6rIcR421e94fNTOCK",
  "object": "tax.transaction",
  "created": 1670863657,
  "currency": "eur",
  ...
  "line_items": {
    "object": "list",
    "data": [
      {

Tax calculations and transactions behave identically in test mode and live mode, so you can confirm that your integration is working correctly before going live. You can run up to 1,000 tax calculations in test mode. Contact Stripe support if you need a higher limit.