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) {
      await 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, await 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
await clearOrderItems()
await selectOfferForSubscriptionUpdate({ offer: newOffer, quantity: 1 })

clearOrderItems is asynchronous. It sends a remove action for every item in the basket to the server and updates the basket state with the response, so it must be awaited before you select the new offer.

---

Adding items to a subscription update checkout

Use addSubscriptionOrderItem to append an order item to the subscription update basket. Unlike selectOfferForSubscriptionUpdate (which replaces all items), this method is additive — it keeps existing items and appends the new one.

The caller constructs the full order item shape, giving visibility and control over what's being added.

await addSubscriptionOrderItem(orderItem: UpdateSubscriptionBasketItem): Promise<void>

Parameters:

Field	Type	Description
orderItemActionType	string	The action type (e.g. "update" for quantity changes)
offer	Offer	The offer being modified
quantity	number	The target quantity

The server resolves the effective date based on the direction of the quantity change. Increases take effect immediately; decreases take effect at end-of-term.

Example — seat quantity update flow:

A common pattern is to use addSubscriptionOrderItem when initially adding a quantity change to the basket, then updateItemQuantity for subsequent adjustments to items already in the basket.

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

const SeatQuantityUpdater = ({ subscription, subscriptionOffer }) => {
  const {
    initiateCheckout,
    addSubscriptionOrderItem,
    updateItemQuantity,
    orderItems,
    basketLoading
  } = useBasket()
  const [quantityUpdates, setQuantityUpdates] = useState([])

  // Step 1: Start the update checkout session if not already initiated
  const handleInitiate = async () => {
    const { nextActions } = await initiateCheckout({
      order: {
        order_type: "update_subscription",
        forSubscription: { id: subscription.id }
      }
    })
    // The server returns available quantity updates for the subscription
    setQuantityUpdates(nextActions.quantityUpdates ?? [])
  }

  // Step 2: Add a quantity change to the basket (item not yet in basket)
  const handleAddQuantityUpdate = async (offer, newQuantity) => {
    await addSubscriptionOrderItem({
      orderItemActionType: "update",
      offer,
      quantity: newQuantity
    })
  }

  // Step 3: Adjust quantity of an item already in the basket
  const handleAdjustQuantity = async (itemId, newQuantity) => {
    await updateItemQuantity(itemId, newQuantity)
  }

  return (
    <div>
      <button onClick={handleInitiate} disabled={basketLoading}>
        Manage seats
      </button>

      {/* Show available quantity updates from the server */}
      {quantityUpdates.map((item, i) => (
        <div key={item.id ?? i}>
          <span>Current seats: {item.currentQuantity}</span>
          <button
            disabled={basketLoading}
            onClick={() => handleAddQuantityUpdate(item, 10)}
          >
            Set to 10 seats
          </button>
        </div>
      ))}

      {/* Show items already in the basket with quantity adjustment */}
      {orderItems.map((item) => (
        <div key={item.id}>
          <span>Seats: {item.quantity}</span>
          <button
            disabled={basketLoading}
            onClick={() => handleAdjustQuantity(item.id, item.quantity + 1)}
          >
            Add seat
          </button>
        </div>
      ))}
    </div>
  )
}

When to use which method:

Scenario	Method
Item is not yet in the basket	addSubscriptionOrderItem
Item is already in the basket	updateItemQuantity
Selecting a completely new plan (replaces all)	selectOfferForSubscriptionUpdate
Removing an offer from the subscription	addSubscriptionOrderItem with orderItemActionType: "remove"

Your component has access to orderItems and nextActions.quantityUpdates to determine which method to use.

---

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.

---

Removing an offer from a subscription

Use addSubscriptionOrderItem with orderItemActionType: "remove" to remove an offer from a multi-offer subscription without cancelling the subscription. The removed offer stays active and billed until the end of the current term — the same effective-date semantics as a downgrade.

Offer removal is available from Release 116.

await addSubscriptionOrderItem({
  orderItemActionType: "remove",
  type: "subscription_offer",
  offer: subscriptionOffer
})

Parameters:

Field	Type	Description
orderItemActionType	"remove"	Marks this item as an offer removal
type	"subscription_offer"	Identifies the item as an existing offer on the subscription
offer	Offer	The subscription offer being removed

Example — removal flow:

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

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

  const handleRemove = async () => {
    // 1. Start the update checkout session
    const basket = await initiateCheckout({
      order: {
        order_type: "update_subscription",
        forSubscription: { id: subscription.id }
      }
    })

    // 2. Add one removal item per offer — batch all removals
    //    into this single order
    for (const offer of offersToRemove) {
      await addSubscriptionOrderItem({
        orderItemActionType: "remove",
        type: "subscription_offer",
        offer
      })
    }

    // 3. Send the subscriber to the update checkout page to
    //    review and submit the order
    window.location.href = `${updatePageUrl}?basket=${basket.order.checkoutId}`
  }

  return (
    <button onClick={handleRemove} disabled={basketLoading}>
      Remove selected offers
    </button>
  )
}

Rules the server enforces:

• A subscription always keeps at least one active offer. An order that would remove every offer is rejected. An offer added in the same order offsets a removal, so swapping (remove one offer, add another) passes.
• Removals take effect at the end of the current term. In a mixed order (for example a removal plus a quantity change), the removal drives the whole order's effective date to term-end, so the offer is never stripped immediately. The exception is a swap: when an offer is added in the same order, the effective date follows the added offer's upgrade or downgrade classification instead.
• Batch all removals into a single order. Submitting an update order sets a pending change on the subscription that blocks further update checkouts until the effective date passes, so sequential removal orders are not possible.

---

Notes

• Start every update flow with initiateCheckout using order_type: "update_subscription" and forSubscription: { id }.
• Always await 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.).