User, Subscription, Invoice & Address

This page describes all of the user and subscription methods available within the Limio SDK.

In the context of Limio Self-Service, authenticated users can view and manage their subscriptions directly through a self-service portal. To support this, the Limio SDK provides a set of hooks and utility functions that allow developers to retrieve and display real-time data about the user, their subscriptions, payment schedules, and account information.

These SDK methods are essential for building authenticated experiences such as:

• Account overviews and profile displays

• Subscription management and renewal flows

• Billing and invoice history pages

• Displaying upcoming charges and subscription status

This page covers the most commonly used methods, including:

• useUser – Retrieve the logged-in user's profile (e.g. email, authentication status)

• useSubscriptions – Access the list of subscriptions linked to the user

• useSubInfo – Extract subscription metadata such as status, quantity, and pending changes

• useUserInvoices – Retrieve billing invoices directly from Zuora

• getCurrentAddress – Get the user's active billing or delivery address

• getCurrentOffer, getPeriodForOffer – Understand the current subscription offer and billing frequency

• checkCurrentSchedule, getRenewalDateForUserSubscription, getPriceForUserSubscription – Display billing details, upcoming payments, and pricing

• useSchedule - Access key dates date prices from a given subscription schdule.

These methods power the Manage My Account journey and other post-purchase experiences in Limio Self-Service.

For more background on Limio Self-Service, see:

• Overview of Limio Self-Service Journeys

useUser -Retrieving details of the current user

If you need to find out if a user is validated and get some details about that user, including Subscription you can use the useUser method.

Example to display authenticated user's email in a navigation bar:

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

const Navbar = () => {
  const user = useUser()
  const { email } = user
  
  return (
    <nav>
      <h1>Shop</h1>
      <ul>
        <li>
          <p>Logged in as { email }</p>
        </li>
        <li>
          <button>Log Out</button>
        </li>
      </ul>
    </nav>
  )
}

Example to display an authenticated user's Subscriptions and the Status of those Subscriptions, as well as upcoming payments:

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

const Subscriptions = () => {
  const { subscriptions } = useSubscriptions()
  
  return (
    <div>
      <h1>Subscriptions</h1>
      <ul>
        {
          subscriptions.map(({ name, status, schedule }) => (
            <li>
              <div>
                <h2>{ name }</h2>
                <span>{ status }<span>
              </div>
              <div>
                <ul>
                  {
                    schedule.map(({ data: { date, amount, description } }) => (
                      <li>
                        <h3>{ description }</h3>
                        <div>
                          <p>{ new Date(date).toLocaleDateString() }</p>
                          <p>{ amount }</p>
                        <div>
                      </li>
                    ))
                  }
                </ul>
              </div>
            <li>
          ))
        }
      <ul>
    </div>
  )
}

Example user:

{
  attributes: {
    aud: "3kde1g4qurqbdmf7p81n6568m0",
    auth_time: 1610643100,
    "cognito:username": "dummy_user",
    email: "[e-mail]",
    email_verified: true,
    event_id: "743826f5-075c-4c36-8bb2-bf343be46f09",
    exp: 1611848843,
    iat: 1611845243,
    iss: "https://cognito-idp.eu-central-1.amazonaws.com/eu-central-1_AVrsbOxSU",
    sub: "d183e0ec-8baf-4320-b847-c78fad0b1df8",
    token_use: "id"
  },
  subscriptions: [
    {
      name: "Limio Monthly",
      data: {},
      status: "active",
      record_type: "subscription",
      owner: "id-hfmd3qJIYU8XZZo-5JI2UOkdacXd0JXBYlptgRGcLMM",
      customer: "cus-VsmB6KhU_PTTTGzgvY51Vk2dy5Hf6dLnIX4NitMaK4I",
      id: "sub-34cb9ce9a3777a164bb1ad471f20a83b",
      service: "limio",
      ref: "order-23b46e1b8f4c23f5ecd7151437afb4b6/a85cbcf1-fcbc-4320-be3f-eaacaaff578f",
      created: "2022-06-09T12:44:38.771Z",
      reference: "1KPEEEJ8RNF8",
      mode: "production"
      offers: [
        {
          name: "Limio Monthly",
          quantity: 1,
              price: {
                summary: {
                  headline: "£20/month"
                },
                currency: "GBP",
                amount: 1
              },
              products: [],
              termEndDate: "2022-09-02T10:25:01.000Z",
              attributes: {
                autoRenew__limio: true
              }
            }
          }
      ],
      schedule: [
        {
          data: {
            date: "2022-06-09T12:44:38.771Z",
            reference: "a85cbcf1-fcbc-4320-be3f-eaacaaff578f_charge0",
            description: "Limio Monthly",
            amount: "20.00",
            currency: "GBP",
            type: "payment"
          },
          status: "pending",
          record_type: "schedule",
          related: "sub-34cb9ce9a3777a164bb1ad471f20a83b",
          owner: "id-hfmd3qJIYU8XZZo-5JI2UOkdacXd0JXBYlptgRGcLMM",
          id: "schedule-46f188d94a8b0b1ef39ee1afbbebfb99",
          service: "limio",
          created: "2022-06-09T12:44:38.771Z",
          reference: "26U64DIIKB1G",
          mode: "production"
        },
        {
          data: {
            date: "2022-07-09T12:44:38.771Z",
            reference: "a85cbcf1-fcbc-4320-be3f-eaacaaff578f_charge0",
            description: "Limio Monthly",
            amount: "20.00",
            currency: "GBP",
            type: "payment"
          },
          status: "pending",
          record_type: "schedule",
          related: "sub-34cb9ce9a3777a164bb1ad471f20a83b",
          owner: "id-hfmd3qJIYU8XZZo-5JI2UOkdacXd0JXBYlptgRGcLMM",
          id: "schedule-f0899162c4c161a0f8c2535dd1526334",
          service: "limio",
          created: "2022-06-09T12:44:38.771Z",
          reference: "7GH68M5H61C0",
          mode: "production"
        }
      ]
    }
  ],
  loginStatus: "logged-in"
  loaded: true,
  token:
    "eyJraWQiOiJrdHFNMjE0WnlZRlhRVklEMGRCUTJ3Y1NRUThtMytJU1QwUHoyc0YyUGVZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJkMTgzZTBlYy04YmFmLTQzMjAtYjg0Ny1jNzhmYWQwYjFkZjgiLCJldmVudF9pZCI6Ijc0MzgyNmY1LTA3NWMtNGMzNi04YmIyLWJmMzQzYmU0NmYwOSIsInRva2VuX3VzZSI6ImFjY2VzcyIsInNjb3BlIjoiYXdzLmNvZ25pdG8uc2lnbmluLnVzZXIuYWRtaW4iLCJhdXRoX3RpbWUiOjE2MTA2NDMxMDAsImlzcyI6Imh0dHBzOlwvXC9jb2duaXRvLWlkcC5ldS1jZW50cmFsLTEuYW1hem9uYXdzLmNvbVwvZXUtY2VudHJhbC0xX0FWcnNiT3hTVSIsImV4cCI6MTYxMTg0ODg0MywiaWF0IjoxNjExODQ1MjQzLCJqdGkiOiIxNGZlMmVmMi1lYTM5LTQ3ZjItYmNlYS00YzkwOWJjMGQzNmMiLCJjbGllbnRfaWQiOiIza2RlMWc0cXVycWJkbWY3cDgxbjY1NjhtMCIsInVzZXJuYW1lIjoiZDE4M2UwZWMtOGJhZi00MzIwLWI4NDctYzc4ZmFkMGIxZGY4In0.coUsZ637mhna85v0uFtWVKOgG084xOlihyXABx5fmOcJBWXl9tJWgUDwH_7p5VYa_hCFf9mUzS-BPn7TgApBN99Hf6EXbTfWyD28yjynaNDhLu_yBie6g_FxVI_ovhsz-vdKZ8kaW5pUvbqQxnfhK-UmdMhCs4-CGldpNvYTWQqQT7epyI0luMtWht3BLhlyAndHhcCmoO59dLCCejvODl7tmBas2C1Po-UOU-MqQ3S4M5WQ_FEwAWdBK9laTfVqF2wOkMGqapDfAPFGrH0lDDld5USTJCeZOTqkx7RE6pk2xONVNNxwVTiNJN0C2CKbWv97UL2HG1h41PrC9UQ6ec"
}

useSubInfo - Getting details from the a subscription

useSubInfo

Extracts and returns key subscription information such as status, gift status, quantity, whether the subscription has lapsed, and if there are any pending changes.

import { useSubInfo } from "@limio/sdk/subscription"

const { status, isGift, quantity, hasLapsed, hasPendingChange } = useSubInfo(subscription);

Returns:

• SubInfo An object containing:

  • status: string: The current status of the subscription.

  • isGift: boolean: Whether the subscription is a gift.

  • quantity: number: The quantity associated with the subscription.

  • hasLapsed: boolean | undefined: Whether the subscription has lapsed.

  • hasPendingChange: boolean: Whether there is a pending change scheduled for the subscription.

useUserInvoices - Getting the user's invoices

To get all of the account level invoices from Zuora, Limio exposes a hook, useUserInvoices. When called this will retrieve ever invoice from the users account. Example usage:

const { invoices, revalidate, mutate } = useUserInvoices()

The invoices are an array of unaltered invoice objects from Zuora. See here for further information on the data structures of each invoice.

getCurrentAddress - Getting the user's address

getCurrentAddress

Checks a Limio Address Object to find and return the active billing or delivery address associated with a customer account.

import { getCurrentAddress } from "@limio/sdk/address";

const { data: deliveryAddress } = getCurrentAddress("delivery", addresses);
const { data: billingAddress } = getCurrentAddress("billing", addresses);

Parameters:

• type: string (required) The type of address to retrieve. Can be "billing" or "delivery".

• addresses: LimioAddressObject (required) An array containing the customer's associated address objects, typically including both billing and delivery addresses.

Returns:

• LimioAddressObject: An object containing the data of the active address matching the specified type. The returned object usually includes the full address details such as street, city, postal code, and country.

Example LimioAddressObject

{
  "firstName": "John",
  "lastName": "Doe",
  "country": "GB",
  "city": "London",
  "address1": "123 Central Lane",
  "postalCode": "N5 5TY"
}

Subscription helpers

getPriceFromSchedule

Retrieves the price from a Limio schedule item and returns an object containing the price value and currency code. It can also take into account the country code, which may influence the price calculation.

import { getPriceFromSchedule } from "@limio/sdk/subscription";

const prevPrice = getPriceFromSchedule(prevSchedule);
const nextPrice = getPriceFromSchedule(nextSchedule, customerAddresses?.billingAddress?.country);

console.log(nextPrice); // Output: { value: "12.49", currencyCode: "GBP" }

Parameters:

• schedule: LimioScheduleItem An object representing a schedule item within a Limio subscription.

• country: string (optional) An alpha-2 country code that may be used to adjust the price based on the country.

Example LimioScheduleItem:

  {
    date: "2022-06-09T12:44:38.771Z",
    schedule_date: "2022-06-09T12:44:38.771Z",
    type: "payment",
    description: "Limio Monthly",
    amount: "20.00",  
    "taxAmount": 0,
    amountWithoutTax: "20.00",
    currency: "GBP",
    lineItems: [
      amountWithoutTax: "20.00",
      processingType: "Charge",
      taxAmount: "0.00",
      chargeDescription: "",
      chargeName: "Limio Monthly Charge",
      productName: "Limio Monthly",
      quantity: 1
    ],
    quantity: 1,
    reference: "",
    unit_amount: "20.00"
}

Returns:

• { value: string, currencyCode: string } An object containing:

  • value: string: The price value extracted from the schedule item.

  • currencyCode: string: The currency code associated with the price.

getCurrentOffer

Returns the current active offer associated with a user's subscription. Useful for retrieving details about the active promotional or pricing offer that applies to the subscription.

import { getCurrentOffer } from "@limio/sdk/offers";

const offer = getCurrentOffer(userSubscription);

Parameters:

• userSubscription: LimioUserSubscription An object representing the user's subscription, including any associated offers.

Returns:

• LimioOffer: An object representing the current active offer associated with the subscription. The offer object typically includes details such as pricing, terms, and conditions.

getPeriodForOffer

Returns the billing period of a LimioOffer object, indicating the duration or frequency of the offer's billing cycle. If the offer is a one-off charge (non-recurring), it returns "N/A".

This function can be used in conjunction with getCurrentOffer to retrieve the billing period of the user's current offer.

import { getCurrentOffer, getPeriodForOffer } from "@limio/sdk/offers";

// Retrieve the current offer for the user's subscription
const offer = getCurrentOffer(userSubscription);

// Get the billing period of the current offer
const period = getPeriodForOffer(offer);

console.log(`The billing period of the current offer is: ${period}`);

Parameters:

• offer: LimioOfferObject An object representing a Limio offer, containing details such as its billing cycle, price, and attributes.

Returns:

• A string representing the period of the offer (e.g., "1 month"), or "N/A" if the offer is a one-off charge or does not auto-renew.

Example Output:

• "1 month" if the offer is recurring monthly.

• "N/A" if the offer is a one-off charge or evergreen.

checkCurrentSchedule

Determines the next applicable schedule from the existing schedules for a subscription. Useful for displaying information such as the next bill date and price.

import { checkCurrentSchedule } from "@limio/sdk/subscription";


const nextSchedule = checkCurrentSchedule(schedules);

Parameters:

• schedules: Array An array of schedule objects associated with the subscription. Each schedule object typically includes a status and a data.date.

Returns:

• schedule: Array Returns the next applicable schedule object based on the provided parameters, or null/undefined if no suitable schedule is found.

getRenewalDateForUserSubscription

Retrieves and returns the renewal date for a user's subscription, formatted according to the default date format defined in the Limio App settings.

import { getRenewalDateForUserSubscription } from "@limio/sdk/subscription";

const renewalDate = getRenewalDateForUserSubscription(userSubscription);

console.log(renewalDate) // Output: "14 Dec 2024"

Parameters:

• userSubscription: UserSubscription An object containing the user's subscription details, such as status, schedule, and term end date.

Returns:

• A string representing the formatted renewal date of the user's subscription. Possible return values include:

  • The next scheduled renewal date.

  • The term end date if no next schedule is found.

  • "N/A" if the subscription status is "cancelled".

getPriceForUserSubscription

Calculates and returns the price information for a user's subscription, considering factors such as the user's subscription status, country, and any applicable offers or charges.

import { getPriceForUserSubscription } from "@limio/sdk/subscription";

const price = getPriceForUserSubscription(userSubscription);

console.log(price) // Output: {value: 5.5, currenyCode: "GBP"}

Parameters:

• userSubscription: UserSubscription An object representing the user's subscription details, such as status, schedule, and purchase country.

Returns:

• A string representing the price information for the user's subscription. Possible return values include:

  • A formatted currency amount for the next scheduled payment.

  • "Currently unavailable" if the price cannot be determined.

  • "N/A" if the subscription status is "cancelled".

useSchedule

Returns key dates and prices from the provided customer schedule, formatted according to the default date format and pricing format defined in your environment.

import { useSchedule } from "@limio/sdk/subscription"

const { renewalPrice, termStartDate, termEndDate, nextPaymentAmount } = useSchedule(purchasedSubscription) || {}

console.log(renewalPrice) // Output: "£12.99"
console.log(termStartDate) // Output: "14 Dec 2024"
console.log(termEndDate) // Output: "14 Dec 2025"
console.log(nextPaymentAmount) // Output: "£9.99"

Parameters:

• purchasedSubscription: UserSubscription An object representing the user's subscription details, such as status, schedule, and purchase country.

Returns:

• An object containing:

  • nextPaymentAmount : string: The next amount the customer will be charged.

  • renewalPrice : string: The price the customer will be charged once their current term has lapsed, and they renew onto the next term.

  • termStartDate : string: The date the subscription term began,

  • termEndDate : string: The date the current subscription term is due to lapse.