Dynamically update line items

Learn how to modify pricing and the contents of a cart during checkout.

Private preview

Dynamic updates 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.

Payment Intents API

If you use the Payment Intents API, you must manually track line item updates and modify the payment amount, or by creating a new PaymentIntent with adjusted amounts.

Set up the SDK
Server-side

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

Update the server SDK
Server-side

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

Configure update permissions for the Checkout Session
Server-side

When you create the Checkout Session, pass the permissions.update_line_items=server_only option to disable client-side updates and to enable updating line items, such as updateLineItemQuantity, from your server.

Dynamically update line items
Server-side

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

Security tip

Client-side code runs in an environment that’s controlled by the user. A malicious user can bypass your client-side validation, intercept and modify requests, or create new requests to your server.

When creating an endpoint, we recommend the following:

Create endpoints for specific customer interactions instead of making them generic. For example, “add cross-sell items” instead of a general “update” action. Specific endpoints can help with writing and maintaining validation logic.
Don’t pass 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. Instead, pass the session ID to your server and use it to securely retrieve the data from the Stripe 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 the 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'],
});

Request server updates
Client-side

From your front end, send an update request to your server and wrap it in runServerUpdate. A successful request updates the Session object 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 items

Learn how to modify pricing and the contents of a cart during checkout.

Private preview

Use cases

Payment Intents API

Set up the SDKServer-side

Update the server SDKServer-side

Configure update permissions for the Checkout SessionServer-side

Dynamically update line itemsServer-side