Skip to content
Create account
 or
Sign in
The Stripe Docs logo
/
Create account
Sign in
OverviewUpgrade your integration
Online payments
OverviewFind your use case
Payment methods
Payment interfaces
Payment scenarios
In-person payments
Other Stripe products

Dynamically update line itemsPrivate preview

Update line items in response to changes made during checkout

Beta

This feature is in private beta. Request access to dynamic updates to checkout.

Learn how to dynamically add, remove, or update products included in a Checkout Session and confirm line item changes server-side, such as quantity updates or the addition or removal of line items.

Possible use cases include:

  • Inventory checks: Run inventory checks and holds when customers attempt to change item quantities.
  • Add new products: Add a complimentary product if the order total exceeds a specific amount.
  • Update shipping rates: If the order total changes, update shipping rates by combining the method described in this guide with what’s out on Customize shipping options during checkout.
  • Update tax rates: If you’re not using Stripe Tax, you can dynamically update tax rates on line items based on the shipping address entered.

Limitations

  • Only supported in payment mode.
  • Doesn’t support price_data as a line_items parameter on Update yet.
  • Doesn’t support updates in response to changes from outside of the checkout page.
  • Doesn’t work with Adaptive Pricing yet. If you enable Adaptive Pricing and use this feature, sessions won’t localize to the buyer’s currency.

Set up Stripe
Server-side

First, you need a Stripe account. Register now.

Use our official libraries to access the Stripe API from your application:

Command Line
# Install with npm
npm install stripe@17.5.0-beta.1 --save

Set the SDK to use the checkout_server_update_beta=v1 beta version header.

const stripe = require('stripe')(
'sk_test_4eC39HqLyjWDarjtT1zdp7dc'
, {
  apiVersion: '2024-11-20.acacia; checkout_server_update_beta=v1',
});

Create a Checkout Session
Server-side

From your server, create a Checkout Session.

By default, the Stripe Checkout client automatically updates the line_items of the Checkout Session object with the updates the customer makes during the session such as modifying the quantity, removing a line item, or adding a cross-sell.

Warning

When permissions.update.line_items is server_only, it disables the automatic client-side update and only your server can update the line items using your Stripe secret key.

server.js
const express = require('express');
const app = express();

app.post('/checkout', async (req, res) => {
  const session = await stripe.checkout.sessions.create({
    ui_mode: 'embedded',
    permissions: {
      update: {
        line_items: 'server_only',
      }
    },
    line_items: [
      {
        // Provide the exact Price ID (for example, pr_1234) of the product you want to sell
        price: '{{PRICE_ID}}',
        quantity: 1,
      },
    ],
    mode: 'payment',
    return_url: `${YOUR_DOMAIN}/return?session_id={CHECKOUT_SESSION_ID}`,
  });

  res.json({clientSecret: session.client_secret});
});

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

Dynamically update line items
Server-side

From your server, create a new endpoint to recompute the line items based on the updates the customer made.

  1. Retrieve the Checkout Session using the checkoutSessionId from the request body.
  2. Validate the customer’s line items from the request body.
  3. Recompute the customer’s new line items based on the line item updates they made in the Checkout UI.
  4. Update the Checkout Session with the customer’s new line_items.
server.js
function validateLineItems(lineItems) {
  // Implement this function to validate the line items the customer has entered.
}

function recomputeLineItems(lineItems, session) {
  // Implement this function to recompute the customer's new line items based on
  // the line item updates they made in the Checkout UI.
}

app.post('/update-line-items', async (req, res) => {
  const {checkout_session_id, line_items} = req.body;

  // 1. Retrieve the Checkout Session
  const session = await stripe.checkout.sessions.retrieve(checkout_session_id,
    {
      // Line items are not included on the API resource by default unless expanded
      expand: ['line_items']
    }
  );

  // 2. Validate the line items
  if (!validateLineItems(line_items)) {
    return res.json({type: 'error', message: 'Your line items are invalid. Please refresh your session.'});
  }

  // 3. Recompute the line items
  const lineItems = recomputeLineItems(line_items, session);

  // 4. Update the Checkout Session with the new line items
  if (lineItems) {
    await stripe.checkout.sessions.update(checkout_session_id, {
      line_items: lineItems,
    });

    return res.json({type:'object', value: {succeeded: true}});
  } else {
    return res.json({type:'error', message: "We could not update your line items. Please try again."});
  }
});

Mount Checkout
Client-side

Checkout is available as part of Stripe.js. Include the Stripe.js script on your page by adding it to the head of your HTML file. Next, create an empty DOM node (container) to use for mounting.

index.html
<head>
  <script src="https://js.stripe.com/v3/"></script>
</head>
<body>
  <div id="checkout">
    <!-- Checkout will insert the payment form here -->
  </div>
</body>

Initialize Stripe.js with your publishable API key, passing in the embedded_checkout_byol_beta_1 beta.

index.js
// Set your publishable key: remember to change this to your live publishable key in production
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx'
, {
  betas: ['embedded_checkout_byol_beta_1']
});;

Create an asynchronous fetchClientSecret function that makes a request to your server to create the Checkout Session and retrieve the client secret.

Create an asynchronous onLineItemsChange function that makes a request to your server to recompute the customer’s new line items based on the line item updates they made in the Checkout UI. Stripe Checkout calls the function when the customer modifies the quantity of a line item, removes a line item, or adds a cross-sell.

index.js
initialize();

async function initialize() {
  // Fetch Checkout Session and retrieve the client secret
  const fetchClientSecret = async () => {
    const response = await fetch("/create-checkout-session", {
      method: "POST",
    });
    const { clientSecret } = await response.json();
    return clientSecret;
  };

  // Call your backend to update line items
  const onLineItemsChange = async (lineItemsChangeEvent) => {
    const {checkoutSessionId, lineItems} = lineItemsChangeEvent;
    const response = await fetch("/update-line-items", {
      method: "POST",
      body: JSON.stringify({
        checkout_session_id: checkoutSessionId,
        line_items: lineItems,
      })
    })

    if (response.type === 'error') {
      return Promise.resolve({type: "reject", errorMessage: response.message});
    } else {
      return Promise.resolve({type: "accept"});
    }
  };

  // Initialize Checkout
  const checkout = await stripe.initEmbeddedCheckout({
    fetchClientSecret,
    onLineItemsChange,
  });

  // Mount Checkout
  checkout.mount('#checkout');
}

Caution

Always return a Promise from your onLineItemsChange function and resolve it with a ResultAction object.

The Checkout client updates the UI based on the result of your onLineItemsChange function.

  • When the result has type: "accept", the Checkout UI renders the line items that you set from your server.
  • When the result has type: "reject", the Checkout UI shows the error message that you set in the result.

Checkout renders in an iframe that securely sends payment information to Stripe over an HTTPS connection.

Common mistake

Avoid placing Checkout within another iframe because some payment methods require redirecting to another page for payment confirmation.

Test the integration

Follow these steps to test your integration, and ensure your dynamic line items work correctly.

  1. Set up a test environment that mirrors your production setup. Use your Stripe test mode API keys for this environment.

  2. Simulate various line item updates to verify that your recomputeLineItems function handles different scenarios correctly.

  3. Verify server-side logic by using logging or debugging tools to confirm that your server:

    • Retrieves the Checkout Session.
    • Validates line items.
    • Recomputes updated line items.
    • Updates the Checkout Session with the new line items when your custom conditions are met. Make sure the update response contains the new line items. By default, the response doesn’t contain the line items field, unless the request expands the object.

  4. Verify client-side logic by completing the checkout process multiple times in your browser. Pay attention to how the UI updates after making a line item change. Make sure that:

    • The onLineItemsChange function is called when expected. It’s called whenever a customer modifies the quantity, removes a line item, or adds a cross-sell.
    • Line items update correctly based on the customer’s line item updates.
    • Error messages display properly when an update failed.

  5. Pass through invalid line items or simulate server errors to test error handling, both server-side and client-side.

Was this page helpful?
YesNo
Need help? Contact Support.
Join our early access program.
Check out our product changelog.
Questions? Contact Sales.
Powered by Markdoc
On this page
Set up Stripe
Create a Checkout Session
Dynamically update line items
Mount Checkout
Test the integration
Products Used
Checkout
Payments