SubscriptionItems

updateSubscriptionItem

Update a subscription item.

Usage

import { type SubscriptionItem, updateSubscriptionItem } from '@lemonsqueezy/lemonsqueezy.js';

const subscriptionItemId = 234567;
const quantity = 10;

// It will be removed with the next major version.
const { statusCode, error, data } = await updateSubscriptionItem(subscriptionItemId, quantity);

// Use the 'updateSubscriptionItem' parameter instead.
const { statusCode, error, data } = await updateSubscriptionItem(subscriptionItemId, { quantity: 20, invoiceImmediately: true });

Type Declarations

/**
 * Update a subscription item.
 *
 * Note: this endpoint is only used with quantity-based billing. If the related subscription's product/variant has usage-based billing enabled, this endpoint will return a `422 Unprocessable Entity` response.
 *
 * @param subscriptionItemId The given subscription item id.
 * @param quantity The unit quantity of the subscription.
 * @deprecated It will be removed with the next major version. Use the 'updateSubscriptionItem' parameter instead.
 * @returns A subscription item object.
 */
declare function updateSubscriptionItem(subscriptionItemId: string | number, quantity: number): Promise<FetchResponse<SubscriptionItem>>;

/**
 * Update a subscription item.
 *
 * Note: this endpoint is only used with quantity-based billing.
 * If the related subscription's product/variant has usage-based billing
 * enabled, this endpoint will return a `422 Unprocessable Entity` response.
 *
 * @param subscriptionItemId The given subscription item id.
 * @param updateSubscriptionItem (Required) Update subscription item info.
 * @param updateSubscriptionItem.quantity (Required) The unit quantity of the subscription.
 * @param [updateSubscriptionItem.invoiceImmediately] (Optional) If `true`, any updates to the subscription will be charged immediately. A new prorated invoice will be generated and payment attempted. Defaults to `false`. Note that this will be overridden by the `disable_prorations` option if used.
 * @param [updateSubscriptionItem.disableProrations] (Optional) If `true`, no proration will be charged and the customer will simply be charged the new price at the next renewal. Defaults to `false`. Note that this will override the `invoice_immediately` option if used.
 * @returns A subscription item object.
 */
declare function updateSubscriptionItem(
	subscriptionItemId: string | number,
	updateSubscriptionItem: UpdateSubscriptionItem
): Promise<FetchResponse<SubscriptionItem>>;

Returns

Returns a subscription item object.

{
	statusCode: number | null;
	error: Error | null;
	data: SubscriptionItem | null;
}

Source

Source ~ Type ~ Test

getSubscriptionItem

Retrieves the subscription item with the given ID.

Usage

import { type SubscriptionItem, getSubscriptionItem } from '@lemonsqueezy/lemonsqueezy.js';

const subscriptionItemId = 234567;
const { statusCode, error, data } = await getSubscriptionItem(subscriptionItemId);

With related resources:

import { type SubscriptionItem, type GetSubscriptionItemParams, getSubscriptionItem } from '@lemonsqueezy/lemonsqueezy.js';

const subscriptionItemId = 234567;
const { statusCode, error, data } = await getSubscriptionItem(subscriptionItemId, { include: ['subscription'] });

Type Declarations

/**
 * Retrieve a subscription item.
 *
 * @param subscriptionItemId The given subscription item id.
 * @param [params] (Optional) Additional parameters.
 * @param [params.include] (Optional) Related resources.
 * @returns A subscription item object.
 */
declare function getSubscriptionItem(subscriptionItemId: number | string, params?: GetSubscriptionItemParams): Promise<FetchResponse<SubscriptionItem>>;

Returns

Returns a subscription item object.

{
	statusCode: number | null;
	error: Error | null;
	data: SubscriptionItem | null;
}

Source

Source ~ Type ~ Test

getSubscriptionItemCurrentUsage

Retrieves the unit usage for a subscription item for the current billing period.

Usage

import { type SubscriptionItemCurrentUsage, getSubscriptionItemCurrentUsage } from '@lemonsqueezy/lemonsqueezy.js';

const subscriptionItemId = 234567;
const { statusCode, error, data } = await getSubscriptionItemCurrentUsage(subscriptionItemId);

Type Declarations

/**
 * Retrieve a subscription item's current usage.
 *
 * Note: this endpoint is only for subscriptions with usage-based billing enabled. It will return a `404 Not Found` response if the related subscription product/variant does not have usage-based billing enabled.
 *
 * @param subscriptionItemId The given subscription item id.
 * @returns A meta object containing usage information.
 */
declare function getSubscriptionItemCurrentUsage(subscriptionItemId: number | string): Promise<FetchResponse<SubscriptionItemCurrentUsage>>;

Returns

Returns a meta object containing usage information.

{
	statusCode: number | null;
	error: Error | null;
	data: SubscriptionItemCurrentUsage | null;
}

Source

Source ~ Type ~ Test

listSubscriptionItems

Returns a paginated list of subscription items.

Usage

import { type ListSubscriptionItems, listSubscriptionItems } from '@lemonsqueezy/lemonsqueezy.js';

const { statusCode, error, data } = await listSubscriptionItems();

With filter:

import { type ListSubscriptionItems, type ListSubscriptionItemsParams, listSubscriptionItems } from '@lemonsqueezy/lemonsqueezy.js';

const { statusCode, error, data } = await listSubscriptionItems({ filter: { subscriptionId: 345678 } });

With pagination:

import { type ListSubscriptionItems, type ListSubscriptionItemsParams, listSubscriptionItems } from '@lemonsqueezy/lemonsqueezy.js';

const { statusCode, error, data } = await listSubscriptionItems({ page: { number: 1, size: 10 } });

With related resources:

import { type ListSubscriptionItems, type ListSubscriptionItemsParams, listSubscriptionItems } from '@lemonsqueezy/lemonsqueezy.js';

const { statusCode, error, data } = await listSubscriptionItems({ include: ['subscription'] });

Type Declarations

/**
 * List all subscription items.
 *
 * @param [params] (Optional) Additional parameters.
 * @param [params.filter] (Optional) Filter parameters.
 * @param [params.filter.subscriptionId] (Optional) Only return subscription items belonging to a subscription with this ID.
 * @param [params.filter.priceId] (Optional) Only return subscription items belonging to a price with this ID.
 * @param [params.page] (Optional) Custom paginated queries.
 * @param [params.page.number] (Optional) The parameter determine which page to retrieve.
 * @param [params.page.size] (Optional) The parameter to determine how many results to return per page.
 * @param [params.include] (Optional) Related resources.
 * @returns A paginated list of subscription item objects ordered by `created_at` (descending).
 */
declare function listSubscriptionItems(params?: ListSubscriptionItemsParams): Promise<FetchResponse<ListSubscriptionItems>>;

Returns

Returns a paginated list of subscription item objects ordered by created_at (descending).

{
	statusCode: number | null;
	error: Error | null;
	data: ListSubscriptionItems | null;
}

Source

Source ~ Type ~ Test