Available Variables
Built-in inputs for getting context on the user
Objects
customer
customer
Customer variables represent a user's Shopify account information. These variables are refreshed when a customer signs in/out.
Property | Type | Example | Availability |
---|---|---|---|
customer.id | String | 6669141901500 | When user is logged in |
customer.firstName | String | John | When user is logged in |
customer.metafields | Object | { "my-namespace": { "my-key": "my-value" } } | If Available |
collection
collection
Collection variables are distinct to the collection that's currently in view on the product listing page (PLP). These variables are refreshed when a user visits a new PLP.
Property | Type | Example | Availability |
---|---|---|---|
collection.id | String | 123457 | Always |
collection.title | String | Vintage Shirts | Always |
collection.handle | String | vintage-shirts | Always |
collection.description | String | Limited availability vintage shirts | Always |
collection.image | String | [ "<https://example.com/image.jpg>" ] | Always |
collection.metafields | Array | { "my-namespace": { "my-key": "my-value" } } | If Available |
cart
cart
Cart variables allow you to access the contents of a customer's current cart. These variables are refreshed in real-time.
Top-level cart
Properties
cart
PropertiesProperty | Type | Example | Availability |
---|---|---|---|
cart.id | String | aBCd1234xyZ | Only on Cart API. Available on every screen once user has created a cart |
cart.items | Array<Items> | [{"quantity", "productId", "variantId", "sellingPlanId", "attributes"}] | If items are in the cart |
cart.appliedDiscounts | Array | ["TEST10","GET20"] | If discounts are applied to the cart |
cart.subtotal | Float | 20.45 (Sum of cart items less any applied discounts) | Always |
cart.currency | String | USD | Always |
cart.attributes | Array<[Objects]> | [ { "key": "value" }, { "key1": "value1" },] | If attributes are applied to the cart |
cart.notes | String | This is a cart note | If notes are applied to cart. Can only have 1 and will be overwritten |
cart.items
Properties
cart.items
PropertiesProperty | Type | Example | Availability |
---|---|---|---|
cart.items.quantity | Integer | 1 | If items are in the cart |
cart.items.productId | String | 7629735690428 | If items are in the cart |
cart.items.variantId | String | 43577520193749 | If items are in the cart |
cart.items.sellingPlanId | String | 1039518903 | If selling plans are in cart |
cart.items.attributes | Array | [ { "key": "value"} ] | If attributes are in the cart |
device
device
Device variables are distinct to the user's device. If a user gets a new device, or deletes & reinstalls the app, they will receive a new device_id
.
Property | Type | Example | Availability |
---|---|---|---|
device.id | String | D40B48A7-0889-4E76-8946-5EA5EBDD29FF | Always |
device.locale | String | en_US | Always |
device.windowHeight | Float | 600 | Always |
product
product
Product variables are distinct to the product that's currently in view on the product detail page (PDP). These variables are refreshed when a user visits a new PDP.
Top-level product
Properties
product
PropertiesProperty | Type | Example | Availability |
---|---|---|---|
product.id | String | 7629735690428 | Always |
product.availableForSale | Boolean | true | false | Always |
product.compareAtPrice | Float | 20.99 | If used |
product.description | String | Vintage cotton shirt | If used |
product.handle | String | vintage-shirt | Always |
product.images | Array | [ "<https://example.com/image.jpg>" ] | Always |
product.options | Array<ProductOption> | [{ "name": "Color", "values": ["Black", "Blue"]}] | Always |
product.price | Float | 15.99 | Always |
product.tags | Array | ["Vintage", "Cotton", "New"] | If used |
product.title | String | Vintage Shirt | Always |
product.url | String | https://www.tapcartcustomblocks.com/products/vintage-shirt | Always |
product.vendor | String | Tapcart | If used |
product.selectedVariant | String | 6875079049404 | Always |
product.variants | Array<ProductVariant> | "variants": [{ "selectedOptions","id","price", "title","isAvailable,"compareAtPrice","image", "sku"}] | Always |
product.metafields | Object | { "my-namespace": { "my-key": "my-value" } } | If used |
product.options
Properties
product.options
PropertiesProperty | Type | Example | Availability |
---|---|---|---|
product.options.name | String | Color | Always |
product.options.values | Array | ['Black', 'Blue'] | Always |
product.variants
Properties
product.variants
PropertiesScroll to the right of the table to view more columns.
Property | Type | Example | Availability |
---|---|---|---|
product.variants.id | String | 43577520193749 | Always |
product.variants.title | String | Blue | Always |
product.variants.image | String | https://example.com/image.jpg | Always |
product.variants.isAvailable | Boolean | true | false | Always |
product.variants.price | Float | 10.99 | Always |
product.variants.compareAtPrice | Float | 20.99 | If used |
product.variants.selectedOptions | Array<SelectedOption> | "selectedOptions": [{"name": "Color", "value": "Black"}] | Always |
product.variants.sku | String | 12938412 | Always |
product.variants.SellingPlanAllocations | Array<SellingPlanAllocations> | "sellingPlanAllocations": [{"sellingPlan": { "id": "549355658","name": "Delivery every 1 week", "description": null,"recurringDeliveries": true, "SellingPlanPriceAdjustments","sellingPlanOptions", "sellingPlanAllocationPriceAdjustment"}}] | If used |
product.variants.metafields | Object | { "my-namespace": { "my-key": "my-value" } } | If used |
selectedOptions
Properties
selectedOptions
PropertiesProperty | Type | Example | Availability |
---|---|---|---|
product.selectedOption.name | String | Color | Always |
product.selectedOption.value | String | Black | Always |
SellingPlanAllocations
Properties
SellingPlanAllocations
PropertiesClick here to learn more about Selling Plans, Shopify's construct of how to sell recurring product subscriptions. Scroll to the right of the table to view more columns.
Property | Type | Example | Availability |
---|---|---|---|
product.variants.SellingPlanAllocations.SellingPlan.id | String | 549355658 | If used |
product.variants.SellingPlanAllocations.SellingPlan.name | String | Delivery every 1 week | If used |
product.variants.SellingPlanAllocations.SellingPlan.description | String | Subscribe to these socks and get them monthly | If used |
product.variants.SellingPlanAllocations.SellingPlan.recurringDeliveries | Boolean | True | False | If used |
product.variants.SellingPlanAllocations.SellingPlan.SellingPlanPriceAdjustments | Array<SellingPlanPriceAdjustments> | "SellingPlanPriceAdjustments": [{ "orderCount": null, "SellingPlanPriceAdjustmentValue" }] | If used |
product.variants.SellingPlanAllocations.SellingPlan.SellingPlanOptions | Array<SellingPlanOptions> | "SellingPlanOptions": [{ "value": "1 Week(s)", "name": "1 Week(s), 2 Week(s), 3 Week(s), 4 Week(s), 5 Week(s), 6 Week(s)"}] | If used |
product.variants.SellingPlanAllocations.SellingPlan.SellingPlanAllocationPriceAdjustments | Array<SelectedPlanAllocationPriceAdjustments> | "SellingPlanAllocationPriceAdjustments": [{"price": 32.3, "unitPrice": null, "compareAtPrice": 34, "perDeliveryPrice": 32.3}] | If used |
SellingPlanPriceAdjustments
Properties
SellingPlanPriceAdjustments
PropertiesProperty | Type | Example | Availability |
---|---|---|---|
product.variants.SellingPlanAllocations.SellingPlan.SellingPlanPriceAdjustments.orderCount | Integer | 3 | If used |
product.variants.SellingPlanAllocations.SellingPlan.SellingPlanPriceAdjustments.SellingPlanPriceAdjustmentValue | Array<SellingPlanPriceAdjustmentValue> | "SellingPlanPriceAdjustmentValue": {"amount": 5, "currencyCode": "USD", "type": "FIXEDAMOUNT"} | If used |
SellingPlanPriceAdjustmentValue
Properties
SellingPlanPriceAdjustmentValue
PropertiesScroll to the right of the table to view more columns.
Property | Type | Example | Availability |
---|---|---|---|
product.variants.SellingPlanAllocations.SellingPlan.SellingPlanPriceAdjustments.SellingPlanPriceAdjustmentValue.type | String | FIXEDAMOUNT | PERCENTAGE | If used |
product.variants.SellingPlanAllocations.SellingPlan.SellingPlanPriceAdjustments.SellingPlanPriceAdjustmentValue.currencyCode | String | USD | If used |
product.variants.SellingPlanAllocations.SellingPlan.SellingPlanPriceAdjustments.SellingPlanPriceAdjustmentValue.amount | Float | 5 | If type is FIXEDAMOUNT |
product.variants.SellingPlanAllocations.SellingPlan.SellingPlanPriceAdjustments.SellingPlanPriceAdjustmentValue.percentageAmount | Float | 5 | If type is PERCENTAGE |
SellingPlanOptions
Properties
SellingPlanOptions
PropertiesScroll to the right of the table to view more columns.
Property | Type | Example | Availability |
---|---|---|---|
product.variants.SellingPlanAllocations.SellingPlan.SellingPlanOptions.name | String | 1 Week(s) | If used |
product.variants.SellingPlanAllocations.SellingPlan.SellingPlanOptions.value | String | 1 Week(s), 2 Week(s) | If used |
SellingPlanAllocationPriceAdjustments
Properties
SellingPlanAllocationPriceAdjustments
PropertiesScroll to the right of the table to view more columns.
Property | Type | Example | Availability |
---|---|---|---|
product.variants.SellingPlanAllocations.SellingPlan.SellingPlanAllocationPriceAdjustmentss.price | Float | 32.20 | If used |
product.variants.SellingPlanAllocations.SellingPlan.SellingPlanAllocationPriceAdjustments.unitPrice | Float | 32.20 | If used |
product.variants.SellingPlanAllocations.SellingPlan.SellingPlanAllocationPriceAdjustments.compareAtPrice | Float | 34.00 | If used |
product.variants.SellingPlanAllocations.SellingPlan.SellingPlanAllocationPriceAdjustments.perDeliveryPrice | Float | 32.30 | If used |
sourceCollection
Properties
sourceCollection
PropertiesScroll to the right of the table to view more columns.
Property | Type | Example. | Availability |
---|---|---|---|
product.sourceCollection.id | String | 238472398423 | Available when a PDP is opened from a collection |
product.sourceCollection.title | String | Vintage Shirts | Available when a PDP is opened from a collection |
product.sourceCollection.handle | String | vintage-shirts | Available when a PDP is opened from a collection |
product.sourceCollection.metafields.namespace.key | Object | { "my-namespace": { "my-key": "my-value" } } | If used/ Available when a PDP is opened from a collection |
metafields
Properties
metafields
PropertiesBefore using a metafield variable your block, you'll first need to enable metafields for your Tapcart app, and include any specific metafields that your app should have access to.
When referencing a metafield variable in your block, make sure to specify the specific namespace
& key
you want to retrieve.
Property | Type | Example | Availability |
---|---|---|---|
product.metafields.namespace.key | Object | { "my-namespace": { "my-key": "my-value" } } | If used |
customer.metafields.namespace.key | Object | { "my-namespace": { "my-key": "my-value" } } | If used |
product.variants.metafields.namespace.key | Object | { "my-namespace": { "my-key": "my-value" } } | If used |
shop.metafields.namespace.key | Object | { "my-namespace": { "my-key": "my-value" } } | If Used |
session
session
Property | Type | Example | Availability |
---|---|---|---|
session.id | String | ABCDE-1234-5678-XYZ | Always |
shop
shop
Shop variables represent a Shopify stores 3rd party added information. These variables are refreshed when a 3rd party updates them
Property | Type | Example | Availability |
---|---|---|---|
shop.metafields | Object | { "my-namespace": { "my-key": "my-value" } } | If Available |
theme
theme
These values can be set in Brand Kit in the Merchant Dashboard and control the colors throughout the app. Referencing them in your Custom Block will help align your Block to the rest of the app. Brand Kit help + reference.
Example colors properties:
Property | Type | Example | Availability |
---|---|---|---|
$theme-tokens-colors-coreColors-brandColorPrimary | String | # e21212 | Always |
$theme-tokens-colors-coreColors-dividingLines | String | # FFFFFF | Always |
$theme-tokens-colors-coreColors-shadowsEnabled | Boolean | true | Always |
For full theme colors list, reference Full Payload Example below ⬇
Full Payload Example
{
"theme": {
"tokens": {
"colors": {
"coreColors": {
"brandColorPrimary": "#e21212",
"pageColor": "#FFFFFFFF",
"headerBackground": "#F2F0ED",
"inputBackground": "#FFFFFFFF",
"modalBackground": "#FFFFFFFF",
"tabBar": "#FFFFFF",
"dividingLines": "#E3E3E3FF",
"shadowsEnabled": true,
"primaryIcon": "#121212FF",
"secondaryIcon": "#727272",
"headerIcon": "#1c1b1d"
},
"buttonColors": {
"primaryFill": "#e21212",
"primaryText": "#FFFFFFFF",
"primaryOutlineEnabled": false,
"primaryOutlineColor": "#00000000",
"primaryShadowEnabled": false,
"secondaryFill": "#00000000",
"secondaryText": "#e21212",
"secondaryOutlineEnabled": true,
"secondaryOutlineColor": "#e21212",
"secondaryShadowEnabled": false
},
"textColors": {
"primaryColor": "#121212FF",
"secondaryColor": "#727272",
"pageTitle": "#121212FF",
"legalText": "#727272",
"productTitle": "#727272",
"priceText": "#121212FF",
"strikethroughPriceText": "#727272FF",
"salePriceText": "#D91E18FF"
},
"stateColors": {
"subscriptions": "#008000FF",
"favorites": "#D91E18FF",
"reviews": "#FFAF02FF",
"success": "#008000FF",
"error": "#D91E18FF",
"warning": "#FFAF02FF",
"disabled": "#B1B1B1FF",
"skeleton": "#E3E3E3FF"
}
}
}
},
"customer": {
"id": "779544431",
"firstName": "John",
"metafields": {
"myNamespace1": {
"myKey1": "myValue1"
},
"myNamespace2": {
"myKey2": "myValue2"
}
}
},
"device": {
"id": "25679b7e-2348-44da-94ef-e218f6be4586",
"locale": "en"
},
"cart": {
"id": "e218f6be4586e218f6be4586",
"items": [
{
"quantity": 1,
"productId": "7629735690428",
"variantId": "43577520193749",
"sellingPlanId": "1039518903",
"attributes": [
{
"key": "value"
}
]
}
],
"appliedDiscounts": [
"TEST10"
],
"subtotal": 0,
"currency": "USD"
},
"session": {
"id": "ABCDE-12345-56789-XYZ"
},
"shop": {
"metafields": {
"myNamespace1": {
"myKey1": "myValue1"
},
"myNamespace2": {
"myKey2": "myValue2"
}
}
},
"product": {
"id": "6875079049404",
"description": "<p>Vintage cotton Tapcart shirt</p>",
"options": [
{
"name": "Color",
"values": [
"Black",
"Blue"
]
}
],
"handle": "vintage-shirt",
"tags": [
"Vintage",
"Cotton",
"New"
],
"availableForSale": true,
"title": "Vintage Tapcart Shirt",
"price": 55,
"metafields": {
"myNamespace1": {
"myKey1": "myValue1"
},
"myNamespace2": {
"myKey2": "myValue2"
}
},
"compareAtPrice": 100,
"vendor": "Tapcart",
"images": [
"https://assets-global.website-files.com/616f0a7a027baaf59a43390b/616f0a7a027baab7e743396e_full.svg"
],
"selectedVariant": {
"id": "6875079049404"
},
"sourceCollection": {
"id": "238472398423",
"handle": "vintage-shirts",
"title": "Vintage Shirts",
"metafields": {
"myNamespace1": {
"myKey1": "myValue1"
}
}
},
"variants": [
{
"selectedOptions": [
{
"name": "Color",
"value": "Black"
}
],
"id": "40122114900156",
"price": 55,
"title": "Vintage Tapcart Shirt",
"isAvailable": true,
"compareAtPrice": 100,
"image": "https://assets-global.website-files.com/616f0a7a027baaf59a43390b/616f0a7a027baab7e743396e_full.svg",
"sku": "12938412",
"metafields": {
"myNamespace1": {
"myKey1": "myValue1"
},
"myNamespace2": {
"myKey2": "myValue2"
}
},
"SellingPlanAllocations": [
{
"SellingPlan": {
"id": "549355658",
"name": "Delivery every 1 week",
"description": null,
"recurringDeliveries": true,
"SellingPlanPriceAdjustments": [
{
"orderCount": null,
"SellingPlanPriceAdjustmentValue": {
"amount": 5,
"currencyCode": "USD",
"type": "FIXEDAMOUNT"
}
},
{
"orderCount": 3,
"SellingPlanPriceAdjustmentValue": {
"percentageAmount": 5,
"type": "PERCENTAGE"
}
}
],
"SellingPlanOptions": [
{
"value": "1 Week(s)",
"name": "1 Week(s), 2 Week(s), 3 Week(s), 4 Week(s), 5 Week(s), 6 Week(s)"
}
],
"SellingPlanAllocationPriceAdjustments": [
{
"price": 32.3,
"unitPrice": null,
"compareAtPrice": 34,
"perDeliveryPrice": 32.3
}
]
}
}
]
}
]
}
}
Updated 23 days ago