Log in Get started

Get started
Developer resources

Subbly.js SDK reference

Amounts and dates

Expand parameters

Set the currency

Set the language

List the addresses

Delete an address

Authentication state

Check the authentication

Log in with a password

Register a customer

Check if an email is registered

Send a one-time password

Log in with a one-time password

Log in with single sign-on

Get the access token

List the bundles

Load the bundle items

Load the bundle groups

Update the cart

Get the start dates

Get the gifting dates

Get the shipping methods

Get the pick-up points

Attach the customer

Purchase the cart

List the countries

Get the customer profile

Update the customer

Get the referral link

Get a pre-purchase offer

Accept a pre-purchase offer

Skip a pre-purchase offer

Reset the pre-purchase offers

Get a mid-purchase offer

Accept a mid-purchase offer

Skip a mid-purchase offer

Get a post-purchase offer

Accept a post-purchase offer

Skip a post-purchase offer

List the metafields

Payment intents

Get a payment intent

Confirm a payment intent

List the pick-up infos

Add a pick-up info

Delete a pick-up info

List the products

Stock notifications

Get a back-in-stock alert

List the subscriptions

Load a subscription

Update a subscription

Update the survey preferences

Update the bundle

Load a subscription item

Update a subscription item

Update an item bundle

Update the item survey preferences

List the payment methods

Start a payment setup

Add a payment method

Start a 3-D Secure setup

Surveys

Load a survey with its questions and answers.

subbly.surveys.load(surveyId, params?, headers?)

Loads a survey with its questions, answers and styling. A survey belongs to a plan: read plan.survey.id on the plan the customer chose, load the survey, then send the answers as options on the cart item.

Method parameters

surveyIdRequirednumber

ID of the survey.

paramsoptionalSurveyResourceParams

Extra data to include.

headersoptionalSurveyRequestHeaders

Extra request headers. Set x-currency to price the answers in another currency. Without it the SDK sends the currency from subbly.setCurrency.

ReturnsPromise<Survey>

The survey.


Load a survey
const survey = await subbly.surveys.load(123, {
  expand: ['questions.answers.product.parent']
})


Answer it and add the item to the cart
const survey = await subbly.surveys.load(plan.survey.id)
const [question] = survey.questions

await subbly.cart.addItem({
  productId: plan.id,
  quantity: 1,
  options: [{ questionId: question.id, answers: [{ id: question.answers[0].id }] }]
})

Last modified on September 15, 2026

expandoptionalstring[]

Relations to include. questions.answers.product.parent loads the product behind each offer and plan answer, with its parent product.

idnumber

ID of the survey.

titlestring

Title of the survey.

appearanceType'before_cart' | 'after_checkout' | 'subscription_box'

When the shop asks the questions: before the item goes in the cart, after the purchase, or inside the subscription box flow.

multiplyPriceByShipmentNumberboolean

Whether an answer price is charged once or once per shipment.

questionsSurveyQuestion[]

The questions, in display order.

customizationsobject

How the survey looks.

progressType'steps' | 'dots' | 'bar' | 'hidden'

The progress indicator.

stylesobject | null

Colours and shapes. Every field is a CSS colour, except buttonStyle and cardStyle, which are numbered presets.

accentColorstring | null

Colour of the highlighted parts.

buttonStylenumber | null

Preset for the buttons.

cardBorderColorstring | null

Border colour of an answer card.

cardStylenumber | null

Preset for the answer cards.

cardDividerColorstring | null

Colour of the line inside an answer card.

fontColorPrimarystring | null

Colour of the main text.

fontColorSecondarystring | null

Colour of the secondary text.

inputBackgroundstring | null

Background of an input.

inputBorderColorstring | null

Border colour of an input.

inputFontColorstring | null

Text colour inside an input.

idnumber

ID of the question. Send it as questionId when you save the answers.

titlestring

The question itself.

descriptionstring | null

Help text under the question.

positionnumber

Place of the question in the survey.

requiredboolean

Whether the customer must answer.

typeSurveyQuestionType

One of text, email, select, multiple, quantity, offer or plan. It sets the shape of answers and the shape of the answer you send back: text and email take { content }, select, multiple, offer and plan take { id }, and quantity takes { id, quantity }.

answersSurveyAnswer[]

The choices. Empty on text and email questions.

minCountnumber | null

Fewest answers the customer may pick. On multiple and quantity questions.

maxCountnumber | null

Most answers the customer may pick. On multiple and quantity questions.

minAmountnumber | null

Smallest total quantity across the answers. On multiple and quantity questions.

maxAmountnumber | null

Largest total quantity across the answers. On multiple and quantity questions.

customizationsobject | null

How the question looks.

createdAtstring

When the question was created.

updatedAtstring

When the question last changed.

idnumber

ID of the answer. Send it as id inside answers when you save the survey.

contentstring | null

The answer text the customer reads.

descriptionstring | null

Longer text under the answer.

imageUrlstring | null

Image for the answer.

positionnumber

Place of the answer in the list.

pricenumber

What the answer adds to the price, in the minor unit of the currency.

defaultboolean

Whether the answer starts selected. On select and plan questions.

defaultQuantitynumber

Quantity the answer starts at. On quantity questions, in place of default.

stockCountnumber | null

Units left for the answer. null means the shop does not track stock for it. On select, multiple and quantity questions.

productIdnumber | null

The product the answer sells. On offer and plan questions.

productProduct | null

That product, as a variant or a plan. On offer and plan questions.

customizationsobject | null

How the answer looks. select answers carry alignContent (start, center or null). plan answers carry highlightType (badge or banner) and highlightText. offer answers carry originalPrice and addonDuration ('1' once, '0' forever).

createdAtstring

When the answer was created.

updatedAtstring

When the answer last changed.

fieldTypestring

The control to draw. text: input, input-numeric, textarea, date, date_month_year or date_month. select: card, tag or dropdown. multiple: card or tag. plan: total, delivery, names, no_price or comparable_period.

placeholderstring | null

Placeholder of the input. On text questions.

listAlignstring | null

How the answers line up: stretch, center, or start on plan questions. On select, multiple and plan questions.

hideImagePlaceholderboolean

Whether to leave out the empty image box. On plan questions.

customHtmlTemplatestring | null

Custom HTML for the offer. On offer questions.