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

The Checkout Sessions API

Use the Checkout Sessions API for a Stripe payments with built-in support for common features.

Use the Checkout Sessions API to build a payments integration with built-in support for tax calculation, discounts, subscriptions, shipping, and currency conversion. Stripe recommends this API for most payments integrations because it handles complex checkout tasks for you, enables powerful features like Adaptive Pricing, and reduces the amount of custom code you need to write and maintain.

The Checkout Sessions API serves as the backend for multiple Stripe payment UIs:

To get started, see the Checkout Sessions quickstart. It walks through creating a Checkout Session on the server, using its client_secret with Stripe Elements on the client.

A prebuilt, extensible checkout

The Checkout Sessions API manages the full checkout lifecycle for you. Some of the advantages of using the Checkout Sessions API include:

FeatureDescription
Built-in checkout featuresTax calculation, discounts, shipping, subscriptions, and Adaptive Pricing are available without additional API integrations.Automatic authentication handlingStripe manages 3D Secure authentication, and other required customer actions.Flexible payment UIsUse a Stripe-hosted page, an embedded form, or fully custom Stripe Elements to match your brand.Managed checkout stateStripe tracks the session state, including expiration and status, so you don’t have to.No double chargesThe API prevents duplicate charges by tracking the session lifecycle.

The Checkout Sessions API covers similar payment scenarios as the Payment Intents API, but the Checkout Sessions API requires significantly less code. Use the Payment Intents API if you need to control every aspect of the checkout state or if you plan to build discount, tax, subscription, and currency conversion logic yourself. To determine which is right for your integration, compare the two.

Checkout lifecycle

The Checkout Sessions API manages the full checkout lifecycle for you, with the lifecycle varying depending on the payment UI you use.

Store information in metadata

Stripe supports adding metadata to most requests, including requests to the Checkout Sessions API. Use metadata to associate your own identifiers (such as order IDs) with Stripe sessions. Metadata is visible in the Dashboard and available in reports, making it easier to reconcile payments.

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
:" \
  -d mode=payment \
  -d ui_mode=custom \
  --data-urlencode return_url="https://example.com/return" \
  -d "metadata[order_id]"=6735

Don’t store sensitive information (such as personally identifiable information or card details) as metadata.

See also

On this page