logo

Front-end metafield reference

Full reference for the metafields applied by Submarine to various Shopify objects, for access in Liquid templates and the Shopify Storefront API.

Overview

As described in the front end integration overview, Submarine augments products and variants that are part of presale or crowdfunding campaigns with metafields that allow front-end developers to display campaign information to customers via Liquid or the Storefront API.
A single metafields is attached per campaign type attached in the submarine namespace โ€” for example, product.metafields.submarine.presales contains all product-level information relating to presale campaigns, while product.metafields.submarine.crowdfunding contains all product-level information relating to crowdfunding campaigns.

Product metafields

Presales

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.
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.
fulfill_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.
fulfilled_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.

Variant metafields

Presales

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 } }