> For the complete documentation index, see [llms.txt](https://docs.getsphere.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.getsphere.com/features/integrations/api/stripe-integration-api/add-tax-to-a-stripe-checkout-session.md).

# Add tax to a Stripe Checkout Session

Apply tax to an open Stripe Checkout Session created by your application.

## Add tax to a Stripe Checkout Session

> Use this when you create the Checkout Session yourself: Sphere reads the cart from the session, calculates tax for the buyer's address, and attaches the tax rates. The session must still be open. Nothing is stored.

```json
{"openapi":"3.1.0","info":{"title":"Sphere API","version":"1.0.0"},"servers":[{"url":"https://api.getsphere.com/v1"},{"url":"https://server.getsphere.com/tax_api/v1"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"CalculateStripeCheckoutSessionTaxRequest":{"additionalProperties":false,"description":"Add tax to a Checkout Session you created yourself. Nothing is stored.","properties":{"stripe_account_id":{"anyOf":[{"pattern":"^acct_","type":"string"},{"type":"null"}],"default":null,"title":"Stripe Account Id"},"shipping_address":{"$ref":"#/components/schemas/Address"},"billing_address":{"anyOf":[{"$ref":"#/components/schemas/Address"},{"type":"null"}],"default":null},"tax_ids":{"items":{"$ref":"#/components/schemas/CustomerTaxIdInput"},"title":"Tax Ids","type":"array"}},"required":["shipping_address"],"title":"CalculateStripeCheckoutSessionTaxRequest","type":"object"},"Address":{"additionalProperties":false,"description":"A postal address.","properties":{"street":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Street. May include the building number when `building_number` is left out.","title":"Street"},"building_number":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Building number.","title":"Building Number"},"additional_street":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Additional street information.","title":"Additional Street"},"additional_line":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A third address line, for details neither street field holds.","title":"Additional Line"},"district":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Neighbourhood or borough within the city, e.g. a Brazilian bairro.","title":"District"},"city":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"City.","title":"City"},"postal_code":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Postal code.","title":"Postal Code"},"region":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Country subdivision, such as a state or province.","title":"Region"},"region_code":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The country subdivision's code, e.g. `JAL` for the Mexican state of Jalisco or `MI` for the Italian province of Milan.","title":"Region Code"},"country":{"$ref":"#/components/schemas/CountryCode","description":"Country."},"extensions":{"anyOf":[{"$ref":"#/components/schemas/AddressExtensions"},{"type":"null"}],"default":null,"description":"Extension blocks for the invoice's regimes, keyed by regime."}},"required":["country"],"title":"Address","type":"object"},"CountryCode":{"description":"An ISO 3166-1 alpha-2 country code, e.g. `BE`.","pattern":"^[A-Z]{2}$","type":"string"},"AddressExtensions":{"additionalProperties":false,"description":"Regime fields for an address.","properties":{"br_nfe":{"anyOf":[{"$ref":"#/components/schemas/BrazilAddressExtension"},{"type":"null"}],"default":null},"br_nfse":{"anyOf":[{"$ref":"#/components/schemas/BrazilAddressExtension"},{"type":"null"}],"default":null}},"title":"AddressExtensions","type":"object"},"BrazilAddressExtension":{"additionalProperties":false,"description":"Brazilian fields for an address, the same under every Brazilian regime.","properties":{"municipality_code":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"IBGE municipality code, 7 digits; required for an address in Brazil (cMun).","title":"Municipality Code"},"bacen_country_code":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"NF-e, for an address abroad: the country as its code in the BACEN country table, e.g. `0639` for Argentina (cPais).","title":"Bacen Country Code"},"country_name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"NF-e, for an address abroad: the country's name as the NF-e prints it, e.g. `ARGENTINA` (xPais).","title":"Country Name"}},"title":"BrazilAddressExtension","type":"object"},"CustomerTaxIdInput":{"additionalProperties":false,"description":"A buyer's tax registration. Give its country directly, or a Stripe\n``tax_id_type`` whose prefix is the country (``de_vat`` -> DE).","properties":{"value":{"minLength":1,"title":"Value","type":"string"},"country":{"anyOf":[{"maxLength":2,"minLength":2,"type":"string"},{"type":"null"}],"default":null,"title":"Country"},"tax_id_type":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Tax Id Type"}},"required":["value"],"title":"CustomerTaxIdInput","type":"object"},"StripeCheckoutSessionTaxResponse":{"description":"The outcome of a tax write, shaped like the invoice endpoint's, plus\nStripe's totals after it.","properties":{"external_id":{"title":"External Id","type":"string"},"stripe_account_id":{"title":"Stripe Account Id","type":"string"},"status":{"allOf":[{"$ref":"#/components/schemas/StripeCheckoutSessionTaxResponseStatusEnum"}],"title":"Status"},"reason":{"title":"Reason","type":"string"},"tax_calculation_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Tax Calculation Id"},"taxability_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Taxability Reason"},"stripe":{"$ref":"#/components/schemas/StripeSessionTotals"}},"required":["external_id","stripe_account_id","status","reason","stripe"],"title":"StripeCheckoutSessionTaxResponse","type":"object"},"StripeCheckoutSessionTaxResponseStatusEnum":{"enum":["applied","no_tax"],"type":"string"},"StripeSessionTotals":{"description":"Every amount as Stripe holds it, so no caller computes a total itself.","properties":{"currency":{"title":"Currency","type":"string"},"amount_subtotal":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Amount Subtotal"},"amount_discount":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Amount Discount"},"amount_tax":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Amount Tax"},"amount_total":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Amount Total"},"tax_lines":{"items":{"$ref":"#/components/schemas/TaxLine"},"title":"Tax Lines","type":"array"}},"required":["currency"],"title":"StripeSessionTotals","type":"object"},"TaxLine":{"description":"One rate as Stripe reports it on the session, with Stripe's own amounts.","properties":{"amount":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Amount"},"taxable_amount":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Taxable Amount"},"taxability_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Taxability Reason"},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Display Name"},"percentage":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Percentage"},"inclusive":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Inclusive"},"jurisdiction":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Jurisdiction"},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Country"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"State"},"tax_type":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Tax Type"}},"title":"TaxLine","type":"object"}}},"paths":{"/stripe/checkout_sessions/{external_id}/tax":{"post":{"operationId":"stripe_checkout_sessions_tax_create","description":"Use this when you create the Checkout Session yourself: Sphere reads the cart from the session, calculates tax for the buyer's address, and attaches the tax rates. The session must still be open. Nothing is stored.","summary":"Add tax to a Stripe Checkout Session","parameters":[{"in":"path","name":"external_id","schema":{"type":"string"},"description":"The Stripe Checkout Session id, e.g. cs_test_a1B2c3.","required":true}],"tags":["Stripe"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalculateStripeCheckoutSessionTaxRequest"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/CalculateStripeCheckoutSessionTaxRequest"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/CalculateStripeCheckoutSessionTaxRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StripeCheckoutSessionTaxResponse"}}},"description":""},"400":{"description":"Validation error."},"403":{"description":"Missing/invalid API key, or Stripe account not enabled for Sphere tax."},"404":{"description":"No such account or session."},"409":{"description":"The session is closed, or Sphere could not calculate tax for the address."},"502":{"description":"Stripe refused the tax update."}}}}}}
```
