Update Subscription

SDK methods for subscription update (change plan) checkouts in the Limio SDK.

Subscription update checkouts let existing subscribers change their plan — upgrade, downgrade, or modify add-ons ( https://docs.limio.com/product/self-service/what-are-the-standard-functionality-of-limio-self-service-manage-my-account/how-to-configure-an-update-subscription-flow ) . They use a different flow from standard acquisition checkouts because the server drives the available next actions (effective dates, proration, removal side-effects).

Subscription update checkouts use order_type: "update_subscription". The SDK detects this automatically and routes mutations through the subscription update API.

How it works

1. From a subscription management page, call initiateCheckout with order_type: "update_subscription" and a forSubscription reference.

2. The server creates an update checkout session and returns a checkoutId.

3. Redirect the subscriber to the update checkout page with the checkoutId.

4. On the offer selection page, use selectOfferForSubscriptionUpdate to let the subscriber pick a new plan.

5. The server resolves effective dates, proration, and next actions, then returns the updated basket.

Starting an update checkout

Use initiateCheckout with order_type: "update_subscription" and the subscription ID. This creates the server-side update session.

import React from "react"
import { useBasket } from "@limio/sdk"

const SubscriptionUpdateButton = ({ subscription, updatePageUrl = "/update" }) => {
  const { initiateCheckout, basketLoading } = useBasket()

  const handleUpdate = async () => {
    const basket = await initiateCheckout({
      order: {
        order_type: "update_subscription",
        forSubscription: {
          id: subscription.id
        }
      }
    })

    const checkoutId = basket.order.checkoutId
    window.location.href = `${updatePageUrl}?basket=${checkoutId}`
  }

  return (
    <button onClick={handleUpdate} disabled={basketLoading}>
      Change plan
    </button>
  )
}

The forSubscription.id tells the server which subscription is being modified. The response includes the checkoutId used to track this update session.

---

Selecting a new offer

Once the update checkout session exists, use selectOfferForSubscriptionUpdate on the offer selection page. Only one offer can be active at a time — selecting a new offer resets the checkout and re-resolves server-side state.

await selectOfferForSubscriptionUpdate(orderItem: Partial<UpdateSubscriptionBasketItem>): Promise<void>

Parameters:

Field	Type	Description
offer	ElasticOffer	The offer the subscriber is switching to
quantity	number	Quantity (typically 1 for plan changes)

import React from "react"
import { useBasket } from "@limio/sdk"

const UpgradeOption = ({ offer, currentOfferId }) => {
  const { selectOfferForSubscriptionUpdate, clearOrderItems, basketLoading } = useBasket()

  const handleSelect = async () => {
    // Clear existing items first — the server will re-resolve
    // effective dates and side-effects for the new selection
    if (currentOfferId && currentOfferId !== offer.id) {
      clearOrderItems()
    }

    await selectOfferForSubscriptionUpdate({
      offer,
      quantity: 1
    })

    // Redirect to the update checkout page
    const params = new URLSearchParams(window.location.search)
    const checkoutId = params.get("basket")
    const ownerId = params.get("ownerId")
    window.location.assign(`/update?basket=${checkoutId}&ownerId=${ownerId}`)
  }

  return (
    <button onClick={handleSelect} disabled={basketLoading}>
      Select {offer.data.attributes.display_name__limio}
    </button>
  )
}

Selecting a new offer drops all existing order items and sends the new selection to the server. The server returns updated next actions, effective dates, and any proration details.

---

Clearing items before re-selection

When the subscriber changes their mind and picks a different offer, call clearOrderItems() before selectOfferForSubscriptionUpdate. This ensures the server re-resolves everything cleanly for the new selection.

const { clearOrderItems, selectOfferForSubscriptionUpdate } = useBasket()

// User changed their mind — clear and re-select
clearOrderItems()
await selectOfferForSubscriptionUpdate({ offer: newOffer, quantity: 1 })

clearOrderItems is a synchronous operation that empties the local basket state. The subsequent selectOfferForSubscriptionUpdate call syncs with the server.

---

Quantity updates in subscription update checkouts

updateItemQuantity behaves differently in subscription update checkouts. Instead of calling the standard basket API, it routes through the subscription update API so the server can recalculate proration and effective dates.

const { updateItemQuantity } = useBasket()

// In a subscription update checkout, this automatically
// uses the subscription update API under the hood
await updateItemQuantity(itemId, 3)

You don't need to handle this routing yourself — the SDK detects order_type: "update_subscription" and uses the correct endpoint.

---

Notes

• Start every update flow with initiateCheckout using order_type: "update_subscription" and forSubscription: { id }.

• Always call clearOrderItems() before selecting a different offer to avoid stale server state.

• The ownerId query parameter identifies which subscription is being updated — pass it through when redirecting.

• Server-driven state means the basket response may include fields not present in standard checkouts (effective dates, next actions, proration details).

• See Basket (Cart) for all other basket methods (adding items, promo codes, checkout navigation, etc.).