STOQ preorder metafields documentation

Overview

This guide shows you how to access and use STOQ's preorder data directly in your Shopify theme using metafields. Perfect for developers who want to build completely custom preorder experiences, display shipping dates in unique ways, show preorder availability counts, or integrate preorder information into their existing product displays without relying on STOQ's default widgets. This article provides a high-level overview of STOQ's preorder metafields. For complete documentation, detailed field descriptions, and advanced examples, visit https://docs.stoqapp.com/frontend/docs/preorder-metafields/

All STOQ metafields use the namespace restockrocket_production. We store preorder data at three levels: shop-wide settings, variant-specific data, and market-specific information for international stores.

Shop Level Metafields

Selling Plans Metafield

Configuration:

• Key: selling_plans
• Type: json
• Namespace: restockrocket_production
• Owner: Shop

Purpose:
This is your source of truth for all preorder configurations in your store. It contains everything about each preorder offer: button text and styling, shipping dates, pricing details, inventory limits, and display preferences. Access this metafield to build custom preorder badges, show delivery timelines, or display offer details anywhere in your theme.

Accessing in Liquid:

{% assign selling_plans = shop.metafields.restockrocket_production.selling_plans.value %}

Key Fields in Selling Plan

{
  "shopify_selling_plan_group_id": "string",
  "shopify_selling_plan_id": "string",
  "enabled": boolean,
  "variant_ids": ["string"],
  "name": "string",
  "preorder_button_text": "string",
  "preorder_button_description": "string",
  "preorder_button_description_background_color": "string",
  "preorder_button_description_text_color": "string",
  "preorder_button_description_border_radius": "number",
  "preorder_badge_enabled": boolean,
  "preorder_badge_text": "string",
  "preorder_badge_text_color": "string",
  "preorder_badge_background_color": "string",
  "delivery_exact_time": "string",
      "shipping_text": "string",
  "payment_type": "string",
  "billing_checkout_charge_type": "string",
  "pricing_type": "string",
  "translations": { /* multilingual support */ }
}

Example: Display Preorder Badge

{% assign current_variant_id = product.selected_or_first_available_variant.id %}
{% assign selling_plans = shop.metafields.restockrocket_production.selling_plans.value %}

{% for plan in selling_plans %}
  {% if plan.enabled %}
    {% if plan.variant_ids contains current_variant_id %}
      <div class="preorder-badge"
           style="background-color: {{ plan.preorder_badge_background_color }};">
        <span style="color: {{ plan.preorder_badge_text_color }};">
          {{ plan.preorder_badge_text }}
        </span>
      </div>

      <div class="preorder-description"
           style="background-color: {{ plan.preorder_button_description_background_color }};
                  color: {{ plan.preorder_button_description_text_color }};">
        {{ plan.preorder_button_description }}
          </div>
    {% endif %}
  {% endif %}
{% endfor %}

Example: Show Shipping Date

{% assign current_variant_id = product.selected_or_first_available_variant.id %}
{% assign selling_plans = shop.metafields.restockrocket_production.selling_plans.value %}

{% for plan in selling_plans %}
  {% if plan.enabled and plan.variant_ids contains current_variant_id %}
    {% if plan.delivery_exact_time %}
      {% assign delivery_date = plan.delivery_exact_time | date: '%Y-%m-%d' | date: '%s' %}
      {% assign today_date = 'now' | date: '%Y-%m-%d' | date: '%s' %}
      {% assign seconds_diff = delivery_date | minus: today_date %}
      {% assign days_until_delivery = seconds_diff | divided_by: 86400 %}

      <div class="delivery-info">
        <h4>Delivery Information</h4>

        {% if days_until_delivery > 0 %}
          <p class="estimated-delivery">
            Estimated delivery: {{ plan.delivery_exact_time | date: '%B %d, %Y' }}
            <span class="days-left">({{ days_until_delivery }} days)</span>
          </p>
        {% else %}
          <p class="delivery-soon">Delivery date approaching</p>
        {% endif %}
      </div>
    {% endif %}
  {% endif %}
{% endfor %}

Product Variant Level Metafields

1. Selling Plan IDs

Configuration:

• Key: selling_plan_ids
• Type: json
• Namespace: restockrocket_production
• Owner: Product Variant

Purpose:
A quick way to check if a variant has any preorder offers without loading all the shop data. Perfect for showing preorder badges on collection pages or checking availability status before rendering custom UI elements.

Accessing in Liquid:

{% assign selling_plan_ids = product_variant.metafields.restockrocket_production.selling_plan_ids.value | json %}

{% if plan_ids.size > 0 %}
  <span class="preorder-available-badge">Preorder Available</span>
{% endif %}

2. Preorder Count

Configuration:

• Key: preorder_count
• Type: number_integer
• Namespace: restockrocket_production
• Owner: Product Variant

Purpose:
The live count of how many preorders have been placed for this variant. Automatically updated in real-time as customers place orders. Use this to show social proof ("43 people have preordered!"), calculate remaining availability, or create urgency messaging.

Accessing in Liquid:

{% assign preorder_count = product_variant.metafields.restockrocket_production.preorder_count %}

3. Preorder Max Count

Configuration:

• Key: preorder_max_count
• Type: number_integer
• Namespace: restockrocket_production
• Owner: Product Variant

Purpose:
The maximum number of preorders you're willing to accept for this variant. Combine this with the preorder count to show "X spots remaining" messaging, create urgency with low-stock warnings, or determine when to switch back to regular "Notify Me" buttons.

Accessing in Liquid:

{% assign preorder_max_count = product_variant.metafields.restockrocket_production.preorder_max_count %}

Example: Show Remaining Preorder Spots

{% assign variant = product.selected_or_first_available_variant %}
{% assign preorder_count = variant.metafields.restockrocket_production.preorder_count.value | default: 0 %}
{% assign preorder_max = variant.metafields.restockrocket_production.preorder_max_count.value %}

{% if preorder_max %}
  {% assign spots_remaining = preorder_max | minus: preorder_count %}

  {% if spots_remaining > 0 %}
    <div class="preorder-availability">
      <span class="spots-left">{{ spots_remaining }} spots remaining</span>
      {% if spots_remaining < 5 %}
        <span class="low-stock-warning">⚠️ Almost sold out!</span>
      {% endif %}
    </div>
  {% else %}
    <div class="preorder-full">
      ❌ Preorder limit reached
    </div>
  {% endif %}
{% endif %}

4. Shipping Text (Variant-Specific)

Configuration:

• Key: shipping_text
• Type: single_line_text_field
• Namespace: restockrocket_production
• Owner: Product Variant

Purpose:

• Stores a per-variant override of the offer's shipping/delivery text, as a plain string.
• Only populated when a per-variant override has been entered (see the note above); otherwise read the offer-level text from the shop-level selling_plans metafield.
• Per-market overrides live in a separate market_shipping_text metafield (json, keyed by Shopify market id) — not in this field.

The variant-level shipping_text metafield is only written when a merchant sets a per-variant shipping-text override for that variant in the offer's Variants tab — and it's only used at runtime when the offer's "Apply shipping text to all products" setting is off (shipping_applies_to_all_products = false).

For the typical store — one shipping message for the whole offer (shipping_applies_to_all_products = true, the default) — STOQ stores the shipping text once on the offer, not on each variant, so this variant metafield will not exist and the Liquid below returns nothing.

To read an offer's shipping text reliably, use the shop-level selling_plans metafield — see Show preorder shipping text on the cart page.

Accessing in Liquid:

{% comment %} Present only if a per-variant override was set on this variant. {% endcomment %}
{% assign variant_shipping = product_variant.metafields.restockrocket_production.shipping_text.value %}

{% if shipping_text %}
  <p class="shipping-info">{{ shipping_text }}</p>
{% endif %}

Market Level Metafields

For international stores that need different preorder limits or shipping timelines per region. If you're selling globally and have different fulfillment capabilities in different markets (like shipping from the US takes 2 weeks but from EU takes 4 weeks), these metafields let you manage that complexity.

1. Market Preorder Count

Configuration:

• Key: market_preorder_count
• Type: json
• Namespace: restockrocket_production
• Owner: Product Variant

Purpose:
Separate preorder counters for each of your markets. This lets you set different inventory limits per region and show region-specific availability. For example, you might accept 100 preorders in the US but only 50 in the EU based on your supply chain capacity.

Accessing in Liquid:

{% assign market_preorder_count = product_variant.metafields.restockrocket_production.market_preorder_count.value | json %}{% assign current_market_id = localization.market.id | json %}

{% if market_counts[current_market_id] %}
  <p>Preorders in your region: {{ market_counts[current_market_id] }}</p>
{% endif %}

2. Market Estimated Shipping

Configuration:

• Key: market_estimated_shipping
• Type: json
• Namespace: restockrocket_production
• Owner: Product Variant

Purpose:
Different shipping dates for each market. Show accurate delivery expectations based on where your customer is located. Essential for building trust with international customers who need to know when their preorder will actually arrive.

Accessing in Liquid:

{% assign market_preorder_max_count = product_variant.metafields.restockrocket_production.market_preorder_max_count.value | json %}


{% if shipping_dates[current_market_id] %}
  <p class="shipping-estimate">
    Estimated shipping: {{ shipping_dates[current_market_id] | date: "%B %d, %Y" }}
  </p>
{% endif %}

Practical Integration Examples

Complete Preorder Info Display

{% assign variant = product.selected_or_first_available_variant %}
{% assign variant_id = variant.id %}
{% assign selling_plans = shop.metafields.restockrocket_production.selling_plans.value %}

{% for plan in selling_plans %}
  {% if plan.enabled and plan.variant_ids contains variant_id %}

    {%comment%} Preorder Badge {%endcomment%}
    {% if plan.preorder_badge_enabled %}
      <div class="preorder-badge"
           style="background: {{ plan.preorder_badge_background_color }};
                  color: {{ plan.preorder_badge_text_color }};">
        {{ plan.preorder_badge_text }}
      </div>
    {% endif %}

    {%comment%} Preorder Button {%endcomment%}
    <button class="preorder-button">
      {{ plan.preorder_button_text }}
    </button>

    {%comment%} Description with Quantity Limit {%endcomment%}
    <div class="preorder-description"
         style="background: {{ plan.preorder_button_description_background_color }};
                color: {{ plan.preorder_button_description_text_color }};">
      {{ plan.preorder_button_description }}

      {% if plan.preorder_button_description_show_quantity_limit %}
        {% assign count = variant.metafields.restockrocket_production.preorder_count.value | default: 0 %}
        {% assign max = variant.metafields.restockrocket_production.preorder_max_count.value %}

        {% if max %}
          {% assign remaining = max | minus: count %}
          <span class="quantity-limit">
            {{ remaining }}{{ plan.preorder_button_description_quantity_limit_suffix }}
          </span>
        {% endif %}
      {% endif %}

      {% if plan.preorder_button_description_show_shipping and plan.delivery_exact_time %}
        <span class="shipping-date">
          {{ plan.preorder_button_description_shipping_text_prefix }}
          {{ plan.delivery_exact_time | date: "%B %d, %Y" }}
        </span>
      {% endif %}
    </div>

  {% endif %}
{% endfor %}

Accessing via GraphQL

Query Shop Selling Plans

{
  shop {
    metafield(namespace: "restockrocket_production", key: "selling_plans") {
      id
      namespace
      key
      value
      type
    }
  }
}

Query Variant Metafields

{
  productVariant(id: "gid://shopify/ProductVariant/YOUR_VARIANT_ID") {
    metafields(
      namespace: "restockrocket_production",
      keys: ["preorder_count", "preorder_max_count", "selling_plan_ids"]
    ) {
      edges {
        node {
          id
          key
          value
          type
        }
      }
    }
  }
}

Important Notes

1. Namespace: All metafields use restockrocket_production
2. Auto-Updates: Metafields are automatically updated when you change settings in STOQ dashboard
3. Enabled Plans: Filter by enabled: true to show only active selling plans
4. Market IDs: Match Shopify's market system IDs

Full Documentation

For complete field structures, GraphQL examples, and advanced use cases: https://docs.stoqapp.com/frontend/docs/preorder-metafields/. If you need any assistance with metafields integration or accessing preorder data in your theme, feel free to contact our 24/7 live support. We're happy to help!

Sub-pages:

• Shop Level Metafields - Complete field list
• Product Variant Level Metafields - Variant-specific data
• Market Level Metafields - International stores

Updated on: 21/07/2026