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.
Before you begin
Section titled “Before you begin”- 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_listingsandunauthenticated_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.
Choose where to read from
Section titled “Choose where to read from”| Where you are | Read | Gives you |
|---|---|---|
| Product page, collection card | The variant’s app--5940125. list |
Every offer the variant is on |
| Cart line with a selling plan | The selling plan’s app--5940125. |
The offer the line was added under |
| A known offer | metaobjects['app--5940125--offer']['offer-<id>'] |
That one offer |
Find the offer for a variant
Section titled “Find the offer for a variant”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.
Show the button text and shipping line
Section titled “Show the button text and shipping line”{%- 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.
tisnilwhen the shop has no translation for that language, and thedefaultfilter takes over. ships_atis in UTC, and thedatefilter shows it in the store’s time zone.- The placeholder is replaced inside the
liquidtag: 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.
Show a badge on collection cards
Section titled “Show a badge on collection cards”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 -%}Offer the payment options
Section titled “Offer the payment options”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.
Label preorder lines in the cart
Section titled “Label preorder lines in the cart”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.
Read offers with the Storefront API
Section titled “Read offers with the Storefront API”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 } } } } } } } } }}Should the button show?
Section titled “Should the button show?”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_ |
Show the preorder button when |
|---|---|
out_ |
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_ |
The variant has stock. |
any_ |
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.
Migrate from the selling_plans metafield
Section titled “Migrate from the selling_plans metafield”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_plansholds 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_planslists enabled offers only. The metaobject includes scheduled and turned-off offers, so you can show “coming soon”.
Field map
Section titled “Field map”selling_ key |
Offer metaobject |
|---|---|
enabled |
current_ is live |
variant_ contains the variant |
The offer is in the variant’s app--5940125. list |
shopify_ |
payments., now a GID |
name |
name |
preorder_ |
widget. |
preorder_ |
widget. |
preorder_, _background_, _border_ |
widget., background_, border_ |
preorder_ |
limits. is disclaimer |
quantity_ |
limits. |
preorder_ |
shipping. |
preorder_ |
shipping. |
shipping_ |
shipping. is same |
delivery_ |
shipping. |
shipping_ |
shipping. |
payment_ |
payments. |
billing_, _amount, _percentage |
payments. |
pricing_, pricing_, pricing_ |
payments. |
billing_, billing_, discount_ |
payments., option_, discount_ |
enable_ |
payments. |
inventory_: stoq, shopify, always |
inventory.: out_, in_, any_ |
preorder_, _text, _text_, _background_ |
widget., badge_, text_, background_ |
translations. |
translations., at the new path |
shopify_ |
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.
Before and after
Section titled “Before and after”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 -%}Troubleshooting
Section titled “Troubleshooting”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.
Thanks for letting us know.
Still stuck? Ask Quinn or chat with support