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.
At a glance
Section titled “At a glance”| Metaobject type | $app:offer. Outside STOQ’s own extensions, use app--5940125--offer. |
| Handle | offer-<offer_, 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 |
How offers are linked
Section titled “How offers are linked”| Owner | Metafield | Type | Points to |
|---|---|---|---|
| Product variant | $app. (app--5940125.) |
list. |
Every offer the variant is on |
| Selling plan | $app. (app--5940125.) |
metaobject_ |
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. is per_, the date comes from the variant’s shipping_ (market-scoped offers: market_) |
| Units preordered and the variant’s limit | Variant preorder_ and preorder_ (market-scoped offers: market_ and market_) |
| The batch on sale now for this variant | Variant preorder_ |
| Whether the variant can be bought right now | Shopify: the variant’s available and inventory |
Status and timing
Section titled “Status and timing”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.
When changes appear
Section titled “When changes appear”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, placeholders and translations
Section titled “Text, placeholders and translations”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. |
See The shipping line |
{{ month_, {{ year }}, {{ days }} |
shipping. |
See The shipping line |
{{ payment }} |
payments. |
The amount due at checkout, formatted as money |
{{ discount }} |
payments. |
The discount, as a percentage or money |
{{ quantity }}, {{ sold }}, {{ total }} |
limits., limits. |
Units left, units preordered, and the limit |
{{ batch }}, {{ batch_, {{ batch_ |
widget., limits. |
The current batch’s label, position and shipping_ (from batches.). 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.
The shipping line
Section titled “The shipping line”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 isshipping.ships_at, or today plusshipping.days_after_checkout.{{ month_year }}and{{ year }}are the same date as month and year, or year only, and{{ days }}isdays_after_checkout. With no date (delivery_timingisasaporunknown), useshipping.timeline.variant_shipping_textfor{{ date }}, the text the merchant entered.per_variant: replace{{ date }}with the variant’sshipping_textmetafield. For an offer limited to some markets, use the variant’smarket_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
Section titled “Translations”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.
Fields
Section titled “Fields”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.
Text fields
Section titled “Text fields”| Field | Description |
|---|---|
offer_ |
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_ |
single_line_text_field. live, scheduled or off when it was last published. See Status and timing. |
widget
Section titled “widget”json. The preorder button, the disclaimer line under it, and the badge.
| Key | Description |
|---|---|
button. |
string, translated. Button label, for example “Preorder now”. |
button. |
boolean. true when the merchant chose button colours. When false, keep your theme’s button style. |
button. |
string. Button text colour, hex. |
button. |
string. Button background colour, hex. |
disclaimer. |
boolean. Whether to show the disclaimer line under the button. |
disclaimer. |
string, translated. The disclaimer line. May contain batch placeholders and simple HTML. |
disclaimer. |
string. Disclaimer text colour, hex. |
disclaimer. |
string. Disclaimer background colour, hex. |
disclaimer. |
integer. Disclaimer corner radius, in pixels. |
badge. |
boolean. Whether to show a badge on the product image. |
badge. |
string, translated. Badge text, for example “Preorder”. |
badge. |
string. Badge text colour, hex. |
badge. |
string. Badge background colour, hex. |
inventory
Section titled “inventory”json. When the preorder button replaces Add to cart.
| Key | Description |
|---|---|
stock_ |
enum. out_: the button shows when the variant is out of stock and Shopify’s “Continue selling when out of stock” is on. in_: only while stock is above 0. any_: whenever the variant can be bought. |
shipping
Section titled “shipping”json. The shipping promise shown with the button and in the cart.
| Key | Description |
|---|---|
timeline. |
enum. same: one shipping date for every variant. per_: each variant may have its own, in the variant’s shipping_ metafield. |
timeline. |
boolean. Whether to show the shipping line. |
timeline. |
string, translated. The shipping line, for example “Ships {{ date }}”. See The shipping line for the placeholders. |
timeline. |
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_ or days_. |
delivery_ |
enum. asap: ships as soon as possible. exact_: on ships_, or days_ days after the order. unknown: no date promised. |
ships_ |
datetime. Ship date, ISO 8601 in UTC. Set only when delivery_ is exact_ with a fixed date. |
days_ |
integer. Ships this many days after the order. Set only when delivery_ is exact_ with a delay. |
payments
Section titled “payments”json. How the customer pays: in full, a deposit, or a choice of both.
| Key | Description |
|---|---|
options_ |
enum. full, partial (a deposit), or full_ (the customer picks). |
default_ |
enum. full or partial: the option selected when the page loads. |
<option>. |
gid. The Shopify selling plan for this option. When advanced. is selling_, add to cart with its numeric id as selling_. |
<option>. |
enum. percentage or price: how the amount paid at checkout is expressed. |
<option>. |
number. Paid at checkout: a percentage of the price, or an amount in currency_. Always 100 (percent) for full. |
<option>. |
enum. percentage off or fixed_ off. null when there is no discount. |
<option>. |
number. The percentage or amount for adjustment_. null when there is no discount. |
<option>. |
string, translated. Option label, for example “Pay a deposit”. |
<option>. |
string, translated. Option description. May contain {{ payment }}, the amount due at checkout. |
<option>. |
string, translated. Savings line. May contain {{ discount }}. |
show_ |
boolean. Whether to show the payment options and savings. |
show_ |
boolean. Whether to show the discounted price next to the original. |
currency_ |
string. The shop’s currency (ISO 4217), for fixed amounts. |
availability
Section titled “availability”json. The offer’s schedule.
| Key | Description |
|---|---|
schedule |
enum. enabled or disabled (no dates), or date_, starts_, ends_. |
starts_ |
datetime. Start, ISO 8601 in UTC, for a dated offer. |
ends_ |
datetime. End, ISO 8601 in UTC, for a dated offer. |
current_ |
enum. Same as the current_ field. |
limits
Section titled “limits”json. Remaining-units display, terms acceptance, and cart rules.
| Key | Description |
|---|---|
display_ |
enum. How remaining units show: none, disclaimer (in the disclaimer line) or progress_. |
limit_ |
string, translated. Remaining-units text. May contain {{ quantity }}, {{ sold }} and {{ total }}. |
show_ |
boolean. Whether to show icons next to the quantity and shipping lines. |
progress_ |
string, translated. Progress bar text, for example “{{ sold }} of {{ total }} claimed”. |
progress_ |
string. Filled part of the bar, hex. |
progress_ |
string. Empty part of the bar, hex. |
progress_ |
string. Box behind the bar, hex. null means use the disclaimer background. |
progress_ |
string. Progress text colour, hex. |
progress_ |
integer. Bar corner radius, in pixels. |
progress_ |
boolean. Whether to show the percentage next to the bar. |
terms. |
boolean. Whether the customer must tick a terms checkbox. |
terms. |
string, translated. Text beside the checkbox. May contain batch placeholders and simple HTML. |
terms. |
boolean. Whether the button stays disabled until the box is ticked. |
terms. |
boolean. Whether acceptance is added to the cart line as a property. |
terms. |
string. Name of that line property. |
cart. |
enum. mixed: preorder and in-stock items can share a cart. preorder_: they can’t. |
cart. |
string, translated. Message for a mixed cart when allowed_ is preorder_. |
order_ |
integer. Fewest units per order line. null for no minimum. |
order_ |
integer. Most units per order line. null for no maximum. |
countdown
Section titled “countdown”json. The countdown timer.
| Key | Description |
|---|---|
show_ |
enum. disabled, before_ (counts to the start), during_ (counts to the end) or both. |
date_ |
enum. schedule (the offer’s dates) or custom (the timer’s own dates). |
starts_ |
datetime. Custom start, ISO 8601 in UTC. |
ends_ |
datetime. Custom end, ISO 8601 in UTC. |
starts_ |
string, translated. Heading before launch, for example “Preorders open in”. |
ends_ |
string, translated. Heading during the preorder, for example “Preorders close in”. |
labels. |
string, translated. Label for days. |
labels. |
string, translated. Label for hours. |
labels. |
string, translated. Label for minutes. |
labels. |
string, translated. Label for seconds. |
text_ |
string. Timer text colour, hex. |
background_ |
string. Timer background colour, hex. |
border_ |
integer. Timer corner radius, in pixels. |
units |
array. Units to show, from days, hours, minutes, seconds. |
current. |
enum. The timer when published: before_, during_ or hidden. |
current. |
datetime. The moment the visible timer counts to, ISO 8601 in UTC. |
current. |
string. The heading for the visible phase. |
current. |
datetime. Start date the timer uses, from the schedule or custom dates. |
current. |
datetime. End date the timer uses, from the schedule or custom dates. |
markets
Section titled “markets”json. The Shopify Markets the offer applies in.
| Key | Description |
|---|---|
scope |
enum. all markets, or selected markets only. |
shopify_ |
array. Shopify Market GIDs, when scope is selected. |
advanced
Section titled “advanced”json. How the preorder reaches checkout, and the cart line properties STOQ adds.
| Key | Description |
|---|---|
checkout_ |
enum. selling_: the preorder is a Shopify selling plan on the line. line_: a plain line with STOQ properties, no selling plan. |
cart_ |
boolean. Whether STOQ adds the payment details to the cart line. |
cart_ |
boolean. Whether STOQ adds the shipping text to the cart line. |
cart_ |
string, translated. Extra text STOQ adds to every preorder line. null for none. |
integrations
Section titled “integrations”json. B2B.
| Key | Description |
|---|---|
b2b. |
boolean. Whether B2B customers can preorder. |
batches
Section titled “batches”json. Batches (waves): stock released in turn, each with its own ship date.
| Key | Description |
|---|---|
release_ |
enum. sequential: one batch on sale at a time. all_: batches are off. |
status_ |
string. Word for a batch that has passed, for example “Sold out”. |
status_ |
string. Word for the batch on sale now. |
status_ |
string. Word for a batch still to come. |
widget. |
enum. Layout: roadmap, stacked, compact or segmented. |
widget. |
enum. counts (units sold of the limit) or percent. |
widget. |
boolean. Whether to list the other batches’ ship dates. |
widget. |
boolean. Whether to show batch names. |
items[]. |
integer. Order of the batch, from 1. |
items[]. |
integer. Units in the batch. null when batches have no limits. |
items[]. |
string. The batch’s ship date text. |
items[]. |
string. The batch’s name, for example “Batch 2”. |
translations
Section titled “translations”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. |
Not included
Section titled “Not included”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.
Thanks for letting us know.
Still stuck? Ask Quinn or chat with support