Skip to content

Offer metaobject (Beta)

Reference for the $app:offer metaobject: every preorder offer's storefront settings in one typed, translatable entry, linked from each variant and selling plan.

Last updated

STOQ publishes each preorder offer to the store as a Shopify metaobject. It holds what the storefront needs to show that offer: button and badge text, the shipping promise, payment options, limits, countdown, batches and translations. Each variant on the offer, and each Shopify selling plan the offer owns, points to it.

To read it from a theme or a headless storefront, see Read preorder offers in a theme or headless storefront.

Metaobject type $app:offer. Outside STOQ’s own extensions, use app--5940125--offer.
Handle offer-<offer_id>, for example offer-3f0c9a52-6d1e-4b8e-9a43-1c2d7e5f8a10
One entry per Offer that hasn’t been deleted, whatever its status
Storefront access Public read: Liquid and the Storefront API, with no extra scope
Admin access Read-only for the merchant. Changes made in the Shopify admin are overwritten on the next publish.
Written by STOQ, after any change to the offer and when a schedule starts or ends
Owner Metafield Type Points to
Product variant $app.offer (app--5940125.offer) list.metaobject_reference Every offer the variant is on
Selling plan $app.offer (app--5940125.offer) metaobject_reference The offer that owns the plan, for each payment option’s plan

Read from the variant on a product page: it gives you every offer the variant is on, before the customer has chosen a plan. Read from the selling plan in the cart, or wherever you have a selling plan allocation: it tells you which offer a line was added under.

What’s on the variant, what’s on the offer

Section titled “What’s on the variant, what’s on the offer”

The metaobject holds settings that are the same for every variant on the offer. What changes from one variant to the next stays in the variant’s preorder metafields:

You need Read
Button text, colours, badge, disclaimer Metaobject widget
Shipping line Metaobject shipping. When timeline.scope is per_variant, the date comes from the variant’s shipping_text (market-scoped offers: market_shipping_text)
Units preordered and the variant’s limit Variant preorder_count and preorder_max_count (market-scoped offers: market_preorder_count and market_preorder_max_count)
The batch on sale now for this variant Variant preorder_batch_info
Whether the variant can be bought right now Shopify: the variant’s available and inventory

current_status is the offer’s status when STOQ last published it:

Value Meaning
live Taking preorders.
scheduled Has a start date in the future.
off Turned off, or its end date has passed.

A dated offer is republished within about five minutes of its start or end, so current_status can lag the clock by that much. If you render a scheduled launch to the second, compare availability.starts_at and availability.ends_at with the current time yourself.

A deleted offer’s entry is removed, and so are the variant and selling plan links to it.

After a merchant saves an offer, the metaobject is usually updated within a minute. Variant links are written in bulk and can take a few minutes on a large catalog. Unchanged offers aren’t rewritten. Storefront API responses and Liquid output are cached by Shopify as usual.

Text fields hold what the merchant typed, in the store’s default language. Some contain placeholders that STOQ’s own widget fills in, and you need to fill in yourself:

Placeholder In Replace with
{{ date }} shipping.timeline.shipping_text See The shipping line
{{ month_year }}, {{ year }}, {{ days }} shipping.timeline.shipping_text See The shipping line
{{ payment }} payments.<option>.option_description The amount due at checkout, formatted as money
{{ discount }} payments.<option>.discount_text The discount, as a percentage or money
{{ quantity }}, {{ sold }}, {{ total }} limits.limit_text, limits.progress_bar.progress_text Units left, units preordered, and the limit
{{ batch }}, {{ batch_position }}, {{ batch_ship_text }} widget.disclaimer.disclaimer_text, limits.terms.terms_text The current batch’s label, position and shipping_text (from batches.items). Empty when batches are off.

Text may contain simple HTML, such as bold, links and line breaks. STOQ rejects scripts and other unsafe markup when the text is saved.

shipping.timeline.shipping_text is a sentence such as “Ships {{ date }}”. How you fill it depends on shipping.timeline.scope:

  • same (one date for every variant): replace {{ date }} with the ship date, formatted for the customer. The ship date is shipping.ships_at, or today plus shipping.days_after_checkout. {{ month_year }} and {{ year }} are the same date as month and year, or year only, and {{ days }} is days_after_checkout. With no date (delivery_timing is asap or unknown), use shipping.timeline.variant_shipping_text for {{ date }}, the text the merchant entered.
  • per_variant: replace {{ date }} with the variant’s shipping_text metafield. For an offer limited to some markets, use the variant’s market_shipping_text, keyed by the numeric market id. A variant with neither has no shipping line: hide it.

Show the line only when shipping.timeline.show_shipping_text is true.

translations holds the shop’s other languages, keyed by locale. Each locale holds only the text the merchant translated, at the same paths as the default text. To show a field in the customer’s language, read the translated value and fall back to the default one. A locale is only present when it has at least one translated field.

The metaobject has three text fields and twelve JSON fields. In a JSON field, a key whose value isn’t set is null, never missing. <option> is full or partial; payments has one or both, as options_offered says.

Field Description
offer_id single_line_text_field. The offer’s STOQ id (a UUID). The metaobject handle is offer- followed by this id.
name single_line_text_field. The offer’s name, as the merchant set it in STOQ.
current_status single_line_text_field. live, scheduled or off when it was last published. See Status and timing.

json. The preorder button, the disclaimer line under it, and the badge.

Key Description
button.button_text string, translated. Button label, for example “Preorder now”.
button.custom_colors_enabled boolean. true when the merchant chose button colours. When false, keep your theme’s button style.
button.text_color string. Button text colour, hex.
button.background_color string. Button background colour, hex.
disclaimer.show_disclaimer boolean. Whether to show the disclaimer line under the button.
disclaimer.disclaimer_text string, translated. The disclaimer line. May contain batch placeholders and simple HTML.
disclaimer.text_color string. Disclaimer text colour, hex.
disclaimer.background_color string. Disclaimer background colour, hex.
disclaimer.border_radius integer. Disclaimer corner radius, in pixels.
badge.show_badge boolean. Whether to show a badge on the product image.
badge.badge_text string, translated. Badge text, for example “Preorder”.
badge.text_color string. Badge text colour, hex.
badge.background_color string. Badge background colour, hex.

json. When the preorder button replaces Add to cart.

Key Description
stock_condition enum. out_of_stock: the button shows when the variant is out of stock and Shopify’s “Continue selling when out of stock” is on. in_stock: only while stock is above 0. any_stock_level: whenever the variant can be bought.

json. The shipping promise shown with the button and in the cart.

Key Description
timeline.scope enum. same: one shipping date for every variant. per_variant: each variant may have its own, in the variant’s shipping_text metafield.
timeline.show_shipping_text boolean. Whether to show the shipping line.
timeline.shipping_text string, translated. The shipping line, for example “Ships {{ date }}”. See The shipping line for the placeholders.
timeline.variant_shipping_text string, translated. The merchant’s ship date text, for example “05 Nov 2026”. Use it for {{ date }} when scope is same and there is no ships_at or days_after_checkout.
delivery_timing enum. asap: ships as soon as possible. exact_time: on ships_at, or days_after_checkout days after the order. unknown: no date promised.
ships_at datetime. Ship date, ISO 8601 in UTC. Set only when delivery_timing is exact_time with a fixed date.
days_after_checkout integer. Ships this many days after the order. Set only when delivery_timing is exact_time with a delay.

json. How the customer pays: in full, a deposit, or a choice of both.

Key Description
options_offered enum. full, partial (a deposit), or full_and_partial (the customer picks).
default_option enum. full or partial: the option selected when the page loads.
<option>.selling_plan_id gid. The Shopify selling plan for this option. When advanced.checkout_method is selling_plan, add to cart with its numeric id as selling_plan.
<option>.checkout_charge.charge_type enum. percentage or price: how the amount paid at checkout is expressed.
<option>.checkout_charge.charge_amount number. Paid at checkout: a percentage of the price, or an amount in currency_code. Always 100 (percent) for full.
<option>.price_adjustment.adjustment_type enum. percentage off or fixed_amount off. null when there is no discount.
<option>.price_adjustment.adjustment_amount number. The percentage or amount for adjustment_type. null when there is no discount.
<option>.option_title string, translated. Option label, for example “Pay a deposit”.
<option>.option_description string, translated. Option description. May contain {{ payment }}, the amount due at checkout.
<option>.discount_text string, translated. Savings line. May contain {{ discount }}.
show_payment_widget boolean. Whether to show the payment options and savings.
show_discounted_price boolean. Whether to show the discounted price next to the original.
currency_code string. The shop’s currency (ISO 4217), for fixed amounts.

json. The offer’s schedule.

Key Description
schedule enum. enabled or disabled (no dates), or date_range, starts_on, ends_on.
starts_at datetime. Start, ISO 8601 in UTC, for a dated offer.
ends_at datetime. End, ISO 8601 in UTC, for a dated offer.
current_status enum. Same as the current_status field.

json. Remaining-units display, terms acceptance, and cart rules.

Key Description
display_style enum. How remaining units show: none, disclaimer (in the disclaimer line) or progress_bar.
limit_text string, translated. Remaining-units text. May contain {{ quantity }}, {{ sold }} and {{ total }}.
show_icons boolean. Whether to show icons next to the quantity and shipping lines.
progress_bar.progress_text string, translated. Progress bar text, for example “{{ sold }} of {{ total }} claimed”.
progress_bar.fill_color string. Filled part of the bar, hex.
progress_bar.background_color string. Empty part of the bar, hex.
progress_bar.box_background_color string. Box behind the bar, hex. null means use the disclaimer background.
progress_bar.text_color string. Progress text colour, hex.
progress_bar.border_radius integer. Bar corner radius, in pixels.
progress_bar.show_percentage boolean. Whether to show the percentage next to the bar.
terms.require_acceptance boolean. Whether the customer must tick a terms checkbox.
terms.terms_text string, translated. Text beside the checkbox. May contain batch placeholders and simple HTML.
terms.disable_button_until_accepted boolean. Whether the button stays disabled until the box is ticked.
terms.record_acceptance boolean. Whether acceptance is added to the cart line as a property.
terms.acceptance_label string. Name of that line property.
cart.allowed_items enum. mixed: preorder and in-stock items can share a cart. preorder_only: they can’t.
cart.error_message string, translated. Message for a mixed cart when allowed_items is preorder_only.
order_quantity.minimum integer. Fewest units per order line. null for no minimum.
order_quantity.maximum integer. Most units per order line. null for no maximum.

json. The countdown timer.

Key Description
show_when enum. disabled, before_launch (counts to the start), during_preorder (counts to the end) or both.
date_source enum. schedule (the offer’s dates) or custom (the timer’s own dates).
starts_at datetime. Custom start, ISO 8601 in UTC.
ends_at datetime. Custom end, ISO 8601 in UTC.
starts_text string, translated. Heading before launch, for example “Preorders open in”.
ends_text string, translated. Heading during the preorder, for example “Preorders close in”.
labels.days string, translated. Label for days.
labels.hours string, translated. Label for hours.
labels.minutes string, translated. Label for minutes.
labels.seconds string, translated. Label for seconds.
text_color string. Timer text colour, hex.
background_color string. Timer background colour, hex.
border_radius integer. Timer corner radius, in pixels.
units array. Units to show, from days, hours, minutes, seconds.
current.visible_phase enum. The timer when published: before_launch, during_preorder or hidden.
current.target_at datetime. The moment the visible timer counts to, ISO 8601 in UTC.
current.heading_text string. The heading for the visible phase.
current.starts_at datetime. Start date the timer uses, from the schedule or custom dates.
current.ends_at datetime. End date the timer uses, from the schedule or custom dates.

json. The Shopify Markets the offer applies in.

Key Description
scope enum. all markets, or selected markets only.
shopify_market_ids array. Shopify Market GIDs, when scope is selected.

json. How the preorder reaches checkout, and the cart line properties STOQ adds.

Key Description
checkout_method enum. selling_plan: the preorder is a Shopify selling plan on the line. line_item_property: a plain line with STOQ properties, no selling plan.
cart_attributes.show_payment boolean. Whether STOQ adds the payment details to the cart line.
cart_attributes.show_shipping boolean. Whether STOQ adds the shipping text to the cart line.
cart_attributes.custom_text string, translated. Extra text STOQ adds to every preorder line. null for none.

json. B2B.

Key Description
b2b.enable_b2b boolean. Whether B2B customers can preorder.

json. Batches (waves): stock released in turn, each with its own ship date.

Key Description
release_strategy enum. sequential: one batch on sale at a time. all_at_once: batches are off.
status_text.past string. Word for a batch that has passed, for example “Sold out”.
status_text.live string. Word for the batch on sale now.
status_text.upcoming string. Word for a batch still to come.
widget.style enum. Layout: roadmap, stacked, compact or segmented.
widget.progress enum. counts (units sold of the limit) or percent.
widget.show_other_ship_dates boolean. Whether to list the other batches’ ship dates.
widget.show_names boolean. Whether to show batch names.
items[].position integer. Order of the batch, from 1.
items[].quantity_limit integer. Units in the batch. null when batches have no limits.
items[].shipping_text string. The batch’s ship date text.
items[].label string. The batch’s name, for example “Batch 2”.

json. Text in the shop’s other languages.

Key Description
translations object. Keyed by locale (for example fr). Each value holds only the translated text, at the same paths as above. Fields marked translated can appear here.

Some offer settings only matter in the admin, so they aren’t in the metaobject: the offer’s internal name, product selection rules, order tags, fulfillment holds and order splitting, the remaining-balance charge schedule, POS settings, revenue, and timestamps. The STOQ API returns all of them.

Was this page helpful?

Still stuck? Ask Quinn or chat with support