Subscriptions

Read the customer's subscriptions, and change their quantity, bundle, and survey answers.

Every method here needs a signed-in customer, and reads or writes only that customer's subscriptions.

A subscription has a plan, a quantity, and a list of items: the subscription line itself plus any add-ons. Change the whole subscription with update, updateBundle and updatePreferences; change one line with the Item methods.

Most methods take a params.expand list, and every method takes a final headers object; see Expand parameters and Currency.

subbly.subscriptions.list(params, headers?)

Gets a page of the customer's subscriptions.

Method parameters

paramsRequiredSubscriptionsListParams

Which subscriptions to return. The argument is required by position, so pass an empty object for the defaults.

headersoptionalRequestHeaders

Extra request headers.

ReturnsPromise<SubscriptionsListResponse>

One page of subscriptions.


List the active subscriptions
const { data, pagination } = await subbly.subscriptions.list({
  statuses: ['active', 'trial'],
  expand: ['product.parent']
})

subbly.subscriptions.load(subscriptionId, params?, headers?)

Loads one subscription.

Method parameters

subscriptionIdRequirednumber

ID of the subscription.

paramsoptionalSubscriptionsResourceParams

Extra data to include.

expandoptionalstring[]

Relations to include.

headersoptionalRequestHeaders

Extra request headers.

ReturnsPromise<Subscription>

The subscription.


Load a subscription
const subscription = await subbly.subscriptions.load(123, {
  expand: ['product.parent', 'discounts']
})

subbly.subscriptions.update(subscriptionId, payload, params?, headers?)

Changes the quantity or the metadata of a subscription. Quantity changes need shop.settings.subscriptionQuantitySelector.

Method parameters

subscriptionIdRequirednumber

ID of the subscription.

payloadRequiredSubscriptionUpdatePayload

The change to make.

paramsoptionalSubscriptionsResourceParams

Extra data to include in the response.

expandoptionalstring[]

Relations to include.

headersoptionalRequestHeaders

Extra request headers.

ReturnsPromise<Subscription>

The subscription, with the change applied.


Change the quantity
await subbly.subscriptions.update(123, { quantity: 2 })


Write a metafield value
await subbly.subscriptions.update(123, {
  quantity: subscription.quantity,
  metadata: [{ id: 45, values: [{ id: 67 }] }]
})

subbly.subscriptions.updatePreferences(subscriptionId, payload, headers?)

Rewrites the survey answers of a subscription. Send every answer you want to keep: the call replaces the whole set. This method takes no params argument.

Method parameters

subscriptionIdRequirednumber

ID of the subscription.

payloadRequiredSubscriptionPreferencesPayload

The new answers.

headersoptionalRequestHeaders

Extra request headers.

ReturnsPromise<Subscription>

The subscription, with the new answers.


Answer the survey again
await subbly.subscriptions.updatePreferences(123, {
  preferences: [
    { questionId: 11, answers: [{ id: 22 }] },
    { questionId: 12, answers: [{ content: 'No nuts, please' }] }
  ],
  updateOrders: true
})

subbly.subscriptions.updateBundle(subscriptionId, payload, headers?)

Rewrites the bundle contents and the bundle preferences of a subscription. Send the whole list of items: the call replaces what was there. This method takes no params argument.

Method parameters

subscriptionIdRequirednumber

ID of the subscription.

payloadRequiredSubscriptionBundlePayload

The new bundle.

headersoptionalRequestHeaders

Extra request headers.

ReturnsPromise<Subscription>

The subscription, with the new bundle.


Swap the bundle contents
await subbly.subscriptions.updateBundle(123, {
  productId: subscription.productId,
  quantity: 1,
  bundle: {
    items: [
      { productId: 456, quantity: 2 },
      { productId: 789, quantity: 1 }
    ],
    preferences: [{ attributeId: 5, values: [9] }]
  }
})

subbly.subscriptions.loadItem(subscriptionId, itemId, params?, headers?)

Loads one item of a subscription: the subscription line itself, or an add-on.

Method parameters

subscriptionIdRequirednumber

ID of the subscription.

itemIdRequirednumber

ID of the item, from subscription.items[].id.

paramsoptionalSubscriptionsResourceParams

Extra data to include.

expandoptionalstring[]

Relations to include.

headersoptionalRequestHeaders

Extra request headers.

ReturnsPromise<SubscriptionItem>

The item.


Load one item
const item = await subbly.subscriptions.loadItem(123, 456, {
  expand: ['product.parent']
})

subbly.subscriptions.updateItem(subscriptionId, itemId, payload, params?, headers?)

Changes the quantity or the metadata of one subscription item.

Method parameters

subscriptionIdRequirednumber

ID of the subscription.

itemIdRequirednumber

ID of the item.

payloadRequiredSubscriptionUpdatePayload

The change to make.

paramsoptionalSubscriptionsResourceParams

Extra data to include in the response.

expandoptionalstring[]

Relations to include.

headersoptionalRequestHeaders

Extra request headers.

ReturnsPromise<SubscriptionItem>

The item, with the change applied.


Change the quantity of an add-on
await subbly.subscriptions.updateItem(123, 456, { quantity: 3 })

subbly.subscriptions.updateItemBundle(subscriptionId, itemId, payload, params?, headers?)

Rewrites the bundle contents of one subscription item. Unlike updateBundle, this call carries no quantity, and bundle is required.

Method parameters

subscriptionIdRequirednumber

ID of the subscription.

itemIdRequirednumber

ID of the item.

payloadRequiredSubscriptionItemBundleUpdatePayload

The new bundle for the item.

paramsoptionalSubscriptionsResourceParams

Extra data to include in the response.

expandoptionalstring[]

Relations to include.

headersoptionalRequestHeaders

Extra request headers.

ReturnsPromise<SubscriptionItem>

The item, with the new bundle.


Swap the contents of one bundle item
await subbly.subscriptions.updateItemBundle(123, 456, {
  productId: item.productId,
  bundle: {
    items: [{ productId: 789, quantity: 2 }],
    preferences: []
  }
})

subbly.subscriptions.updateItemPreferences(subscriptionId, itemId, payload, headers?)

Rewrites the survey answers of one subscription item. This method takes no params argument.

Method parameters

subscriptionIdRequirednumber

ID of the subscription.

itemIdRequirednumber

ID of the item.

payloadRequiredSubscriptionPreferencesPayload

The new answers.

headersoptionalRequestHeaders

Extra request headers.

ReturnsPromise<SubscriptionItem>

The item, with the new answers.


Answer the survey for one item
await subbly.subscriptions.updateItemPreferences(123, 456, {
  preferences: [{ questionId: 11, answers: [{ id: 22 }] }]
})

Last modified on September 15, 2026

Subscriptions

Read the customer's subscriptions, and change their quantity, bundle, and survey answers.

Every method here needs a signed-in customer, and reads or writes only that customer's subscriptions.

Most methods take a params.expand list, and every method takes a final headers object; see Expand parameters and Currency.

subbly.subscriptions.list(params, headers?)

Gets a page of the customer's subscriptions.

Method parameters

paramsRequiredSubscriptionsListParams

Which subscriptions to return. The argument is required by position, so pass an empty object for the defaults.

pageoptionalnumber

Page to return, counted from 1.

perPageoptionalnumber

How many subscriptions per page.

statusesoptionalSubscriptionStatus[]

Keep only these statuses: active, trial, pre_order, gift_waiting_to_start, cancelled, switched or expired.

expandoptionalstring[]

Relations to include.

headersoptionalRequestHeaders

Extra request headers.

ReturnsPromise<SubscriptionsListResponse>

One page of subscriptions.

dataSubscription[]

The subscriptions on this page.

paginationPagination

Where this page sits in the full list.


List the active subscriptions
const { data, pagination } = await subbly.subscriptions.list({
  statuses: ['active', 'trial'],
  expand: ['product.parent']
})

subbly.subscriptions.load(subscriptionId, params?, headers?)

Loads one subscription.

Method parameters

subscriptionIdRequirednumber

ID of the subscription.

paramsoptionalSubscriptionsResourceParams

Extra data to include.

expandoptionalstring[]

Relations to include.

headersoptionalRequestHeaders

Extra request headers.

ReturnsPromise<Subscription>

The subscription.

idnumber

ID of the subscription.

customerIdnumber

The customer who owns it.

productIdnumber

The plan the subscription runs on.

productProductPlan | null

That plan. Ask for the product expand to get it.

quantitynumber

How many of the plan the customer gets each cycle.

currencyCodestring

Currency of the subscription, such as USD.

statusSubscriptionStatus

One of active, trial, pre_order, gift_waiting_to_start, cancelled, switched or expired.

activeboolean

Whether the subscription still bills.

pausedboolean

Whether the customer paused it.

pausedAtstring | null

When it was paused.

pastDueboolean

Whether a payment failed and Subbly is retrying.

unpaidboolean

Whether Subbly gave up on a failed payment.

startsAtstring

When the subscription starts.

nextPaymentDatestring

When the next payment is due.

lastPaymentAtstring | null

When the last payment went through.

nextShipmentAtstring | null

When the next parcel goes out.

skippingUntilstring | null

The date the customer skipped shipments up to.

waitingUntilstring | null

The date the subscription waits until before it starts billing.

successfulChargesCountnumber

How many payments have gone through.

chargesLimitnumber | null

How many payments the subscription takes before it ends.

commitmentTermTotalPaymentsnumber | null

How many payments the customer commits to.

cancelAtPeriodEndboolean

Whether it stops at the end of the paid period.

cancelAtEndOfCommitmentboolean

Whether it stops when the commitment ends.

cancellationRequestedboolean

Whether the customer asked to cancel.

cancelledAtstring | null

When it was cancelled.

cancellationsSubscriptionCancellation[]

The cancellation records, with the reason the customer gave. Ask for the cancellations expand to get them.

switchedAtstring | null

When the customer switched to another plan.

previousSubscriptionIdnumber | null

The subscription this one replaced.

itemsSubscriptionItem[]

The lines and add-ons of the subscription.

addonsSubscriptionItem[]

The same items under their old name. Read items instead.

bundleSubscriptionBundle

The bundle contents, when the plan sells a bundle. The object is always there; items is empty when there is no bundle.

surveySubscriptionSurvey | null

The survey answers the customer gave.

preferencesSubscriptionSurvey | null

The same answers under another name. Read survey instead.

discountsSubscriptionDiscount[]

Discounts on the subscription. Ask for the discounts expand to get them.

giftSubscriptionGift | null

Gift settings, when the subscription is a gift.

metadataMetafield[] | null

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

paymentMethodIdnumber

The saved payment method Subbly charges.

billingAddressIdnumber | null

The billing address on the subscription.

shippingAddressIdnumber | null

The shipping address or pick-up record on the subscription.

shippingMethodIdnumber | null

The delivery option on the subscription.

referredBynumber | null

The customer who referred this one.

createdAtstring

When the subscription was created.

updatedAtstring

When the subscription last changed.


Load a subscription
const subscription = await subbly.subscriptions.load(123, {
  expand: ['product.parent', 'discounts']
})

subbly.subscriptions.update(subscriptionId, payload, params?, headers?)

Changes the quantity or the metadata of a subscription. Quantity changes need shop.settings.subscriptionQuantitySelector.

Method parameters

subscriptionIdRequirednumber

ID of the subscription.

payloadRequiredSubscriptionUpdatePayload

The change to make.

quantityRequirednumber

New quantity. Send it even when only the metadata changes.

metadataoptionalMetadataObject[] | null

Metafield values to write. Each entry is { id, values }, where id is a metafield ID. A value is { id } for a preset field and { value } for a free-text one.

paramsoptionalSubscriptionsResourceParams

Extra data to include in the response.

expandoptionalstring[]

Relations to include.

headersoptionalRequestHeaders

Extra request headers.

ReturnsPromise<Subscription>

The subscription, with the change applied.

idnumber

ID of the subscription.

customerIdnumber

The customer who owns it.

productIdnumber

The plan the subscription runs on.

productProductPlan | null

That plan. Ask for the product expand to get it.

quantitynumber

How many of the plan the customer gets each cycle.

currencyCodestring

Currency of the subscription, such as USD.

statusSubscriptionStatus

One of active, trial, pre_order, gift_waiting_to_start, cancelled, switched or expired.

activeboolean

Whether the subscription still bills.

pausedboolean

Whether the customer paused it.

pausedAtstring | null

When it was paused.

pastDueboolean

Whether a payment failed and Subbly is retrying.

unpaidboolean

Whether Subbly gave up on a failed payment.

startsAtstring

When the subscription starts.

nextPaymentDatestring

When the next payment is due.

lastPaymentAtstring | null

When the last payment went through.

nextShipmentAtstring | null

When the next parcel goes out.

skippingUntilstring | null

The date the customer skipped shipments up to.

waitingUntilstring | null

The date the subscription waits until before it starts billing.

successfulChargesCountnumber

How many payments have gone through.

chargesLimitnumber | null

How many payments the subscription takes before it ends.

commitmentTermTotalPaymentsnumber | null

How many payments the customer commits to.

cancelAtPeriodEndboolean

Whether it stops at the end of the paid period.

cancelAtEndOfCommitmentboolean

Whether it stops when the commitment ends.

cancellationRequestedboolean

Whether the customer asked to cancel.

cancelledAtstring | null

When it was cancelled.

cancellationsSubscriptionCancellation[]

The cancellation records, with the reason the customer gave. Ask for the cancellations expand to get them.

switchedAtstring | null

When the customer switched to another plan.

previousSubscriptionIdnumber | null

The subscription this one replaced.

itemsSubscriptionItem[]

The lines and add-ons of the subscription.

addonsSubscriptionItem[]

The same items under their old name. Read items instead.

bundleSubscriptionBundle

The bundle contents, when the plan sells a bundle. The object is always there; items is empty when there is no bundle.

surveySubscriptionSurvey | null

The survey answers the customer gave.

preferencesSubscriptionSurvey | null

The same answers under another name. Read survey instead.

discountsSubscriptionDiscount[]

Discounts on the subscription. Ask for the discounts expand to get them.

giftSubscriptionGift | null

Gift settings, when the subscription is a gift.

metadataMetafield[] | null

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

paymentMethodIdnumber

The saved payment method Subbly charges.

billingAddressIdnumber | null

The billing address on the subscription.

shippingAddressIdnumber | null

The shipping address or pick-up record on the subscription.

shippingMethodIdnumber | null

The delivery option on the subscription.

referredBynumber | null

The customer who referred this one.

createdAtstring

When the subscription was created.

updatedAtstring

When the subscription last changed.


Change the quantity
await subbly.subscriptions.update(123, { quantity: 2 })


Write a metafield value
await subbly.subscriptions.update(123, {
  quantity: subscription.quantity,
  metadata: [{ id: 45, values: [{ id: 67 }] }]
})

subbly.subscriptions.updatePreferences(subscriptionId, payload, headers?)

Rewrites the survey answers of a subscription. Send every answer you want to keep: the call replaces the whole set. This method takes no params argument.

Method parameters

subscriptionIdRequirednumber

ID of the subscription.

payloadRequiredSubscriptionPreferencesPayload

The new answers.

preferencesRequiredSubscriptionSurveyOption[] | null

One entry per question, as { questionId, answers }. An answer is { content } for a text or email question, { id } for a select, multiple, offer or plan question, and { id, quantity } for a quantity question. Pass null to clear the answers.

updateOrdersoptionalboolean

true also applies the answers to orders Subbly already generated.

headersoptionalRequestHeaders

Extra request headers.

ReturnsPromise<Subscription>

The subscription, with the new answers.

idnumber

ID of the subscription.

customerIdnumber

The customer who owns it.

productIdnumber

The plan the subscription runs on.

productProductPlan | null

That plan. Ask for the product expand to get it.

quantitynumber

How many of the plan the customer gets each cycle.

currencyCodestring

Currency of the subscription, such as USD.

statusSubscriptionStatus

One of active, trial, pre_order, gift_waiting_to_start, cancelled, switched or expired.

activeboolean

Whether the subscription still bills.

pausedboolean

Whether the customer paused it.

pausedAtstring | null

When it was paused.

pastDueboolean

Whether a payment failed and Subbly is retrying.

unpaidboolean

Whether Subbly gave up on a failed payment.

startsAtstring

When the subscription starts.

nextPaymentDatestring

When the next payment is due.

lastPaymentAtstring | null

When the last payment went through.

nextShipmentAtstring | null

When the next parcel goes out.

skippingUntilstring | null

The date the customer skipped shipments up to.

waitingUntilstring | null

The date the subscription waits until before it starts billing.

successfulChargesCountnumber

How many payments have gone through.

chargesLimitnumber | null

How many payments the subscription takes before it ends.

commitmentTermTotalPaymentsnumber | null

How many payments the customer commits to.

cancelAtPeriodEndboolean

Whether it stops at the end of the paid period.

cancelAtEndOfCommitmentboolean

Whether it stops when the commitment ends.

cancellationRequestedboolean

Whether the customer asked to cancel.

cancelledAtstring | null

When it was cancelled.

cancellationsSubscriptionCancellation[]

The cancellation records, with the reason the customer gave. Ask for the cancellations expand to get them.

switchedAtstring | null

When the customer switched to another plan.

previousSubscriptionIdnumber | null

The subscription this one replaced.

itemsSubscriptionItem[]

The lines and add-ons of the subscription.

addonsSubscriptionItem[]

The same items under their old name. Read items instead.

bundleSubscriptionBundle

The bundle contents, when the plan sells a bundle. The object is always there; items is empty when there is no bundle.

surveySubscriptionSurvey | null

The survey answers the customer gave.

preferencesSubscriptionSurvey | null

The same answers under another name. Read survey instead.

discountsSubscriptionDiscount[]

Discounts on the subscription. Ask for the discounts expand to get them.

giftSubscriptionGift | null

Gift settings, when the subscription is a gift.

metadataMetafield[] | null

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

paymentMethodIdnumber

The saved payment method Subbly charges.

billingAddressIdnumber | null

The billing address on the subscription.

shippingAddressIdnumber | null

The shipping address or pick-up record on the subscription.

shippingMethodIdnumber | null

The delivery option on the subscription.

referredBynumber | null

The customer who referred this one.

createdAtstring

When the subscription was created.

updatedAtstring

When the subscription last changed.


Answer the survey again
await subbly.subscriptions.updatePreferences(123, {
  preferences: [
    { questionId: 11, answers: [{ id: 22 }] },
    { questionId: 12, answers: [{ content: 'No nuts, please' }] }
  ],
  updateOrders: true
})

subbly.subscriptions.updateBundle(subscriptionId, payload, headers?)

Rewrites the bundle contents and the bundle preferences of a subscription. Send the whole list of items: the call replaces what was there. This method takes no params argument.

Method parameters

subscriptionIdRequirednumber

ID of the subscription.

payloadRequiredSubscriptionBundlePayload

The new bundle.

productIdRequirednumber | null

The plan the bundle belongs to. May be null.

quantityoptionalnumber

New quantity of the bundle.

bundleoptionalobject

What goes in the bundle.

itemsRequiredBundlePayloadItem[] | null

The items picked, as { productId, quantity }. productId is a bundle item's productId.

preferencesRequiredBundlePayloadPreference[] | null

The preferences picked, as { attributeId, values }, where values holds attribute value IDs.

headersoptionalRequestHeaders

Extra request headers.

ReturnsPromise<Subscription>

The subscription, with the new bundle.

idnumber

ID of the subscription.

customerIdnumber

The customer who owns it.

productIdnumber

The plan the subscription runs on.

productProductPlan | null

That plan. Ask for the product expand to get it.

quantitynumber

How many of the plan the customer gets each cycle.

currencyCodestring

Currency of the subscription, such as USD.

statusSubscriptionStatus

One of active, trial, pre_order, gift_waiting_to_start, cancelled, switched or expired.

activeboolean

Whether the subscription still bills.

pausedboolean

Whether the customer paused it.

pausedAtstring | null

When it was paused.

pastDueboolean

Whether a payment failed and Subbly is retrying.

unpaidboolean

Whether Subbly gave up on a failed payment.

startsAtstring

When the subscription starts.

nextPaymentDatestring

When the next payment is due.

lastPaymentAtstring | null

When the last payment went through.

nextShipmentAtstring | null

When the next parcel goes out.

skippingUntilstring | null

The date the customer skipped shipments up to.

waitingUntilstring | null

The date the subscription waits until before it starts billing.

successfulChargesCountnumber

How many payments have gone through.

chargesLimitnumber | null

How many payments the subscription takes before it ends.

commitmentTermTotalPaymentsnumber | null

How many payments the customer commits to.

cancelAtPeriodEndboolean

Whether it stops at the end of the paid period.

cancelAtEndOfCommitmentboolean

Whether it stops when the commitment ends.

cancellationRequestedboolean

Whether the customer asked to cancel.

cancelledAtstring | null

When it was cancelled.

cancellationsSubscriptionCancellation[]

The cancellation records, with the reason the customer gave. Ask for the cancellations expand to get them.

switchedAtstring | null

When the customer switched to another plan.

previousSubscriptionIdnumber | null

The subscription this one replaced.

itemsSubscriptionItem[]

The lines and add-ons of the subscription.

addonsSubscriptionItem[]

The same items under their old name. Read items instead.

bundleSubscriptionBundle

The bundle contents, when the plan sells a bundle. The object is always there; items is empty when there is no bundle.

surveySubscriptionSurvey | null

The survey answers the customer gave.

preferencesSubscriptionSurvey | null

The same answers under another name. Read survey instead.

discountsSubscriptionDiscount[]

Discounts on the subscription. Ask for the discounts expand to get them.

giftSubscriptionGift | null

Gift settings, when the subscription is a gift.

metadataMetafield[] | null

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

paymentMethodIdnumber

The saved payment method Subbly charges.

billingAddressIdnumber | null

The billing address on the subscription.

shippingAddressIdnumber | null

The shipping address or pick-up record on the subscription.

shippingMethodIdnumber | null

The delivery option on the subscription.

referredBynumber | null

The customer who referred this one.

createdAtstring

When the subscription was created.

updatedAtstring

When the subscription last changed.


Swap the bundle contents
await subbly.subscriptions.updateBundle(123, {
  productId: subscription.productId,
  quantity: 1,
  bundle: {
    items: [
      { productId: 456, quantity: 2 },
      { productId: 789, quantity: 1 }
    ],
    preferences: [{ attributeId: 5, values: [9] }]
  }
})

subbly.subscriptions.loadItem(subscriptionId, itemId, params?, headers?)

Loads one item of a subscription: the subscription line itself, or an add-on.

Method parameters

subscriptionIdRequirednumber

ID of the subscription.

itemIdRequirednumber

ID of the item, from subscription.items[].id.

paramsoptionalSubscriptionsResourceParams

Extra data to include.

expandoptionalstring[]

Relations to include.

headersoptionalRequestHeaders

Extra request headers.

ReturnsPromise<SubscriptionItem>

The item.


Load one item
const item = await subbly.subscriptions.loadItem(123, 456, {
  expand: ['product.parent']
})

subbly.subscriptions.updateItem(subscriptionId, itemId, payload, params?, headers?)

Changes the quantity or the metadata of one subscription item.

Method parameters

subscriptionIdRequirednumber

ID of the subscription.

itemIdRequirednumber

ID of the item.

payloadRequiredSubscriptionUpdatePayload

The change to make.

quantityRequirednumber

New quantity of the item.

metadataoptionalMetadataObject[] | null

Metafield values to write, as { id, values }.

paramsoptionalSubscriptionsResourceParams

Extra data to include in the response.

expandoptionalstring[]

Relations to include.

headersoptionalRequestHeaders

Extra request headers.

ReturnsPromise<SubscriptionItem>

The item, with the change applied.


Change the quantity of an add-on
await subbly.subscriptions.updateItem(123, 456, { quantity: 3 })

subbly.subscriptions.updateItemBundle(subscriptionId, itemId, payload, params?, headers?)

Rewrites the bundle contents of one subscription item. Unlike updateBundle, this call carries no quantity, and bundle is required.

Method parameters

subscriptionIdRequirednumber

ID of the subscription.

itemIdRequirednumber

ID of the item.

payloadRequiredSubscriptionItemBundleUpdatePayload

The new bundle for the item.

productIdRequirednumber | null

The variant or plan the bundle belongs to. May be null.

bundleRequiredobject

What goes in the bundle.

itemsRequiredBundlePayloadItem[] | null

The items picked, as { productId, quantity }.

preferencesRequiredBundlePayloadPreference[] | null

The preferences picked, as { attributeId, values }.

paramsoptionalSubscriptionsResourceParams

Extra data to include in the response.

expandoptionalstring[]

Relations to include.

headersoptionalRequestHeaders

Extra request headers.

ReturnsPromise<SubscriptionItem>

The item, with the new bundle.


Swap the contents of one bundle item
await subbly.subscriptions.updateItemBundle(123, 456, {
  productId: item.productId,
  bundle: {
    items: [{ productId: 789, quantity: 2 }],
    preferences: []
  }
})

subbly.subscriptions.updateItemPreferences(subscriptionId, itemId, payload, headers?)

Rewrites the survey answers of one subscription item. This method takes no params argument.

Method parameters

subscriptionIdRequirednumber

ID of the subscription.

itemIdRequirednumber

ID of the item.

payloadRequiredSubscriptionPreferencesPayload

The new answers.

preferencesRequiredSubscriptionSurveyOption[] | null

One entry per question, as { questionId, answers }. Pass null to clear the answers.

updateOrdersoptionalboolean

true also applies the answers to orders Subbly already generated.

headersoptionalRequestHeaders

Extra request headers.

ReturnsPromise<SubscriptionItem>

The item, with the new answers.


Answer the survey for one item
await subbly.subscriptions.updateItemPreferences(123, 456, {
  preferences: [{ questionId: 11, answers: [{ id: 22 }] }]
})

Last modified on September 15, 2026