Funnels

Offers before, during, and after the purchase: get the next one, accept it, or skip it.

A funnel has three phases: pre-purchase, mid-purchase and post-purchase. In each phase you fetch the next step, then accept it or skip it, and fetch again until step is null. For the full flow, with one example per phase, see Run a funnel.

subbly.funnels.prePurchaseFetch(cartId, params?)

Gets the next pre-purchase offer for the cart. step comes back null once the customer has seen every offer.

Method parameters

cartIdRequiredstring

ID of the cart, usually subbly.cart.id.

paramsoptionalFunnelsResourceParams

Extra data to include.

ReturnsPromise<FunnelFetchResponse>

The next offer, or an empty one.


Show the next offer
const { step } = await subbly.funnels.prePurchaseFetch(subbly.cart.id, {
  expand: ['parent']
})

if (step) render(step)

subbly.funnels.prePurchaseAccept(cartId, funnelStepId, payload, params?)

Accepts a pre-purchase offer and adds its products to the cart.

The cart it returns is a plain object, not the subbly.cart model, so subbly.cart still holds the old contents. Reload it with subbly.cart.load().

Method parameters

cartIdRequiredstring

ID of the cart.

funnelStepIdRequirednumber

ID of the step the customer accepted, from step.id.

payloadRequiredFunnelAcceptPayload

The products the customer took.

paramsoptionalCartResourceParams

Extra data to include on the cart that comes back.

ReturnsPromise<SubblyCart>

The cart after the offer went in.


Accept an offer
await subbly.funnels.prePurchaseAccept(subbly.cart.id, step.id, {
  offers: [{ productId: step.offer.products[0].id }]
})

await subbly.cart.load()

subbly.funnels.prePurchaseReject(cartId, funnelStepId)

Skips a pre-purchase offer. Subbly records the refusal, so the next fetch moves on to the following step.

Method parameters

cartIdRequiredstring

ID of the cart.

funnelStepIdRequirednumber

ID of the step the customer skipped.

ReturnsPromise<void>

Nothing. The response body is empty.


Skip an offer
await subbly.funnels.prePurchaseReject(subbly.cart.id, step.id)

const { step: next } = await subbly.funnels.prePurchaseFetch(subbly.cart.id)

subbly.funnels.prePurchaseRefresh(cartId)

Clears which pre-purchase offers the customer accepted or skipped, so the sequence starts from the first step again. Only the pre-purchase phase has this.

Method parameters

cartIdRequiredstring

ID of the cart.

ReturnsPromise<unknown>

Nothing you need to read. Treat the response as empty.


Start the offers again
await subbly.funnels.prePurchaseRefresh(subbly.cart.id)

subbly.funnels.midPurchaseFetch(cartId, params?)

Gets the next mid-purchase offer for the cart. Show these while the customer works through checkout.

Method parameters

cartIdRequiredstring

ID of the cart.

paramsoptionalFunnelsResourceParams

Extra data to include.

ReturnsPromise<FunnelFetchResponse>

The next offer, or an empty one.


Show the next offer
const { step } = await subbly.funnels.midPurchaseFetch(subbly.cart.id)

subbly.funnels.midPurchaseAccept(cartId, funnelStepId, payload, params?)

Accepts a mid-purchase offer and adds its products to the cart. As with the pre-purchase accept, reload subbly.cart afterwards.

Method parameters

cartIdRequiredstring

ID of the cart.

funnelStepIdRequirednumber

ID of the step the customer accepted.

payloadRequiredFunnelAcceptPayload

The products the customer took.

paramsoptionalCartResourceParams

Extra data to include on the cart that comes back.

expandoptionalstring[]

Cart relations to include.

ReturnsPromise<SubblyCart>

The cart after the offer went in.


Accept an offer
await subbly.funnels.midPurchaseAccept(subbly.cart.id, step.id, {
  offers: [{ productId: step.offer.products[0].id }]
})

await subbly.cart.load()

subbly.funnels.midPurchaseReject(cartId, funnelStepId)

Skips a mid-purchase offer so the next fetch moves on.

Method parameters

cartIdRequiredstring

ID of the cart.

funnelStepIdRequirednumber

ID of the step the customer skipped.

ReturnsPromise<void>

Nothing. The response body is empty.


Skip an offer
await subbly.funnels.midPurchaseReject(subbly.cart.id, step.id)

subbly.funnels.postPurchaseFetch(cartId, params?)

Gets the next post-purchase offer for the cart. These run only after subbly.checkout.purchase succeeds, on the thank-you page.

Method parameters

cartIdRequiredstring

ID of the cart that was paid.

paramsoptionalFunnelsResourceParams

Extra data to include.

ReturnsPromise<FunnelFetchResponse>

The next offer, or an empty one.


Show the next offer after checkout
await subbly.checkout.purchase(subbly.cart.id)

const { step } = await subbly.funnels.postPurchaseFetch(subbly.cart.id)

subbly.funnels.postPurchaseAccept(cartId, funnelStepId, payload, params?)

Accepts a post-purchase offer and charges it as a new purchase on the card the customer already used. Unlike the other two accepts, this one returns the invoice, subscription and orders it created. Needs an authenticated customer.

Method parameters

cartIdRequiredstring

ID of the cart that was paid.

funnelStepIdRequirednumber

ID of the step the customer accepted.

payloadRequiredFunnelPostAcceptPayload

The products taken, and anything the purchase still needs.

paramsoptionalCartResourceParams

Extra data to include in the response.

ReturnsPromise<FunnelPostAcceptResponse>

What the extra purchase created.


Accept a post-purchase offer
const { invoice, orders } = await subbly.funnels.postPurchaseAccept(
  subbly.cart.id,
  step.id,
  { offers: [{ productId: step.offer.products[0].id }] }
)

subbly.funnels.postPurchaseReject(cartId, funnelStepId)

Skips a post-purchase offer so the next fetch moves on.

Method parameters

cartIdRequiredstring

ID of the cart that was paid.

funnelStepIdRequirednumber

ID of the step the customer skipped.

ReturnsPromise<void>

Nothing. The response body is empty.


Skip an offer
await subbly.funnels.postPurchaseReject(subbly.cart.id, step.id)

Last modified on September 15, 2026

Funnels

Offers before, during, and after the purchase: get the next one, accept it, or skip it.

subbly.funnels.prePurchaseFetch(cartId, params?)

Gets the next pre-purchase offer for the cart. step comes back null once the customer has seen every offer.

Method parameters

cartIdRequiredstring

ID of the cart, usually subbly.cart.id.

paramsoptionalFunnelsResourceParams

Extra data to include.

expandoptionalstring[]

Relations to include. parent loads the parent product of each offered variant or plan.

ReturnsPromise<FunnelFetchResponse>

The next offer, or an empty one.

stepFunnelStep | null

The offer to show. null means there is nothing left to offer.


Show the next offer
const { step } = await subbly.funnels.prePurchaseFetch(subbly.cart.id, {
  expand: ['parent']
})

if (step) render(step)

subbly.funnels.prePurchaseAccept(cartId, funnelStepId, payload, params?)

Accepts a pre-purchase offer and adds its products to the cart.

The cart it returns is a plain object, not the subbly.cart model, so subbly.cart still holds the old contents. Reload it with subbly.cart.load().

Method parameters

cartIdRequiredstring

ID of the cart.

funnelStepIdRequirednumber

ID of the step the customer accepted, from step.id.

payloadRequiredFunnelAcceptPayload

The products the customer took.

offersRequiredFunnelOfferPayload[]

One entry per product taken.

productIdRequirednumber

The variant or plan the customer picked, from step.offer.products[].id.

optionsoptionalSubscriptionSurveyOption[]

Survey answers, when the offered plan has a survey. Each entry is { 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.

paramsoptionalCartResourceParams

Extra data to include on the cart that comes back.

expandoptionalstring[]

Cart relations to include, such as items.product and items.product.parent.

ReturnsPromise<SubblyCart>

The cart after the offer went in.

idstring

UUID of the cart. Pass it to subbly.checkout.purchase and to the funnel methods.

shopIdnumber

ID of the shop the cart belongs to.

statusstring

initialized, abandoned, expired, completed or restored. A completed cart cannot be changed.

attachedboolean

true once a signed-in customer owns the cart. subbly.cart.attachCustomer sets it.

createdAtstring

When the cart was created.

updatedAtstring

When the cart last changed.

currencyCodestring

Currency of the cart, such as USD. Change it with subbly.cart.update({ currencyCode }).

baseCurrencyCodestring

Base currency of the shop.

subTotalnumber

Sum of the lines before discount and tax.

discountTotalnumber

Total taken off by coupons, offers, referrals and gift cards.

taxTotalnumber

Total tax.

taxRatenumber

Cart-level tax rate. Single lines may use their own rate.

customsFeenumber

Customs charge on this order.

futureCustomsFeenumber

Customs charge on each later renewal.

adjustmentnumber

A manual correction. It may be negative.

totalnumber

Grand total, across what is charged now and what is charged later. Read summaryItems[].chargeNow to split the two.

balanceChangeobject

How much store credit the cart uses.

itemsCartItem[]

The lines the customer added. They hold no money fields; the prices live in summaryItems.

summaryItemsCartSummaryItem[]

The priced lines. Every item produces one or more of these, and shipping adds one of its own. Match them back with itemId.

discountsobject[]

The cart-level discounts.

customerIdnumber | null

ID of the customer who owns the cart. Set only after subbly.cart.attachCustomer.

customerobject | null

Guest details written straight onto the cart. null once a customer is attached. This is not a SubblyCustomer: id, userId and createdAt are always null.

couponCodestring | null

The coupon code on the cart.

couponCoupon | null

The coupon itself. The API sends it only when you ask for the coupon expand.

giftCardCodestring | null

The gift card code on the cart.

giftCardGiftCard | null

The gift card itself. The API sends it only when you ask for the gift_card expand.

referralIdnumber | null

ID of the referral that led to this cart.

giftInfoobject

Gift settings. Always an object; every member is null when the cart is not a gift.

startsAtstring | null

When the subscription starts. Pick a date from subbly.cart.getStartDates().

shippingAddressIdnumber | null

ID of the saved address or pick-up info used for delivery.

shippingAddressCustomerAddress | CustomerPickupInfo | null

The delivery address. The API sends it only when you ask for the shipping_address expand. A pick-up info arrives instead when the cart ships to a pick-up point; its fields are on the Pick-up info page.

billingAddressIdnumber | null

ID of the saved billing address.

billingAddressCustomerAddress | null

The billing address. The API sends it only when you ask for the billing_address expand. Same fields as shippingAddress.

shippingMethodIdnumber | null

ID of the delivery option chosen.

shippingMethodShippingMethod | null

The delivery option itself. The API sends it only when you ask for the shipping_method expand. Read type to tell a carrier delivery, a local delivery and a pick-up point apart.

shippingCarrierIdnumber | null

ID of the carrier chosen.

shippingCarrierobject | null

The carrier chosen, with id, name and serviceCodes. The API sends it only when you ask for the shipping_carrier expand.

shippingCarrierServicestring | null

The carrier service chosen, from serviceCodes.

paymentMethodIdnumber | null

ID of the payment method to charge. Only a signed-in customer has one.

paymentMethodPaymentMethod | null

The payment method itself. The API sends it only when you ask for the payment_method expand, and only for a signed-in customer.

metadataMetafield[] | null

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

onboardingTemplateIdnumber | null

ID of the onboarding template applied to the cart.


Accept an offer
await subbly.funnels.prePurchaseAccept(subbly.cart.id, step.id, {
  offers: [{ productId: step.offer.products[0].id }]
})

await subbly.cart.load()

subbly.funnels.prePurchaseReject(cartId, funnelStepId)

Skips a pre-purchase offer. Subbly records the refusal, so the next fetch moves on to the following step.

Method parameters

cartIdRequiredstring

ID of the cart.

funnelStepIdRequirednumber

ID of the step the customer skipped.

ReturnsPromise<void>

Nothing. The response body is empty.


Skip an offer
await subbly.funnels.prePurchaseReject(subbly.cart.id, step.id)

const { step: next } = await subbly.funnels.prePurchaseFetch(subbly.cart.id)

subbly.funnels.prePurchaseRefresh(cartId)

Clears which pre-purchase offers the customer accepted or skipped, so the sequence starts from the first step again. Only the pre-purchase phase has this.

Method parameters

cartIdRequiredstring

ID of the cart.

ReturnsPromise<unknown>

Nothing you need to read. Treat the response as empty.


Start the offers again
await subbly.funnels.prePurchaseRefresh(subbly.cart.id)

subbly.funnels.midPurchaseFetch(cartId, params?)

Gets the next mid-purchase offer for the cart. Show these while the customer works through checkout.

Method parameters

cartIdRequiredstring

ID of the cart.

paramsoptionalFunnelsResourceParams

Extra data to include.

expandoptionalstring[]

Relations to include. parent loads the parent product of each offered variant or plan.

ReturnsPromise<FunnelFetchResponse>

The next offer, or an empty one.

stepFunnelStep | null

The offer to show. null means there is nothing left to offer.


Show the next offer
const { step } = await subbly.funnels.midPurchaseFetch(subbly.cart.id)

subbly.funnels.midPurchaseAccept(cartId, funnelStepId, payload, params?)

Accepts a mid-purchase offer and adds its products to the cart. As with the pre-purchase accept, reload subbly.cart afterwards.

Method parameters

cartIdRequiredstring

ID of the cart.

funnelStepIdRequirednumber

ID of the step the customer accepted.

payloadRequiredFunnelAcceptPayload

The products the customer took.

offersRequiredFunnelOfferPayload[]

One entry per product taken.

productIdRequirednumber

The variant or plan the customer picked.

optionsoptionalSubscriptionSurveyOption[]

Survey answers, when the offered plan has a survey. Each entry is { questionId, answers }.

paramsoptionalCartResourceParams

Extra data to include on the cart that comes back.

expandoptionalstring[]

Cart relations to include.

ReturnsPromise<SubblyCart>

The cart after the offer went in.

idstring

UUID of the cart. Pass it to subbly.checkout.purchase and to the funnel methods.

shopIdnumber

ID of the shop the cart belongs to.

statusstring

initialized, abandoned, expired, completed or restored. A completed cart cannot be changed.

attachedboolean

true once a signed-in customer owns the cart. subbly.cart.attachCustomer sets it.

createdAtstring

When the cart was created.

updatedAtstring

When the cart last changed.

currencyCodestring

Currency of the cart, such as USD. Change it with subbly.cart.update({ currencyCode }).

baseCurrencyCodestring

Base currency of the shop.

subTotalnumber

Sum of the lines before discount and tax.

discountTotalnumber

Total taken off by coupons, offers, referrals and gift cards.

taxTotalnumber

Total tax.

taxRatenumber

Cart-level tax rate. Single lines may use their own rate.

customsFeenumber

Customs charge on this order.

futureCustomsFeenumber

Customs charge on each later renewal.

adjustmentnumber

A manual correction. It may be negative.

totalnumber

Grand total, across what is charged now and what is charged later. Read summaryItems[].chargeNow to split the two.

balanceChangeobject

How much store credit the cart uses.

itemsCartItem[]

The lines the customer added. They hold no money fields; the prices live in summaryItems.

summaryItemsCartSummaryItem[]

The priced lines. Every item produces one or more of these, and shipping adds one of its own. Match them back with itemId.

discountsobject[]

The cart-level discounts.

customerIdnumber | null

ID of the customer who owns the cart. Set only after subbly.cart.attachCustomer.

customerobject | null

Guest details written straight onto the cart. null once a customer is attached. This is not a SubblyCustomer: id, userId and createdAt are always null.

couponCodestring | null

The coupon code on the cart.

couponCoupon | null

The coupon itself. The API sends it only when you ask for the coupon expand.

giftCardCodestring | null

The gift card code on the cart.

giftCardGiftCard | null

The gift card itself. The API sends it only when you ask for the gift_card expand.

referralIdnumber | null

ID of the referral that led to this cart.

giftInfoobject

Gift settings. Always an object; every member is null when the cart is not a gift.

startsAtstring | null

When the subscription starts. Pick a date from subbly.cart.getStartDates().

shippingAddressIdnumber | null

ID of the saved address or pick-up info used for delivery.

shippingAddressCustomerAddress | CustomerPickupInfo | null

billingAddressIdnumber | null

ID of the saved billing address.

billingAddressCustomerAddress | null

The billing address. The API sends it only when you ask for the billing_address expand. Same fields as shippingAddress.

shippingMethodIdnumber | null

ID of the delivery option chosen.

shippingMethodShippingMethod | null

The delivery option itself. The API sends it only when you ask for the shipping_method expand. Read type to tell a carrier delivery, a local delivery and a pick-up point apart.

shippingCarrierIdnumber | null

ID of the carrier chosen.

shippingCarrierobject | null

The carrier chosen, with id, name and serviceCodes. The API sends it only when you ask for the shipping_carrier expand.

shippingCarrierServicestring | null

The carrier service chosen, from serviceCodes.

paymentMethodIdnumber | null

ID of the payment method to charge. Only a signed-in customer has one.

paymentMethodPaymentMethod | null

The payment method itself. The API sends it only when you ask for the payment_method expand, and only for a signed-in customer.

metadataMetafield[] | null

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

onboardingTemplateIdnumber | null

ID of the onboarding template applied to the cart.


Accept an offer
await subbly.funnels.midPurchaseAccept(subbly.cart.id, step.id, {
  offers: [{ productId: step.offer.products[0].id }]
})

await subbly.cart.load()

subbly.funnels.midPurchaseReject(cartId, funnelStepId)

Skips a mid-purchase offer so the next fetch moves on.

Method parameters

cartIdRequiredstring

ID of the cart.

funnelStepIdRequirednumber

ID of the step the customer skipped.

ReturnsPromise<void>

Nothing. The response body is empty.


Skip an offer
await subbly.funnels.midPurchaseReject(subbly.cart.id, step.id)

subbly.funnels.postPurchaseFetch(cartId, params?)

Gets the next post-purchase offer for the cart. These run only after subbly.checkout.purchase succeeds, on the thank-you page.

Method parameters

cartIdRequiredstring

ID of the cart that was paid.

paramsoptionalFunnelsResourceParams

Extra data to include.

expandoptionalstring[]

Relations to include. parent loads the parent product of each offered variant or plan.

ReturnsPromise<FunnelFetchResponse>

The next offer, or an empty one.

stepFunnelStep | null

The offer to show. null means there is nothing left to offer.


Show the next offer after checkout
await subbly.checkout.purchase(subbly.cart.id)

const { step } = await subbly.funnels.postPurchaseFetch(subbly.cart.id)

subbly.funnels.postPurchaseAccept(cartId, funnelStepId, payload, params?)

Method parameters

cartIdRequiredstring

ID of the cart that was paid.

funnelStepIdRequirednumber

ID of the step the customer accepted.

payloadRequiredFunnelPostAcceptPayload

The products taken, and anything the purchase still needs.

offersRequiredFunnelOfferPayload[]

One entry per product taken.

productIdRequirednumber

The variant or plan the customer picked.

optionsoptionalSubscriptionSurveyOption[]

Survey answers, when the offered plan has a survey.

shippingAddressIdoptionalnumber | null

Address to ship to. Send it when the checkout did not set one.

shippingMethodIdoptionalnumber | null

Delivery option to use. Send it when the checkout did not set one.

paymentIntentIdoptionalstring | null

The payment intent you confirmed, when you retry after 3-D Secure.

paramsoptionalCartResourceParams

Extra data to include in the response.

expandoptionalstring[]

Relations to include, such as subscription.product and order.metadata.

ReturnsPromise<FunnelPostAcceptResponse>

What the extra purchase created.


Accept a post-purchase offer
const { invoice, orders } = await subbly.funnels.postPurchaseAccept(
  subbly.cart.id,
  step.id,
  { offers: [{ productId: step.offer.products[0].id }] }
)

subbly.funnels.postPurchaseReject(cartId, funnelStepId)

Skips a post-purchase offer so the next fetch moves on.

Method parameters

cartIdRequiredstring

ID of the cart that was paid.

funnelStepIdRequirednumber

ID of the step the customer skipped.

ReturnsPromise<void>

Nothing. The response body is empty.


Skip an offer
await subbly.funnels.postPurchaseReject(subbly.cart.id, step.id)

Last modified on September 15, 2026