Metafield Reference

Full reference for the metafields applied by Submarine to various Shopify objects, for access in Liquid templates and the Shopify Storefront API to support advanced subscription, presale and crowdfunding capabilities.

Overview

As described in the front end integration overview, Submarine augments products and variants with metadata that allow front-end developers to display information to customers and drive behaviour via Liquid or the Storefront API.

A single metafield is attached per experience type in the submarine namespace — for example, product.metafields.submarine.presales contains all product-level information relating to presale campaigns, and product.metafields.submarine.crowdfunding contains all product-level information relating to crowdfunding campaigns.

💡

Be sure to read the Note on Submarine metadata approaches to understand why there is a substantial difference between metadata approaches between presales and crowdfunding and subscriptions.

Presale metafields

Presales product metafields

Information about all presale campaigns a product has been part of, including historical campaigns, is available in a single product.metafields.submarine.presales metafield as a JSON object array.

Each campaign object has the following properties:

Property key	Property type	Example value	Notes
`cancelled_at`	String	`2023-03-07T06:02:35Z`	If the campaign has been cancelled, the time it was cancelled in ISO8601 format.
`completed_at`	String	`2023-03-07T06:02:35Z`	If the campaign has been completed, the time it was completed in ISO8601 format.
`deposit_type`	String	`percentage`	The type of deposit policy for the campaign. Currently, `percentage` is the only supported value.
`deposit_value`	String	`30`	The value of the deposit. For `percentage` deposit policies, this will be a decimal value between `0` and `100`.
`deleted_at`	String	`2023-02-18T14:00:00Z`	If the campaign has been deleted, the time it was deleted in ISO8601 format.
`end_at`	String	`2023-02-18T14:00:00Z`	The time the campaign is due to end in ISO8601 format.
`ended_at`	String	`2023-03-07T06:02:35Z`	If the campaign has ended, the time it ended in ISO8601 format.
`fulfil_at`	String	`2023-06-11T12:30:00Z`	The time the campaign is due to be fulfilled in ISO8601 format. Note that not all presale campaigns require a scheduled fulfilment date, so this value may be `null`.
`fulfilling_at`	String	`2023-03-07T06:02:35Z`	If the campaign has been fulfilled, the time it was fulfilled in ISO8601 format.
`id`	String	`4f2b1c79-49c5-4ad2-af14-5034623ce62e`	The unique Submarine ID for the presale campaign.
`launch_at`	String	`2023-02-06T16:31:18Z`	The time the campaign is scheduled to launch in ISO8601 format.
`launched_at`	String	`2023-03-07T06:02:35Z`	If the campaign has launched, the time it was launched in ISO8601 format.
`limit`	Number	`1500`	The total limit of units to be sold for this campaign across all products and variants that are part of the campaign.
`reserved`	Number	`467`	The total number of units of this product that have been sold for the campaign. If the campaign contains only a single product, this value will be the same as `total_campaign_reserved`.
`selling_plan_gid`	String	`gid://shopify/SellingPlan/4464279842`	The global ID of the Shopify selling plan related to this presale campaign.
`selling_plan_group_gid`	String	`gid://shopify/SellingPlanGroup/746324258`	The global ID of the Shopify selling plan grouped related to this presale campaign.
`status`	String	`pending`	The current status of the presale campaign. One of `pending`, `allocated`, `paid`, `completed` or `cancelled`.
`total_campaign_reserved`	Number	`435`	The total number of units that have been sold for the campaign across all products. If the campaign contains only a single product, this value will be the same as `reserved`.

Here’s an example JSON value for a product’s presale metafield for a product that has been part of two presale campaigns, one active and one completed:

json
[
  {
    "cancelled_at": null,
    "completed_at": null,
    "deleted_at": null,
    "deposit_type": "percentage",
    "deposit_value": "50.0",
    "end_at": "2023-03-31T00:52:00.000Z",
    "ended_at": "2023-03-03T03:20:36.000Z",
    "fulfil_at": "2023-04-06T14:00:00.000Z",
    "fulfilling_at": null,
    "id": "0184c0df-775b-1d55-1bd7-a395e0f5e0b2",
    "launch_at": "2022-12-29T00:52:24.000Z",
    "launched_at": "2022-12-29T01:03:01.000Z",
    "limit": 100,
    "reserved": 25,
    "selling_plan_gid": "gid://shopify/SellingPlan/4464279842",
    "selling_plan_group_gid": "gid://shopify/SellingPlanGroup/746324258",
    "status": "ended",
    "total_campaign_reserved": 100
  },
  {
    "cancelled_at": null,
    "completed_at": null,
    "deleted_at": null,
    "deposit_type": "percentage",
    "deposit_value": "0.0",
    "end_at": "2023-07-31T02:00:00.000Z",
    "ended_at": null,
    "fulfil_at": "2023-08-21T14:00:00.000Z",
    "fulfilling_at": null,
    "id": "0186b467-958b-3bed-9923-263684148a86",
    "launch_at": "2023-03-06T01:00:00.000Z",
    "launched_at": "2023-03-06T01:03:00.000Z",
    "limit": 100,
    "reserved": 9,
    "selling_plan_gid": "gid://shopify/SellingPlan/4517003554",
    "selling_plan_group_gid": "gid://shopify/SellingPlanGroup/778436898",
    "status": "launched",
    "total_campaign_reserved": 9
  }
]

The first, ended campaign was a 50% deposit up front campaign that spanned multiple products - 25 units of this product were sold of the 100 unit total.

The second, active (launched) campaign is a 0% up front campaign that’s sold 9 units of the product.

Presales variant metafields

Variants that have been part of a presale campaign have a variant.metafields.submarine.presales metafield attached that exposes information relevant to that variant within each campaign.

While this metafield is also a JSON value, unlike the product metafield it’s a JSON object that maps Submarine campaign IDs to the variant-specific properties for that campaign.

The properties are:

Property key	Property type	Example value	Notes
`reserved`	Number	`22`	The total number of units of this variant that have been sold for a campaign.

Here’s an example JSON value for a variant’s presale metafield, assuming it was part of both of the campaigns defined in the product example above:

json
{
  "4f2b1c79-49c5-4ad2-af14-5034623ce62e": {
    "reserved": 106
  },
  "44bf0a37-f21c-4257-93f0-e2e3cd58d631": {
    "reserved": 76
  }
}

Crowdfunding metafields

Crowdfunding product metafields

Information about all crowdfund campaigns a product has been part of, including historical campaigns, is available in a single product.metafields.submarine.crowdfunds metafield as a JSON object array.

Each campaign object has the following properties:

Property key	Property type	Example value	Notes
`campaign_end_total_units`	Number	`25`	The total number of units sold at the end of the campaign.
`campaign_end_total_value_cents`	Number	`25`	The total value sold at the end of the campaign in cents.
`campaign_running_total_units`	Number	`25`	The total number of units sold at the current time for the campaign.
`campaign_running_total_value_cents`	Number	`25`	The running value sold at the end of the campaign in cents.
`cancelled_at`	String	`2023-03-07T06:02:35Z`	If the campaign has been cancelled, the time it was cancelled in ISO8601 format.
ㅤ	ㅤ	ㅤ	ㅤ
`completed_at`	String	`2023-03-07T06:02:35Z`	If the campaign has been completed, the time it was completed in ISO8601 format.
`deleted_at`	String	`2023-02-18T14:00:00Z`	If the campaign has been deleted, the time it was deleted in ISO8601 format.
`end_at`	String	`2023-02-18T14:00:00Z`	The time the campaign is due to end in ISO8601 format.
`ended_at`	String	`2023-03-07T06:02:35Z`	If the campaign has ended, the time it ended in ISO8601 format.
`fulfil_at`	String	`2023-06-11T12:30:00Z`	The time the campaign is due to be fulfilled in ISO8601 format. Note that not all campaigns require a scheduled fulfilment date, so this value may be `null`.
`fulfilled_at`	String	`2023-03-07T06:02:35Z`	If the campaign has been fulfilled, the time it was fulfilled in ISO8601 format.
`goal_progress`	Number	`25`	The total current progress on the campaign.
`goal_status`	String	`failed`	The end status of the campaign once the end date has passed. One of, `succeeded` or `failed`
`goal_total_units`	Number	`30`	The total amount set for the campaign. For both units and value this will be a decimal value between `0` and `100`.
`goal_total_value_cents`	Number	`30`	The total amount set for the campaign. For both units and value this will be a decimal value between `0` and `100`.
`goal_type`	String	`total_units`	The selected goal type for the campaign. One of `total_units` or `total_value`.
`id`	String	`4f2b1c79-49c5-4ad2-af14-5034623ce62e`	The unique Submarine ID for the crowdfund campaign.
`launch_at`	String	`2023-02-06T16:31:18Z`	The time the campaign is scheduled to launch in ISO8601 format.
`launched_at`	String	`2023-03-07T06:02:35Z`	If the campaign has launched, the time it was launched in ISO8601 format.
`reserved`	Number	`467`	The total number of units of this product that have been sold for the campaign. If the campaign contains only a single product, this value will be the same as `total_campaign_reserved`.
`selling_plan_gid`	String	`gid://shopify/SellingPlan/4464279842`	The global ID of the Shopify selling plan related to this crowdfund campaign.
`selling_plan_group_gid`	String	`gid://shopify/SellingPlanGroup/746324258`	The global ID of the Shopify selling plan grouped related to this crowdfund campaign.
`status`	String	`pending`	The current status of the crowdfund campaign. One of `pending`, `allocated`, `paid`, `completed` or `cancelled`.
`total_campaign_reserved`	Number	`435`	The total number of units that have been sold for the campaign across all products. If the campaign contains only a single product, this value will be the same as `reserved`.

Here’s an example JSON value for a product’s crowdfund metafield for a product that has been part of an Ended: Successful campaign that has not yet allocated inventory (fulfilments are still on Hold):

json
[
  {
    "campaign_end_total_units": 11,
    "campaign_end_total_value_cents": 77000,
    "campaign_running_total_units": 11,
    "campaign_running_total_value_cents": 77000,
    "cancelled_at": null,
    "completed_at": "2023-05-18T20:21:30.000Z",
    "deleted_at": null,
    "deposit_type": "percentage",
    "deposit_value": "0.0",
    "end_at": "2023-07-14T20:30:04.000Z",
    "ended_at": "2023-05-14T20:23:26.000Z",
    "fulfil_at": null,
    "fulfilling_at": null,
    "goal_progress": 11,
    "goal_status": "succeeded",
    "goal_total_units": 7,
    "goal_total_value_cents": null,
    "goal_type": "total_units",
    "id": "01881bec-d0e4-4519-f82f-b55f21934ac6",
    "launch_at": "2023-06-14T20:30:04.000Z",
    "launched_at": "2023-05-14T20:21:30.000Z",
    "limit": null,
    "reserved": 11,
    "selling_plan_gid": "gid://shopify/SellingPlan/4471259422",
    "selling_plan_group_gid": "gid://shopify/SellingPlanGroup/1030291742",
    "status": "ended",
    "total_campaign_reserved": 11
  }
]

Crowdfunding variant metafields

Variants that have been part of a crowdfunding campaign have a variant.metafields.submarine.crowdfund metafield attached that exposes information relevant to that variant within each campaign.

While this metafield is also a JSON value, unlike the product metafield it’s a JSON object that maps Submarine campaign IDs to the variant-specific properties for that campaign.

The properties are:

Property key	Property type	Example value	Notes
`reserved`	Number	`22`	The total number of units of this variant that have been sold for a campaign.

Here’s an example JSON value for a variant’s crowdfund metafield, assuming it was part of both of the campaigns defined in the product example above:

json
[
  {
    "01884ca2-ed92-faab-e7b9-c66cdc409d78": {
      "reserved": 20
    }
  }
]

Subscription metafields

Subscription variant metafields

Variants that are available for subscription via one or more subscription plan (or that have been available as such in the past) have a variant.metafields.submarine.subscription_plans metafield attached.

This metafield is defined as a Metaobject list that references zero to many Subscription Plan metaobjects.

Here’s an example value for a variant’s subscription plans metafield:

json
[
  "gid://shopify/Metaobject/51324780862"
]

Both Liquid templates and the Shopify Storefront API support expanding this list of object references to the underlying object definitions — see the Subscription Plan metaobject definition for details on the data exposed there.