Bundles

Read bundles, their items and groups, and price the items a customer picked.

Every method here takes an optional headers argument to price one call in another currency, and every amount is a whole number in the minor unit; see Currency and Amounts and dates.

A typical flow: load the bundle for its plans and rules, loadItems for what the customer can pick, quote to show the price, then subbly.cart.addItem to buy it.

subbly.bundles.list(params, headers?)

Gets a paginated list of the shop's bundles.

Method parameters

paramsRequiredBundleListParams

Paging and filters. Pass {} for the defaults — the argument is required by position even though every field inside it is optional.

headersoptionalBundleRequestHeaders

Extra request headers.

ReturnsPromise<BundleListResponse>

One page of bundles.


List the bundles
const { data, pagination } = await subbly.bundles.list({})


List the configurable bundles with their plans
const { data } = await subbly.bundles.list({
  perPage: 24,
  configurable: true,
  expand: ['plans.plan', 'plans.variant'],
})

subbly.bundles.load(bundleId, params?, headers?)

Gets one bundle with its plans, prices, discounts, rulesets, filters and preferences — everything the picker needs except the items themselves.

Method parameters

bundleIdRequirednumber

ID of the bundle.

paramsoptionalBundleResourceParams

Relations to include.

headersoptionalBundleRequestHeaders

Extra request headers.

x-currencyoptionalstring

Currency for the prices in the response.

ReturnsPromise<Bundle>

The bundle.


Load a bundle
const bundle = await subbly.bundles.load(512, {
  expand: ['plans.plan', 'plans.plan.parent'],
})

subbly.bundles.loadItems(bundleId, params?, headers?)

Gets a paginated, filterable list of the products a customer can pick for the bundle. Send the picks to quote and to subbly.cart.addItem as { productId, quantity }.

Method parameters

bundleIdRequirednumber

ID of the bundle.

paramsoptionalBundleItemsParams

Paging, filters and relations.

headersoptionalBundleRequestHeaders

Extra request headers.

x-currencyoptionalstring

Currency for the prices in the response.

ReturnsPromise<BundleItemsResponse>

One page of bundle items.


Load the bundle items
const { data } = await subbly.bundles.loadItems(512, {
  perPage: 50,
  expand: ['product'],
})


Filter the items by an attribute
const { data } = await subbly.bundles.loadItems(512, {
  filters: [{ attributeId: 9, values: [31, 32] }],
})

subbly.bundles.loadGroups(bundleId, params?, headers?)

Gets the item groups of a bundle. A group gathers the variants of one product and sets its own minimum and maximum quantity, so a customer can be asked for, say, two coffees and one tea.

Method parameters

bundleIdRequirednumber

ID of the bundle.

paramsoptionalBundleGroupsParams

Paging and relations.

headersoptionalBundleRequestHeaders

Extra request headers.

x-currencyoptionalstring

Currency for the prices in the response.

ReturnsPromise<BundleGroupsResponse>

One page of groups.


Load the bundle groups
const { data } = await subbly.bundles.loadGroups(512, {
  expand: ['items.product'],
})

subbly.bundles.quote(bundleId, payload, params?, headers?)

Prices a bundle for the exact items and preferences a customer picked, before it goes in the cart. Use it to show a running total in the picker.

Method parameters

bundleIdRequirednumber

ID of the bundle.

payloadRequiredBundleQuotePayload

What the customer picked. items and preferences are both required; send an empty array when the bundle has no preferences.

paramsoptionalBundleQuoteParams

Relations to include.

headersoptionalBundleRequestHeaders

Extra request headers.

x-currencyoptionalstring

Currency for the prices in the response.

ReturnsPromise<BundleQuote>

The priced bundle, with a line for every picked item.


Quote a bundle
const quote = await subbly.bundles.quote(512, {
  productId: 8801,
  quantity: 1,
  items: [
    { productId: 3301, quantity: 2 },
    { productId: 3307, quantity: 1 },
  ],
  preferences: [],
})

Last modified on September 15, 2026

Bundles

Read bundles, their items and groups, and price the items a customer picked.

Every method here takes an optional headers argument to price one call in another currency, and every amount is a whole number in the minor unit; see Currency and Amounts and dates.

A typical flow: load the bundle for its plans and rules, loadItems for what the customer can pick, quote to show the price, then subbly.cart.addItem to buy it.

subbly.bundles.list(params, headers?)

Gets a paginated list of the shop's bundles.

Method parameters

paramsRequiredBundleListParams

Paging and filters. Pass {} for the defaults — the argument is required by position even though every field inside it is optional.

pageoptionalnumber

Page to fetch, counting from 1.

perPageoptionalnumber

How many bundles per page.

tagsoptionalstring[]

Keep only bundles carrying these tags.

slugsoptionalstring[]

Keep only bundles with these slugs.

idsoptionalnumber[]

Keep only these bundle IDs.

digitaloptionalboolean

true keeps only digital bundles, false only physical ones.

configurableoptionalboolean

true keeps only bundles the customer configures, false only fixed ones.

expandoptionalstring[]

Relations to include: plans.variant, plans.variant.parent, plans.plan, plans.plan.parent and metadata.

headersoptionalBundleRequestHeaders

Extra request headers.

x-currencyoptionalstring

Currency for the prices in the response, such as EUR.

ReturnsPromise<BundleListResponse>

One page of bundles.

dataBundle[]

The bundles on this page.

paginationPagination

Where this page sits in the list.

currentPagenumber

The page you are on, counting from 1.

fromnumber

Index of the first row on this page.

tonumber

Index of the last row on this page.

lastPagenumber

The number of pages.

totalnumber

The number of rows across every page.


List the bundles
const { data, pagination } = await subbly.bundles.list({})


List the configurable bundles with their plans
const { data } = await subbly.bundles.list({
  perPage: 24,
  configurable: true,
  expand: ['plans.plan', 'plans.variant'],
})

subbly.bundles.load(bundleId, params?, headers?)

Gets one bundle with its plans, prices, discounts, rulesets, filters and preferences — everything the picker needs except the items themselves.

Method parameters

bundleIdRequirednumber

ID of the bundle.

paramsoptionalBundleResourceParams

Relations to include.

expandoptionalstring[]

plans.variant, plans.variant.parent, plans.plan, plans.plan.parent and metadata.

headersoptionalBundleRequestHeaders

Extra request headers.

x-currencyoptionalstring

Currency for the prices in the response.

ReturnsPromise<Bundle>

The bundle.

idnumber

ID of the bundle.

namestring

Name of the bundle.

slugstring

URL-safe name. Filter on it with the slugs parameter of subbly.bundles.list.

descriptionstring | null

Description of the bundle.

deliveryInfostring | null

Delivery note the shop shows with the bundle.

digitalboolean

true when nothing is shipped.

searchableboolean

true when the bundle may appear in a listing.

configurableboolean

true when the customer picks the items. false means the contents are fixed.

hiddenItemsboolean

true when the shop hides the item list from the customer.

showRulesetNameboolean

true when the picker should show the ruleset name.

appearanceTypestring

How to lay the picker out: one_step, two_step, without_ruleset or after_checkout.

selectionTypestring

What the customer picks: variant, product or single_product.

rulesetTypestring

What a ruleset counts: total for money, quantity for items.

priceTypestring | null

How the bundle is priced: per_item or total. null when the plans set the price.

discountTypestring | null

How the bundle discount works: per_item, total or percentage.

quantitySelectorsnumber[] | null

The bundle quantities the customer may choose from.

imagesobject[]

Bundle images, each with id, url, order, createdAt and updatedAt.

plansBundlePlan[]

The ways to buy the bundle: a subscription plan or a one-time variant.

pricesobject[]

What the bundle costs at each size.

discountsobject[]

What comes off at each size.

rulesetsobject[]

The rules for how much the customer must pick.

filtersobject[]

The attribute filters for the item picker. Send the chosen ones as filters in subbly.bundles.loadItems.

preferencesobject[]

The preferences the customer answers for the bundle. Send the answers as preferences in subbly.bundles.quote and subbly.cart.addItem.

metadataMetafield[] | null

Metafield values on the bundle. The API sends them only when you ask for the metadata expand. The shape is on the Metafields page.

createdAtstring

When the bundle was created.

updatedAtstring

When the bundle last changed.


Load a bundle
const bundle = await subbly.bundles.load(512, {
  expand: ['plans.plan', 'plans.plan.parent'],
})

subbly.bundles.loadItems(bundleId, params?, headers?)

Gets a paginated, filterable list of the products a customer can pick for the bundle. Send the picks to quote and to subbly.cart.addItem as { productId, quantity }.

Method parameters

bundleIdRequirednumber

ID of the bundle.

paramsoptionalBundleItemsParams

Paging, filters and relations.

pageoptionalnumber

Page to fetch, counting from 1.

perPageoptionalnumber

How many items per page.

filtersoptionalobject[]

Attribute filters, built from bundle.filters.

attributeIdRequirednumber

ID of the attribute, from bundle.filters[].attributeId.

valuesRequirednumber[]

IDs of the chosen values, from bundle.filters[].values[].id.

productIdsoptionalnumber[]

Keep only these variant IDs.

queryoptionalstring

Free-text search over the item names.

expandoptionalstring[]

product and product.parent.

headersoptionalBundleRequestHeaders

Extra request headers.

x-currencyoptionalstring

Currency for the prices in the response.

ReturnsPromise<BundleItemsResponse>

One page of bundle items.

dataBundleItem[]

The items on this page.

paginationPagination

Where this page sits in the list.

currentPagenumber

The page you are on, counting from 1.

fromnumber

Index of the first row on this page.

tonumber

Index of the last row on this page.

lastPagenumber

The number of pages.

totalnumber

The number of rows across every page.


Load the bundle items
const { data } = await subbly.bundles.loadItems(512, {
  perPage: 50,
  expand: ['product'],
})


Filter the items by an attribute
const { data } = await subbly.bundles.loadItems(512, {
  filters: [{ attributeId: 9, values: [31, 32] }],
})

subbly.bundles.loadGroups(bundleId, params?, headers?)

Gets the item groups of a bundle. A group gathers the variants of one product and sets its own minimum and maximum quantity, so a customer can be asked for, say, two coffees and one tea.

Method parameters

bundleIdRequirednumber

ID of the bundle.

paramsoptionalBundleGroupsParams

Paging and relations.

pageoptionalnumber

Page to fetch, counting from 1.

perPageoptionalnumber

How many groups per page.

expandoptionalstring[]

product, items.product and items.product.parent.

headersoptionalBundleRequestHeaders

Extra request headers.

x-currencyoptionalstring

Currency for the prices in the response.

ReturnsPromise<BundleGroupsResponse>

One page of groups.

dataBundleGroup[]

The groups on this page.

paginationPagination

Where this page sits in the list.


Load the bundle groups
const { data } = await subbly.bundles.loadGroups(512, {
  expand: ['items.product'],
})

subbly.bundles.quote(bundleId, payload, params?, headers?)

Prices a bundle for the exact items and preferences a customer picked, before it goes in the cart. Use it to show a running total in the picker.

Method parameters

bundleIdRequirednumber

ID of the bundle.

payloadRequiredBundleQuotePayload

What the customer picked. items and preferences are both required; send an empty array when the bundle has no preferences.

productIdRequirednumber

The plan or variant the customer chose, from bundle.plans[].plan.id or bundle.plans[].variant.id.

quantityRequirednumber

How many bundles.

itemsRequiredobject[]

The picked items.

productIdRequirednumber

ID of the picked variant, from bundleItem.productId.

quantityRequirednumber

How many of it.

preferencesRequiredobject[]

The answers to the bundle preferences. Send [] when there are none.

attributeIdRequirednumber

ID of the attribute, from bundle.preferences[].attributeId.

valuesRequirednumber[]

IDs of the chosen values.

paramsoptionalBundleQuoteParams

Relations to include.

expandoptionalstring[]

items.product and items.product.parent.

headersoptionalBundleRequestHeaders

Extra request headers.

x-currencyoptionalstring

Currency for the prices in the response.

ReturnsPromise<BundleQuote>

The priced bundle, with a line for every picked item.


Quote a bundle
const quote = await subbly.bundles.quote(512, {
  productId: 8801,
  quantity: 1,
  items: [
    { productId: 3301, quantity: 2 },
    { productId: 3307, quantity: 1 },
  ],
  preferences: [],
})

Last modified on September 15, 2026