0
# Tax
1

2
Stripe Tax provides comprehensive tax calculation, collection, and compliance capabilities for global transactions. It handles complex tax scenarios including VAT, GST, sales tax, and other regional tax requirements with real-time calculation and automated compliance features.
3

4
## Tax Calculation
5

6
### Tax.Calculations
7

8
Calculate taxes for transactions before creating charges or invoices:
9

10
```typescript { .api }
11
interface TaxCalculation {
12
  id: string;
13
  object: 'tax.calculation';
14
  amount_total: number;
15
  currency: string;
16
  customer?: string;
17
  customer_details: {
18
    address: {
19
      country: string;
20
      state?: string;
21
      postal_code?: string;
22
      city?: string;
23
      line1?: string;
24
      line2?: string;
25
    };
26
    address_source: 'billing' | 'shipping';
27
    ip_address?: string;
28
    taxability_override: 'none' | 'reverse_charge' | 'exempt';
29
  };
30
  line_items: {
31
    data: Array<{
32
      id: string;
33
      amount: number;
34
      amount_tax: number;
35
      product?: string;
36
      quantity: number;
37
      reference?: string;
38
      tax_behavior: 'inclusive' | 'exclusive';
39
      tax_breakdown: Array<{
40
        amount: number;
41
        jurisdiction: {
42
          country: string;
43
          display_name: string;
44
          level: 'country' | 'state' | 'county' | 'city';
45
          state?: string;
46
        };
47
        sourcing: 'destination' | 'origin';
48
        tax_rate_details: {
49
          country: string;
50
          percentage_decimal: string;
51
          state?: string;
52
          tax_type: 'gst' | 'hst' | 'pst' | 'qst' | 'rst' | 'sales_tax' | 'vat';
53
        };
54
        taxability_reason: 'not_collecting' | 'not_subject_to_tax' | 'not_supported' | 'portion_product_exempt' | 'portion_reduced_rated' | 'portion_standard_rated' | 'product_exempt' | 'product_exempt_holiday' | 'proportionally_rated' | 'reduced_rated' | 'reverse_charge' | 'standard_rated' | 'taxable_basis_reduced' | 'zero_rated';
55
      }>;
56
    }>;
57
  };
58
  shipping_cost?: {
59
    amount: number;
60
    amount_tax: number;
61
  };
62
  expires_at?: number;
63
}
64

65
// Calculate tax for line items
66
const calculation = await stripe.tax.calculations.create({
67
  currency: 'usd',
68
  line_items: [
69
    {
70
      amount: 1000,
71
      reference: 'L1',
72
      tax_behavior: 'exclusive'
73
    }
74
  ],
75
  customer_details: {
76
    address: {
77
      line1: '123 Main St',
78
      city: 'San Francisco',
79
      state: 'CA',
80
      postal_code: '94105',
81
      country: 'US'
82
    },
83
    address_source: 'billing'
84
  }
85
});
86

87
// Calculate with products
88
const productCalculation = await stripe.tax.calculations.create({
89
  currency: 'usd',
90
  line_items: [
91
    {
92
      amount: 2000,
93
      product: 'prod_123',
94
      quantity: 1,
95
      tax_behavior: 'exclusive'
96
    }
97
  ],
98
  customer_details: {
99
    address: {
100
      country: 'GB',
101
      postal_code: 'SW1A 1AA'
102
    },
103
    address_source: 'shipping'
104
  }
105
});
106

107
// Calculate with shipping
108
const shippingCalculation = await stripe.tax.calculations.create({
109
  currency: 'eur',
110
  line_items: [
111
    {
112
      amount: 5000,
113
      reference: 'item-1',
114
      tax_behavior: 'exclusive'
115
    }
116
  ],
117
  shipping_cost: {
118
    amount: 500
119
  },
120
  customer_details: {
121
    address: {
122
      country: 'DE',
123
      postal_code: '10115'
124
    },
125
    address_source: 'shipping'
126
  }
127
});
128

129
// Retrieve calculation
130
const retrieved = await stripe.tax.calculations.retrieve('taxcalc_123');
131

132
// List line items
133
const lineItems = await stripe.tax.calculations.listLineItems('taxcalc_123');
134
```
135

136
## Tax Transactions
137

138
### Tax.Transactions
139

140
Record and manage tax transactions for compliance:
141

142
```typescript { .api }
143
interface TaxTransaction {
144
  id: string;
145
  object: 'tax.transaction';
146
  type: 'reversal' | 'transaction';
147
  reference: string;
148
  currency: string;
149
  customer?: string;
150
  customer_details: {
151
    address: {
152
      country: string;
153
      state?: string;
154
      postal_code?: string;
155
      city?: string;
156
      line1?: string;
157
      line2?: string;
158
    };
159
    address_source: 'billing' | 'shipping';
160
    ip_address?: string;
161
    taxability_override: 'none' | 'reverse_charge' | 'exempt';
162
  };
163
  line_items: {
164
    data: Array<{
165
      id: string;
166
      amount: number;
167
      amount_tax: number;
168
      product?: string;
169
      quantity: number;
170
      reference: string;
171
      reversal?: {
172
        original_line_item: string;
173
      };
174
    }>;
175
  };
176
  created: number;
177
}
178

179
// Create transaction from calculation
180
const transaction = await stripe.tax.transactions.createFromCalculation({
181
  calculation: 'taxcalc_123',
182
  reference: 'order_12345'
183
});
184

185
// Create transaction directly
186
const directTransaction = await stripe.tax.transactions.create({
187
  currency: 'usd',
188
  line_items: [
189
    {
190
      amount: 1000,
191
      amount_tax: 80,
192
      reference: 'L1',
193
      quantity: 1,
194
      tax_behavior: 'exclusive'
195
    }
196
  ],
197
  customer_details: {
198
    address: {
199
      country: 'US',
200
      state: 'CA',
201
      postal_code: '94105'
202
    },
203
    address_source: 'billing'
204
  },
205
  reference: 'invoice_67890'
206
});
207

208
// Retrieve transaction
209
const retrievedTx = await stripe.tax.transactions.retrieve('tax_123');
210

211
// Create reversal
212
const reversal = await stripe.tax.transactions.createReversal('tax_123', {
213
  mode: 'full',
214
  reference: 'refund_123'
215
});
216

217
// Partial reversal
218
const partialReversal = await stripe.tax.transactions.createReversal('tax_123', {
219
  mode: 'partial',
220
  line_items: [
221
    {
222
      line_item: 'taxli_123',
223
      quantity: 1
224
    }
225
  ],
226
  reference: 'partial_refund_456'
227
});
228

229
// List transactions
230
const transactions = await stripe.tax.transactions.list({
231
  limit: 10,
232
  reference: 'order_12345'
233
});
234
```
235

236
## Tax Settings
237

238
### Tax.Settings
239

240
Manage global tax settings and configurations:
241

242
```typescript { .api }
243
interface TaxSettings {
244
  object: 'tax.settings';
245
  defaults: {
246
    tax_behavior: 'inclusive' | 'exclusive';
247
    tax_code?: string;
248
  };
249
  head_office?: {
250
    address: {
251
      city?: string;
252
      country: string;
253
      line1?: string;
254
      line2?: string;
255
      postal_code?: string;
256
      state?: string;
257
    };
258
  };
259
  status: 'active' | 'pending';
260
  status_details: {
261
    active?: {
262
      status: 'active';
263
    };
264
    pending?: {
265
      status: 'pending';
266
      missing_fields: Array<string>;
267
    };
268
  };
269
}
270

271
// Retrieve tax settings
272
const settings = await stripe.tax.settings.retrieve();
273

274
// Update tax settings
275
const updated = await stripe.tax.settings.update({
276
  defaults: {
277
    tax_behavior: 'exclusive',
278
    tax_code: 'txcd_99999999'
279
  },
280
  head_office: {
281
    address: {
282
      line1: '354 Oyster Point Blvd',
283
      city: 'South San Francisco',
284
      state: 'CA',
285
      postal_code: '94080',
286
      country: 'US'
287
    }
288
  }
289
});
290
```
291

292
## Tax Registrations
293

294
### Tax.Registrations
295

296
Manage tax registrations for different jurisdictions:
297

298
```typescript { .api }
299
interface TaxRegistration {
300
  id: string;
301
  object: 'tax.registration';
302
  active_from: number;
303
  country: string;
304
  country_options: {
305
    [key: string]: {
306
      standard_tax_id?: {
307
        type: string;
308
        value: string;
309
      };
310
      type: 'simplified' | 'standard';
311
    };
312
  };
313
  created: number;
314
  expires_at?: number;
315
  livemode: boolean;
316
  status: 'active' | 'expired' | 'scheduled';
317
}
318

319
// Create tax registration
320
const registration = await stripe.tax.registrations.create({
321
  country: 'US',
322
  country_options: {
323
    us: {
324
      type: 'state_tax_id',
325
      state: 'CA'
326
    }
327
  },
328
  active_from: Math.floor(Date.now() / 1000)
329
});
330

331
// Create EU registration
332
const euRegistration = await stripe.tax.registrations.create({
333
  country: 'IE',
334
  country_options: {
335
    ie: {
336
      type: 'oss_union',
337
      standard_tax_id: {
338
        type: 'eu_vat',
339
        value: 'IE1234567FA'
340
      }
341
    }
342
  },
343
  active_from: Math.floor(Date.now() / 1000)
344
});
345

346
// Retrieve registration
347
const retrievedReg = await stripe.tax.registrations.retrieve('taxreg_123');
348

349
// Update registration
350
const updatedReg = await stripe.tax.registrations.update('taxreg_123', {
351
  expires_at: Math.floor(Date.now() / 1000) + (365 * 24 * 60 * 60), // 1 year
352
  active_from: Math.floor(Date.now() / 1000)
353
});
354

355
// List registrations
356
const registrations = await stripe.tax.registrations.list({
357
  status: 'active'
358
});
359
```
360

361
## Integration with Other Resources
362

363
### Automatic Tax on Products
364

365
```typescript { .api }
366
// Create product with tax code
367
const taxableProduct = await stripe.products.create({
368
  name: 'Digital Service',
369
  tax_code: 'txcd_10103001' // Digital services tax code
370
});
371

372
// Create price with tax behavior
373
const taxInclusivePrice = await stripe.prices.create({
374
  product: taxableProduct.id,
375
  unit_amount: 1200, // €12.00 including tax
376
  currency: 'eur',
377
  tax_behavior: 'inclusive'
378
});
379
```
380

381
### PaymentIntents with Tax
382

383
```typescript { .api }
384
// PaymentIntent with automatic tax
385
const paymentIntent = await stripe.paymentIntents.create({
386
  amount: 2000,
387
  currency: 'usd',
388
  customer: 'cus_123',
389
  automatic_tax: {
390
    enabled: true
391
  },
392
  metadata: {
393
    tax_calculation: 'taxcalc_123'
394
  }
395
});
396
```
397

398
Stripe Tax handles the complexity of global tax compliance, providing accurate real-time calculations, automated tax collection, and detailed reporting for tax authorities across multiple jurisdictions.