Products

List the products, and load a product, a variant, or a plan.

A shop sells two kinds of product. A one-time product holds variants; a subscription product holds plans. A parent product is what you list and show on a page; a variant or a plan is what a customer buys, and its id is the productId you send to subbly.cart.addItem.

Every method here takes an optional headers argument to price one response in another currency; see Currency.

subbly.products.list(params?, headers?)

Gets a page of the shop's parent products.

Method parameters

paramsoptionalProductsListParams

Which products to return.

headersoptionalProductRequestHeaders

Extra request headers, such as x-currency.

ReturnsPromise<ProductsListResponse>

One page of products.


List the products
const { data, pagination } = await subbly.products.list({
  page: 1,
  perPage: 10,
  expand: ['variants.parent']
})


List the subscription products only
const { data } = await subbly.products.list({
  type: 'subscription',
  expand: ['plans']
})

subbly.products.load(productId, params?, headers?)

Loads one parent product, with its variants or its plans.

Method parameters

productIdRequirednumber

ID of the parent product.

paramsoptionalProductsResourceParams

Extra data to include.

headersoptionalProductRequestHeaders

Extra request headers, such as x-currency.

ReturnsPromise<ParentProduct>

The product. Narrow on type to read variants or plans.


Load a product
const product = await subbly.products.load(123, {
  expand: ['variants.parent', 'plans.parent']
})

const buyable = product.type === 'subscription' ? product.plans : product.variants

subbly.products.loadVariant(productId, params?, headers?)

Loads one product variant, the buyable child of a one-time product.

Pass a variant ID, not the ID of its parent. The endpoint behind this method also serves plans, so the declared result is a variant or a plan; use subbly.products.loadPlan when you hold a plan ID.

Method parameters

productIdRequirednumber

ID of the variant.

paramsoptionalProductsResourceParams

Extra data to include.

headersoptionalProductRequestHeaders

Extra request headers, such as x-currency.

ReturnsPromise<Product>

The variant, or the plan when the ID belongs to one.


Load a variant
const variant = await subbly.products.loadVariant(456, { expand: ['parent'] })

await subbly.cart.addItem({ productId: variant.id, quantity: 1 })

subbly.products.loadPlan(productId, params?, headers?)

Loads one subscription plan, the buyable child of a subscription product. Older material calls a plan a pricing.

loadPlan and loadVariant call the same endpoint; only the type of the result differs. Use loadPlan when the ID belongs to a plan.

Method parameters

productIdRequirednumber

ID of the plan.

paramsoptionalProductsResourceParams

Extra data to include.

headersoptionalProductRequestHeaders

Extra request headers, such as x-currency.

ReturnsPromise<ProductPlan>

The plan.


Load a plan
const plan = await subbly.products.loadPlan(789, { expand: ['parent'] })

console.log(plan.frequencyCount, plan.frequencyUnit)

Last modified on September 15, 2026

Products

List the products, and load a product, a variant, or a plan.

Every method here takes an optional headers argument to price one response in another currency; see Currency.

subbly.products.list(params?, headers?)

Gets a page of the shop's parent products.

Method parameters

paramsoptionalProductsListParams

Which products to return.

pageoptionalnumber

Page to return, counted from 1.

perPageoptionalnumber

How many products per page.

tagsoptionalstring[]

Keep only products with these tags.

typeoptional'one_time' | 'subscription'

Keep only one-time products, or only subscription products.

slugsoptionalstring[]

Keep only products with these slugs.

digitaloptionalboolean

true keeps only digital products, false only physical ones.

giftCardoptionalboolean

true keeps only gift cards, false leaves them out.

expandoptionalstring[]

Relations to include: variants, variants.parent, plans, plans.parent and metadata. Without them a product carries no buyable children.

headersoptionalProductRequestHeaders

Extra request headers, such as x-currency.

ReturnsPromise<ProductsListResponse>

One page of products.

dataParentProduct[]

The products on this page. Each one is a one-time product or a subscription product; narrow on type.

paginationPagination

Where this page sits in the full list.


List the products
const { data, pagination } = await subbly.products.list({
  page: 1,
  perPage: 10,
  expand: ['variants.parent']
})


List the subscription products only
const { data } = await subbly.products.list({
  type: 'subscription',
  expand: ['plans']
})

subbly.products.load(productId, params?, headers?)

Loads one parent product, with its variants or its plans.

Method parameters

productIdRequirednumber

ID of the parent product.

paramsoptionalProductsResourceParams

Extra data to include.

expandoptionalstring[]

Relations to include: variants, variants.parent, plans, plans.parent and metadata.

headersoptionalProductRequestHeaders

Extra request headers, such as x-currency.

ReturnsPromise<ParentProduct>

The product. Narrow on type to read variants or plans.


Load a product
const product = await subbly.products.load(123, {
  expand: ['variants.parent', 'plans.parent']
})

const buyable = product.type === 'subscription' ? product.plans : product.variants

subbly.products.loadVariant(productId, params?, headers?)

Loads one product variant, the buyable child of a one-time product.

Method parameters

productIdRequirednumber

ID of the variant.

paramsoptionalProductsResourceParams

Extra data to include.

expandoptionalstring[]

Relations to include. parent loads the product the variant belongs to.

headersoptionalProductRequestHeaders

Extra request headers, such as x-currency.

ReturnsPromise<Product>

The variant, or the plan when the ID belongs to one.

idnumber

ID of the plan. Send it as productId when you add the subscription to a cart.

namestring

Name of the plan, such as Monthly.

pricingNamestring | null

Older name of the plan. Subbly called plans pricings before.

descriptionstring | null

Description of the plan.

pricenumber

Price of one billing period, in the minor unit of the currency.

setupFeenumber | null

One-off fee charged with the first payment.

frequencyCountnumber

How many frequencyUnit periods sit between two payments.

frequencyUnit'day' | 'week' | 'month'

The unit of the billing period.

chargeImmediatelyboolean

Whether the first payment is taken at checkout.

shipImmediatelyboolean

Whether the first shipment goes out at once.

chargesLimitnumber | null

How many payments the subscription takes before it ends. null means it runs until the customer cancels.

commitmentBillingCountnumber

How many payments the customer commits to before they may cancel.

trialLengthnumber | null

Length of the trial, in days.

trialPricenumber | null

Price of the trial, in the minor unit of the currency.

trialLengthDaysnumber | null

The trial length again, in days. Survey answers carry this name.

cutOffAtstring | null

The moment after which a new customer joins the next cycle rather than this one.

preOrderEndAtstring | null

When the pre-order window closes.

rebillingStartAtstring | null

When regular billing starts, for a plan that begins on a fixed date.

planHashstring | null

Internal hash of the plan settings.

stockCountnumber | null

Units left. null means the shop does not track stock for this plan.

priceSchemeProductPriceScheme | null

Volume pricing, when the shop sets it up. null when the price never changes with quantity.

bundlePlanIdnumber | null

The bundle plan this plan prices, when the plan belongs to a bundle.

surveySurvey | null

The survey the customer answers when they buy the plan. Load the questions with subbly.surveys.load, then send the answers as options on the cart item.

shippingsProductShipping[]

The fixed shipment dates of the plan, for a shop that ships on a calendar rather than on the billing date.

metadataMetafield[] | null

Metafield values saved on the plan. Ask for the metadata expand to get them.

parentProductSubscription

The product the plan belongs to. Ask for the parent expand to get it.

createdAtstring

When the plan was created.


Load a variant
const variant = await subbly.products.loadVariant(456, { expand: ['parent'] })

await subbly.cart.addItem({ productId: variant.id, quantity: 1 })

subbly.products.loadPlan(productId, params?, headers?)

Loads one subscription plan, the buyable child of a subscription product. Older material calls a plan a pricing.

loadPlan and loadVariant call the same endpoint; only the type of the result differs. Use loadPlan when the ID belongs to a plan.

Method parameters

productIdRequirednumber

ID of the plan.

paramsoptionalProductsResourceParams

Extra data to include.

expandoptionalstring[]

Relations to include. parent loads the product the plan belongs to.

headersoptionalProductRequestHeaders

Extra request headers, such as x-currency.

ReturnsPromise<ProductPlan>

The plan.

idnumber

ID of the plan. Send it as productId when you add the subscription to a cart.

namestring

Name of the plan, such as Monthly.

pricingNamestring | null

Older name of the plan. Subbly called plans pricings before.

descriptionstring | null

Description of the plan.

pricenumber

Price of one billing period, in the minor unit of the currency.

setupFeenumber | null

One-off fee charged with the first payment.

frequencyCountnumber

How many frequencyUnit periods sit between two payments.

frequencyUnit'day' | 'week' | 'month'

The unit of the billing period.

chargeImmediatelyboolean

Whether the first payment is taken at checkout.

shipImmediatelyboolean

Whether the first shipment goes out at once.

chargesLimitnumber | null

How many payments the subscription takes before it ends. null means it runs until the customer cancels.

commitmentBillingCountnumber

How many payments the customer commits to before they may cancel.

trialLengthnumber | null

Length of the trial, in days.

trialPricenumber | null

Price of the trial, in the minor unit of the currency.

trialLengthDaysnumber | null

The trial length again, in days. Survey answers carry this name.

cutOffAtstring | null

The moment after which a new customer joins the next cycle rather than this one.

preOrderEndAtstring | null

When the pre-order window closes.

rebillingStartAtstring | null

When regular billing starts, for a plan that begins on a fixed date.

planHashstring | null

Internal hash of the plan settings.

stockCountnumber | null

Units left. null means the shop does not track stock for this plan.

priceSchemeProductPriceScheme | null

Volume pricing, when the shop sets it up. null when the price never changes with quantity.

bundlePlanIdnumber | null

The bundle plan this plan prices, when the plan belongs to a bundle.

surveySurvey | null

The survey the customer answers when they buy the plan. Load the questions with subbly.surveys.load, then send the answers as options on the cart item.

shippingsProductShipping[]

The fixed shipment dates of the plan, for a shop that ships on a calendar rather than on the billing date.

metadataMetafield[] | null

Metafield values saved on the plan. Ask for the metadata expand to get them.

parentProductSubscription

The product the plan belongs to. Ask for the parent expand to get it.

createdAtstring

When the plan was created.


Load a plan
const plan = await subbly.products.loadPlan(789, { expand: ['parent'] })

console.log(plan.frequencyCount, plan.frequencyUnit)

Last modified on September 15, 2026