Dynamically update line itemsPrivate preview

Update line items in response to changes made during checkout.

Private preview

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

Learn how to dynamically add, remove, or update line items included in a Checkout Session.

Use cases

This guide demonstrates how to update line items to upsell a subscription, but you can also:

Check inventory: 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.

Set up SDK
Server-side

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

Update server SDK
Server-side

To use this beta, first update your SDK to use the checkout_server_update_beta=v1 beta version header.

Configure Checkout Session update permissions
Server-side

Pass in permissions.update_line_items=server_only when you create the Checkout Session to enable updating line items from your server. Passing this option will also disable client-side updates to line items, such as updateLineItemQuantity, ensuring that all updates pass through your server.

Dynamically update line items
Server-side

Create a new endpoint on your server to update the line items on the Checkout Session. You’ll call this from the frontend in a later step.

Security tip

It’s essential to understand that client-side code runs in an environment fully controlled by the user. A malicious user can bypass your client-side validation, intercept, and modify requests, or even craft entirely new requests to your server.

When designing the endpoint, we recommend the following:

Design endpoints for specific customer interactions instead of making them overly generic (for example, “add cross-sell item” rather than a general “update” action). Specific endpoints help keep the purpose clear and make validation logic easier to write and maintain.
Avoid passing Session data directly from the client to your endpoint. Malicious clients can modify request data, making it an unreliable source for determining the Checkout Session state. Rather, pass the session ID to your server and use it to securely retrieve the data from Stripe’s API.

When updating line items, you must retransmit the entire array of line items.

To keep an existing line item, specify its id.
To update an existing line item, specify its id along with the new values of the fields to update.
To add a new line item, specify a price and quantity without an id.
To remove an existing line item, omit the line item’s ID from the retransmitted array.
To reorder a line item, specify its id at the desired position in the retransmitted array.

Update client SDK
Client-side

Initialize stripe.js with the custom_checkout_server_updates_1 beta header.

checkout.js
const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx'
, {
  betas: ['custom_checkout_server_updates_1'],
});

Invoke server updates
Client-side

Trigger the update from your front end by making a request to your server, and wrapping it in runServerUpdate. If the request is successful, the Session object updates with the new line items.

index.html
<button id="change-subscription-interval" role="switch" aria-checked="false">
  Save with a yearly subscription
</button>

checkout.js
document.getElementById('change-subscription-interval')
  .addEventListener("click", async (event) => {
    const button = event.target;
    const isCurrentSubscriptionMonthly =
      button.getAttribute("aria-checked") === "false";

    const updateCheckout = () => {
      return fetch("/change-subscription-interval", {
        method: "POST",
        headers: {
          "Content-type": "application/json",
        },
        body: JSON.stringify({
          checkout_session_id: checkout.session().id,
          interval: isCurrentSubscriptionMonthly ? "yearly" : "monthly",
        })
      });
    };

    const response = await checkout.runServerUpdate(updateCheckout);
    if (!response.ok) {
      // Handle error state
      return;
    }

    // Update toggle state on success
    const isNewSubscriptionMonthly = !isCurrentSubscriptionMonthly;
    button.setAttribute("aria-checked", !isNewSubscriptionMonthly);
    button.textContent = isNewSubscriptionMonthly
      ? "Save with a yearly subscription"
      : "Use monthly subscription";
  });

Dynamically update line itemsPrivate preview

Update line items in response to changes made during checkout.

Private preview

Use cases

Set up SDKServer-side

Update server SDKServer-side

Configure Checkout Session update permissionsServer-side

Dynamically update line itemsServer-side