> 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/create-a-stripe-checkout-session.md).

# Create a Stripe Checkout Session

Create a Stripe Checkout Session with Sphere tax applied.

## Create a Stripe Checkout Session with Sphere tax applied

> Send Stripe's Checkout parameters under stripe, and the buyer Sphere needs to price under sphere. Sphere calculates tax, expresses it as Tax Rate objects in your account, creates the Checkout Session with those rates and returns it. Redirect to url (hosted) or mount client\_secret (embedded) exactly as you do today. When the session completes, call the complete endpoint (or let Sphere's webhook do it) so renewals are taxed by Sphere.

```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":{"CreateCheckoutSessionRequest":{"additionalProperties":false,"description":"Stripe's Checkout parameters and Sphere's pricing inputs, kept apart.","properties":{"stripe_account_id":{"anyOf":[{"pattern":"^acct_","type":"string"},{"type":"null"}],"default":null,"title":"Stripe Account Id"},"stripe":{"$ref":"#/components/schemas/StripeCheckoutSessionParams"},"sphere":{"$ref":"#/components/schemas/MerchantSuppliedBuyer"}},"required":["stripe","sphere"],"title":"CreateCheckoutSessionRequest","type":"object"},"StripeCheckoutSessionParams":{"additionalProperties":false,"description":"Stripe's own Checkout parameters, whitelisted and passed through.","properties":{"mode":{"allOf":[{"$ref":"#/components/schemas/ModeEnum"}],"title":"Mode"},"currency":{"maxLength":3,"minLength":3,"title":"Currency","type":"string"},"line_items":{"items":{"$ref":"#/components/schemas/LineItem"},"minItems":1,"title":"Line Items","type":"array"},"customer_id":{"anyOf":[{"pattern":"^cus_","type":"string"},{"type":"null"}],"default":null,"title":"Customer Id"},"customer_email":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Customer Email"},"success_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Success Url"},"cancel_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Cancel Url"},"return_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Return Url"},"metadata":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"default":null,"title":"Metadata"},"subscription_data":{"anyOf":[{"$ref":"#/components/schemas/SubscriptionData"},{"type":"null"}],"default":null},"allow_promotion_codes":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Allow Promotion Codes"},"ui_mode":{"anyOf":[{"enum":["hosted","embedded"],"type":"string"},{"type":"null"}],"default":null,"title":"Ui Mode"},"client_reference_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Client Reference Id"},"locale":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Locale"}},"required":["mode","currency","line_items"],"title":"StripeCheckoutSessionParams","type":"object"},"ModeEnum":{"enum":["subscription","payment"],"type":"string"},"LineItem":{"additionalProperties":false,"properties":{"price":{"pattern":"^price_","title":"Price","type":"string"},"quantity":{"default":1,"minimum":1,"title":"Quantity","type":"integer"},"adjustable_quantity":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Adjustable Quantity"}},"required":["price"],"title":"LineItem","type":"object"},"SubscriptionData":{"additionalProperties":false,"properties":{"metadata":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"default":null,"title":"Metadata"}},"title":"SubscriptionData","type":"object"},"MerchantSuppliedBuyer":{"additionalProperties":false,"description":"The ``sphere`` block: what Sphere needs to price and Stripe does not take.","properties":{"variant":{"const":"merchant_supplied","default":"merchant_supplied","title":"Variant","type":"string"},"customer_name":{"minLength":1,"title":"Customer Name","type":"string"},"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"},"locale":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Locale"}},"required":["customer_name","shipping_address"],"title":"MerchantSuppliedBuyer","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"},"CheckoutSessionResponse":{"description":"Stripe's session and Sphere's tax, kept apart as on the way in.","properties":{"stripe_account_id":{"title":"Stripe Account Id","type":"string"},"stripe":{"$ref":"#/components/schemas/StripeCheckoutSessionResult"},"sphere":{"$ref":"#/components/schemas/SphereTaxResult"}},"required":["stripe_account_id","stripe","sphere"],"title":"CheckoutSessionResponse","type":"object"},"StripeCheckoutSessionResult":{"description":"The Checkout Session as Stripe returned it. Redirect to ``url`` or mount\n``client_secret``; the amounts are Stripe's own arithmetic.","properties":{"id":{"title":"Id","type":"string"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Url"},"client_secret":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Client Secret"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Status"},"amount_subtotal":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Amount Subtotal"},"amount_tax":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Amount Tax"},"amount_total":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Amount Total"}},"required":["id"],"title":"StripeCheckoutSessionResult","type":"object"},"SphereTaxResult":{"description":"What Sphere put on the session to get those amounts.","properties":{"tax_calculation_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Tax Calculation Id"},"tax_rate_ids":{"items":{"type":"string"},"title":"Tax Rate Ids","type":"array"},"tax_lines":{"items":{"$ref":"#/components/schemas/TaxLine"},"title":"Tax Lines","type":"array"}},"title":"SphereTaxResult","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":{"post":{"operationId":"stripe_checkout_sessions_create","description":"Send Stripe's Checkout parameters under stripe, and the buyer Sphere needs to price under sphere. Sphere calculates tax, expresses it as Tax Rate objects in your account, creates the Checkout Session with those rates and returns it. Redirect to url (hosted) or mount client_secret (embedded) exactly as you do today. When the session completes, call the complete endpoint (or let Sphere's webhook do it) so renewals are taxed by Sphere.","summary":"Create a Stripe Checkout Session with Sphere tax applied","tags":["Stripe"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCheckoutSessionRequest"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/CreateCheckoutSessionRequest"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/CreateCheckoutSessionRequest"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutSessionResponse"}}},"description":""},"400":{"description":"Validation error, keyed by the failing field."},"403":{"description":"Missing/invalid API key, or Stripe account not enabled for Sphere tax."},"404":{"description":"No such connected Stripe account."},"409":{"description":"No address to calculate from, or Sphere could not calculate tax."},"502":{"description":"Stripe refused the Checkout Session."}}}}}}
```
