Skip to content

Read preorder offers in a theme or headless storefront (Beta)

Use the $app:offer metaobject to show preorder buttons, badges, shipping dates and payment options from Liquid or the Storefront API, and move off the selling_plans metafield.

Last updated

STOQ publishes every preorder offer as an offer metaobject, linked from each variant on the offer. This guide shows how to read it. You’ll find the offer that applies to a variant, render its button, badge and shipping line, offer its payment options, and label preorder lines in the cart. It covers Liquid and the Storefront API.

  • The store has STOQ installed and at least one offer with products.
  • Liquid: nothing else. App metafields and metaobjects can always be read from Liquid.
  • Storefront API: an access token with unauthenticated_read_product_listings and unauthenticated_read_metaobjects. STOQ’s metafields and metaobject are public, so nothing else is needed.

Throughout, app--5940125 is STOQ’s namespace. Write it in full: the $app short form only works inside STOQ’s own code.

Where you are Read Gives you
Product page, collection card The variant’s app--5940125.offer list Every offer the variant is on
Cart line with a selling plan The selling plan’s app--5940125.offer The offer the line was added under
A known offer metaobjects['app--5940125--offer']['offer-<id>'] That one offer

A variant can be on more than one offer. For example, it might be on one offer for Canada and a store-wide one for everywhere else. For each variant, keep the offers that are live, and drop those limited to markets the customer isn’t in. If one is limited to the customer’s market, it takes priority over an offer for all markets.

{%- liquid
assign variant = product.selected_or_first_available_variant
assign market_gid = 'gid://shopify/Market/' | append: localization.market.id
assign stoq_offer = nil
for candidate in variant.metafields['app--5940125'].offer.value
if candidate.current_status.value != 'live'
continue
endif
assign markets = candidate.markets.value
if markets.scope == 'selected'
if markets.shopify_market_ids contains market_gid
assign stoq_offer = candidate
break
endif
elsif stoq_offer == nil
assign stoq_offer = candidate
endif
endfor
-%}

stoq_offer is now the offer to show, or nil. The JSON fields (widget, shipping, payments and the rest) are parsed for you: stoq_offer.widget.value.button.button_text is a string.

{%- if stoq_offer -%}
{%- liquid
assign widget = stoq_offer.widget.value
assign shipping = stoq_offer.shipping.value
assign t = stoq_offer.translations.value[request.locale.iso_code]
assign button_text = t.widget.button.button_text | default: widget.button.button_text
assign shipping_line = t.shipping.timeline.shipping_text | default: shipping.timeline.shipping_text
if shipping.timeline.scope == 'per_variant'
assign ship_date = variant.metafields.restockrocket_production.shipping_text.value
elsif shipping.ships_at
assign ship_date = shipping.ships_at | date: '%d %b %Y'
else
assign ship_date = t.shipping.timeline.variant_shipping_text | default: shipping.timeline.variant_shipping_text
endif
assign shipping_line = shipping_line | replace: '{{ date }}', ship_date
-%}
<button type="submit" name="add" class="button"
{%- if widget.button.custom_colors_enabled %}
style="color: {{ widget.button.text_color }}; background: {{ widget.button.background_color }};"
{%- endif %}>
{{ button_text }}
</button>
{%- if shipping.timeline.show_shipping_text and ship_date != blank -%}
<p class="preorder-shipping">{{ shipping_line }}</p>
{%- endif -%}
{%- endif -%}

Notes on this example:

  • The translation lookup reads the customer’s language and falls back to the default text. t is nil when the shop has no translation for that language, and the default filter takes over.
  • ships_at is in UTC, and the date filter shows it in the store’s time zone.
  • The placeholder is replaced inside the liquid tag: a {{ date }} written inside {{ … }} output would end the tag early.
  • For an offer with days_after_checkout, work out the date as today plus that many days, the way STOQ’s widget does. The shipping line lists every placeholder.

On a collection page you have a product, not a selected variant. Show the badge when any variant is on a live offer whose badge is turned on:

{%- liquid
assign preorder_badge = nil
for variant in product.variants
for candidate in variant.metafields['app--5940125'].offer.value
if candidate.current_status.value == 'live'
assign badge = candidate.widget.value.badge
if badge.show_badge
assign preorder_badge = badge
break
endif
endif
endfor
if preorder_badge
break
endif
endfor
-%}
{%- if preorder_badge -%}
<span class="badge" style="color: {{ preorder_badge.text_color }}; background: {{ preorder_badge.background_color }};">
{{ preorder_badge.badge_text }}
</span>
{%- endif -%}

When advanced.checkout_method is selling_plan, each payment option is a Shopify selling plan. Add its numeric id to the product form as selling_plan (product_form_id below is your theme’s product form id), and Shopify applies the deposit, the discount and the balance charge at checkout.

{%- liquid
assign payments = stoq_offer.payments.value
assign uses_selling_plan = false
if stoq_offer.advanced.value.checkout_method == 'selling_plan'
assign uses_selling_plan = true
endif
-%}
{%- if uses_selling_plan -%}
{%- assign kinds = 'full,partial' | split: ',' -%}
{%- for kind in kinds -%}
{%- assign option = payments[kind] -%}
{%- if option -%}
<label>
<input type="radio" name="selling_plan" form="{{ product_form_id }}"
value="{{ option.selling_plan_id | split: '/' | last }}"
{% if payments.default_option == kind %}checked{% endif %}>
{{ option.option_title }}
</label>
{%- endif -%}
{%- endfor -%}
{%- endif -%}

option_description and discount_text can contain {{ payment }} and {{ discount }}. Replace them with the amount due at checkout and the saving, worked out from checkout_charge, price_adjustment and the variant price.

A cart line added with a selling plan belongs to the offer that owns that plan. In Liquid, compare the line’s selling plan with each of the variant’s offers:

{%- for item in cart.items -%}
{%- assign plan_id = item.selling_plan_allocation.selling_plan.id -%}
{%- if plan_id -%}
{%- for candidate in item.variant.metafields['app--5940125'].offer.value -%}
{%- assign payments = candidate.payments.value -%}
{%- assign full_id = payments.full.selling_plan_id | split: '/' | last | plus: 0 -%}
{%- assign partial_id = payments.partial.selling_plan_id | split: '/' | last | plus: 0 -%}
{%- if plan_id == full_id or plan_id == partial_id -%}
<p class="cart-item__preorder">{{ candidate.name.value }}</p>
{%- break -%}
{%- endif -%}
{%- endfor -%}
{%- endif -%}
{%- endfor -%}

An offer whose checkout_method is line_item_property adds no selling plan. Its lines carry STOQ’s line item properties instead, and you can show those as they are.

The same data is available to a headless storefront. Request the variant’s offers with the fields you need. Each JSON field arrives as a string, so parse it.

query VariantOffers($handle: String!, $country: CountryCode)
@inContext(country: $country) {
localization {
market { id }
}
product(handle: $handle) {
variants(first: 100) {
nodes {
id
availableForSale
currentlyNotInStock
shippingText: metafield(namespace: "restockrocket_production", key: "shipping_text") { value }
offers: metafield(namespace: "app--5940125", key: "offer") {
references(first: 10) {
nodes {
... on Metaobject {
handle
status: field(key: "current_status") { value }
widget: field(key: "widget") { value }
shipping: field(key: "shipping") { value }
payments: field(key: "payments") { value }
markets: field(key: "markets") { value }
translations: field(key: "translations") { value }
}
}
}
}
}
}
}
}

Then pick the offer the same way as in Liquid:

type Field = { value: string } | null
type OfferNode = {
handle: string
status: Field
widget: Field
shipping: Field
payments: Field
markets: Field
translations: Field
}
const parse = (field: Field) => (field ? JSON.parse(field.value) : null)
export function offerFor(offers: OfferNode[], marketId: string) {
let storeWide: OfferNode | null = null
for (const offer of offers) {
if (offer.status?.value !== 'live') continue
const markets = parse(offer.markets)
if (markets?.scope === 'selected') {
if (markets.shopify_market_ids.includes(marketId)) return offer
} else {
storeWide ??= offer
}
}
return storeWide
}
// "Ships {{ date }}" filled in for the shopper's language, or null to hide the line.
export function shippingLine(offer: OfferNode, variantShippingText: string | null, locale: string) {
const shipping = parse(offer.shipping)
const translated = parse(offer.translations)?.[locale]?.shipping?.timeline ?? {}
if (!shipping.timeline.show_shipping_text) return null
let date: string | null
if (shipping.timeline.scope === 'per_variant') {
date = variantShippingText
} else if (shipping.ships_at) {
date = new Intl.DateTimeFormat(locale, { dateStyle: 'medium' }).format(new Date(shipping.ships_at))
} else {
date = translated.variant_shipping_text ?? shipping.timeline.variant_shipping_text
}
if (!date) return null
const sentence = translated.shipping_text ?? shipping.timeline.shipping_text
return sentence.replaceAll('{{ date }}', date)
}

localization.market.id and shopify_market_ids are both market GIDs, so they compare directly. Translation keys are the shop’s locale codes, such as fr or pt-BR.

In a cart, read the offer from each line’s selling plan:

query CartOffers($cartId: ID!) {
cart(id: $cartId) {
lines(first: 100) {
nodes {
id
sellingPlanAllocation {
sellingPlan {
offer: metafield(namespace: "app--5940125", key: "offer") {
reference {
... on Metaobject {
name: field(key: "name") { value }
shipping: field(key: "shipping") { value }
}
}
}
}
}
}
}
}
}

The metaobject tells you how an offer looks. Whether a variant is on preorder at this moment also depends on its stock, which changes between publishes. Combine inventory.stock_condition with the variant’s stock:

stock_condition Show the preorder button when
out_of_stock The variant is out of stock and can still be bought (Shopify’s “Continue selling when out of stock” is on). In the Storefront API: availableForSale and currentlyNotInStock are both true.
in_stock The variant has stock.
any_stock_level The variant can be bought at all.

Then check the variant’s limit. When preorder_max_count is set and preorder_count has reached it, the variant is sold out for preorder.

To let STOQ decide instead, call the variant availability endpoint from your server.

The shop-level selling_plans metafield still works, and STOQ keeps writing it. New work should read the metaobject:

  • It loads only what a page needs. selling_plans holds every enabled offer with all of its variant ids, in one value that grows with the catalog. The metaobject is one entry per offer, reached from the variants that use it.
  • It has the full offer. Countdown, batches, markets, terms, cart rules and every payment option are included, with stable names and documented values.
  • It covers every status. selling_plans lists enabled offers only. The metaobject includes scheduled and turned-off offers, so you can show “coming soon”.
selling_plans key Offer metaobject
enabled current_status is live
variant_ids contains the variant The offer is in the variant’s app--5940125.offer list
shopify_selling_plan_id payments.<option>.selling_plan_id, now a GID
name name
preorder_button_text widget.button.button_text
preorder_button_description widget.disclaimer.disclaimer_text
preorder_button_description_text_color, _background_color, _border_radius widget.disclaimer.text_color, background_color, border_radius
preorder_button_description_show_quantity_limit limits.display_style is disclaimer
quantity_limit_text limits.limit_text
preorder_button_description_show_shipping shipping.timeline.show_shipping_text
preorder_shipping_text shipping.timeline.shipping_text
shipping_applies_to_all_products shipping.timeline.scope is same
delivery_exact_time shipping.ships_at
shipping_text shipping.timeline.variant_shipping_text
payment_type payments.options_offered
billing_checkout_charge_type, _amount, _percentage payments.<option>.checkout_charge
pricing_type, pricing_amount, pricing_percentage payments.<option>.price_adjustment
billing_title, billing_description, discount_text payments.<option>.option_title, option_description, discount_text
enable_billing_widget payments.show_payment_widget
inventory_provider: stoq, shopify, always inventory.stock_condition: out_of_stock, in_stock, any_stock_level
preorder_badge_enabled, _text, _text_color, _background_color widget.badge.show_badge, badge_text, text_color, background_color
translations.<locale>.<key> translations.<locale>, at the new path
shopify_selling_plan_group_id Not published. Use the STOQ API.

preorder_button_description_quantity_limit_suffix and preorder_button_description_shipping_text_prefix have no equivalent. STOQ’s widget no longer uses them.

Showing the button text for the selected variant, before:

{%- assign variant_id = product.selected_or_first_available_variant.id | append: '' -%}
{%- for plan in shop.metafields.restockrocket_production.selling_plans.value -%}
{%- if plan.enabled and plan.variant_ids contains variant_id -%}
{{ plan.preorder_button_text }}
{%- break -%}
{%- endif -%}
{%- endfor -%}

After:

{%- for offer in product.selected_or_first_available_variant.metafields['app--5940125'].offer.value -%}
{%- if offer.current_status.value == 'live' -%}
{{ offer.widget.value.button.button_text }}
{%- break -%}
{%- endif -%}
{%- endfor -%}

The append: '' cast goes: the metaobject list holds offers, not ids, so there’s nothing to match. If the store sells in several markets, use the market check from Find the offer for a variant.

While the metaobject is in Beta, fall back to selling_plans when a variant’s offer list is empty:

{%- assign stoq_offers = variant.metafields['app--5940125'].offer.value -%}
{%- if stoq_offers == blank -%}
{%- comment -%} Read shop.metafields.restockrocket_production.selling_plans as before. {%- endcomment -%}
{%- endif -%}

The variant’s offer list is empty. Check that you wrote app--5940125, not $app. If the variant was added to an offer in the last few minutes, its link may not be written yet. On a large catalog, links are written in bulk and can take longer. A variant that’s on no offer has no list at all.

An offer shows old settings. Shopify caches storefront responses, and STOQ rewrites an offer within about a minute of a change. A dated offer’s current_status changes within about five minutes of its start or end.

current_status is live but STOQ’s widget shows no button. The variant is on the offer but isn’t on preorder: check its stock against stock_condition, and its limit.

A text field shows {{ … }}. Fill the placeholder yourself. The reference lists every one.

Was this page helpful?

Still stuck? Ask Quinn or chat with support