Self-Service Checkout

SDK methods for self-service checkouts — changing payment method or address on an existing subscription.

Self-service checkouts let existing subscribers modify their subscription details without contacting support. Currently two self-service order types are supported:

change_payment — Update the payment method on a subscription
change_address — Update the billing or delivery address on a subscription

Both use initiateCheckout with a forSubscription reference, similar to Update Subscription checkouts. The server creates a self-service checkout session and pre-populates the basket with the subscription's current details.

Self-service checkouts use the same initiateCheckout method as standard and update subscription checkouts. The SDK routes the request based on order_type.

Change payment method

Use initiateCheckout with order_type: "change_payment" to start a payment method update flow. The basket is pre-populated with the subscriber's current billing details.

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

const ChangePaymentButton = ({ subscription, checkoutPageUrl = "/checkout" }) => {
  const { initiateCheckout, basketLoading } = useBasket()

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

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

  return (
    <button onClick={handleChangePayment} disabled={basketLoading}>
      Change payment method
    </button>
  )
}

Change address

Use initiateCheckout with order_type: "change_address" to start an address update flow. The type field specifies whether the subscriber is updating their billing or delivery address.

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

const ChangeAddressButton = ({ subscription, addressType, checkoutPageUrl = "/checkout" }) => {
  const { initiateCheckout, basketLoading } = useBasket()

  const handleChangeAddress = async () => {
    const basket = await initiateCheckout({
      order: {
        order_type: "change_address",
        type: addressType, // "billing" or "delivery"
        forSubscription: {
          id: subscription.id
        }
      }
    })

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

  return (
    <button onClick={handleChangeAddress} disabled={basketLoading}>
      Change {addressType} address
    </button>
  )
}

Parameters:

Field

Type

Description

order_type

"change_address"

Identifies this as an address change checkout

type

"billing" | "delivery"

Which address to update

forSubscription.id

string

The subscription being modified

The basket response includes pre-populated address data from the subscription:

billingDetails — Current billing address
deliveryDetails — Current delivery address (empty object if none exists)

These are available in the checkout form via PREFILL_ORDER_PROPERTIES, so form fields are automatically pre-filled with the subscriber's existing address.

Pre-populated basket data

Both self-service checkout types return a basket pre-populated with the subscriber's current details. This means the checkout form can display existing values for the subscriber to review and edit, rather than requiring them to re-enter everything.

const basket = await initiateCheckout({
  order: {
    order_type: "change_address",
    type: "billing",
    forSubscription: { id: subscription.id }
  }
})

// basket.order contains:
// - billingDetails: { address1, city, state, postalCode, country, ... }
// - deliveryDetails: { address1, city, state, postalCode, country, ... }
// - customerDetails: { firstName, lastName, email, ... }

Notes

Both change_payment and change_address follow the same flow: create a self-service basket via initiateCheckout, redirect to the checkout page, and submit the form.
The forSubscription.id tells the server which subscription is being modified.
Address data is pre-populated from the subscription's current addresses. If a delivery address doesn't exist on the subscription, deliveryDetails defaults to an empty object.
Self-service checkouts use the same underlying API as Update Subscription checkouts (POST /api/mma/checkout).

Good evening