Available Variables

Built-in inputs for getting context on the user

Objects

customer

Customer variables represent a user's Shopify account information. These variables are refreshed when a customer signs in/out.

PropertyTypeExampleAvailability
customer.idString6669141901500When user is logged in
customer.firstNameStringJohnWhen user is logged in
customer.metafieldsObject{ "my-namespace": { "my-key": "my-value" } }If Available
customer.tagsArray{ "newsletter" }When user is logged in & merchant has custom tags enabled
customer.customerAccessTokenString57de1b5f7c89aeb0fbbead0f4c429f28If feature flag is enabled
customer.customerSessionObject{"customerAccessToken", "customerSessionToken","storefrontSessionToken"}If New Customer Account is enabled in integration & feature flag

customer.customerSession

PropertyTypeExampleAvailability
customer.customerSession.customerAccessTokenObject{ "accessToken", "expiresAt", "idToken", "refreshToken" }f New Customer Account is enabled in integration & feature flag
customer.customerSession.customerSessionTokenObject{ "accessToken", "expiresAt"}f New Customer Account is enabled in integration & feature flag
customer.customerSession.storefrontSessionTokenObject{ "accessToken", "expiresAt"}f New Customer Account is enabled in integration & feature flag

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.

PropertyTypeExampleAvailability
collection.idString123457Always
collection.titleStringVintage ShirtsAlways
collection.handleStringvintage-shirtsAlways
collection.descriptionStringLimited availability vintage shirtsAlways
collection.imageString[ "<https://example.com/image.jpg>" ]Always
collection.metafieldsArray { "my-namespace": { "my-key": "my-value" } }If Available

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

PropertyTypeExampleAvailability
cart.idStringaBCd1234xyZOnly on Cart API. Available on every screen once user has created a cart
cart.itemsArray<Items>[{"quantity", "productId", "variantId", "sellingPlanId", "attributes"}]If items are in the cart
cart.discountsArray ["TEST10","GET20"]If discounts are applied to the cart
cart.subtotalFloat20.45 (Sum of cart items less any applied discounts)Always
cart.currencyStringUSDAlways
cart.attributesArray<[Objects]>[ { "key": "value" }, { "key1": "value1" },]If attributes are applied to the cart
cart.notesStringThis is a cart noteIf notes are applied to cart. Can only have 1 and will be overwritten

cart.items Properties

PropertyTypeExampleAvailability
cart.items.quantityInteger1If items are in the cart
cart.items.productIdString7629735690428If items are in the cart
cart.items.variantIdString43577520193749If items are in the cart
cart.items.sellingPlanIdString1039518903If selling plans are in cart
cart.items.attributesArray[ { "key": "value"} ]If attributes are in the cart
cart.items.discountsArray[ { "type", "title", "code", "amount"} ]If discounts are applied to the item

cart.items.discountsProperties

PropertyTypeExampleAvailability
cart.items.discounts.typeStringfreeShippingAlways
cart.items.discounts.titleStringsave10Always
cart.items.discounts.codeStringSAVE10Always
cart.items.discounts.amountFloat10Always

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.

PropertyTypeExampleAvailability
device.idStringD40B48A7-0889-4E76-8946-5EA5EBDD29FFAlways
device.localeStringen_USAlways
device.windowHeightFloat600Always
device.tapcartVersionString12.16.0Always
device.operatingSystemStringAndroidAlways
device.osVersionString15Always

orderDetails

Only available from the post purchase screen, these details of successful orders include the delivery info, payment method, id and cart information as standard. Optionally including the billing address, email and phone number if they are available

Top-level orderDetails Properties

PropertyTypeExampleAvailability
orderDetails.billingAddressObjectAddressSee sectionIf used
orderDetails.cartObjectCartInfoSee sectionAlways
orderDetails.deliveriesArray<DeliveryInfo >See sectionAlways
orderDetails.emailString[email protected]If used
orderDetails.idString87655489Always
orderDetails.paymentMethodsArray<PaymentMethod >See SectionAlways
orderDetails.phoneString+12378650066If used

addressProperties

PropertyTypeExampleAvailability
orderDetails.address1String34503 9th Avenue SouthIf used
orderDetails.address2StringApartment 4If used
orderDetails.cityStringFederal WayIf used
orderDetails.countryCodeStringUSIf used
orderDetails.firstNameStringBertIf used
orderDetails.LastNameStringTracyIf used
orderDetails.nameStringBert TracyIf used
orderDetails.phoneString+16578875655If used
orderDetails.postalCodeString98003If used
orderDetails.referenceIdString453333234If used
orderDetails.zoneCodeString003If used

orderDetails.cartProperties

PropertyTypeExampleAvailability
orderDetails.linesArray<CartLine >See sectionAlways
orderDetails.priceObjectPriceSee sectionAlways
orderDetails.tokenString444568322Always

cartLineProperties

PropertyTypeExampleAvailability
cartLine.discountsArray[ { "amount", "applicationType", "title", "value", "valueType"} ]If used
cartLine.imageCartLineImageSee belowIf used
cartLine.merchandiseIdString"5667879800"If used
cartLine.priceMoneyV2{ 65.78, "EUR"}Always
cartLine.productIdString"340237068"If used
cartLine.quantityInt4Always
cartLine.titleString"Nice Shoes"Always

cartLine.cartLineImageProperties

PropertyTypeExampleAvailability
cartLine.cartLineImage.altTextString"A beautiful product"If used
cartLine.cartLineImage.lgString"https://example.com/images/product-lg.jpg"Always
cartLine.cartLineImage..mdString"https://example.com/images/product-md.jpg"Always
cartLine.cartLineImage.smString"https://example.com/images/product-sm.jpg"Always

orderDetails.cart.priceProperties

PropertyTypeExampleAvailability
orderDetails.cart.price.discountsArray[ { "amount", "applicationType", "title", "value", "valueType"} ]Always
orderDetails.cart.price.shippingMoneyV2{ 345.98, "USD"}If used
orderDetails.cart.price.subtotalMoneyV2{ 65.78, "EUR"}If used
orderDetails.cart.price.taxesMoneyV2{ 3435.98, "NOK"}If used
orderDetails.cart.price.totalMoneyV2{ 122.73, "CDF"}If used

orderDetails.cart.price.moneyV2Properties

PropertyTypeExampleAvailability
moneyV2.amountFloat345.98If used
moneyV2.currencyCodeStringUSDIf used

deliveryInfoProperties

PropertyTypeExampleAvailability
deliveryInfo.detailsObjectSee belowIf used
deliveryInfo.methodStringCurrent possible methods: SHIPPING, PICK_UP, RETAIL, LOCAL, PICKUP_POINT, NONEAlways

deliveryInfo.deliveryDetailsProperties

PropertyTypeExampleAvailability
deliveryInfo.deliveryDetails.additionalInfoObjectSee sectionIf used
deliveryInfo.deliveryDetails.locationObjectAddressSee sectionIf used
deliveryInfo.deliveryDetails.nameStringHomeIf used

paymentMethodProperties

PropertyTypeExampleAvailability
paymentMethod.detailsMap<String, String>If used
paymentMethod.typeStringMastercardAlways

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

PropertyTypeExampleAvailability
product.idString7629735690428Always
product.availableForSaleBooleantrue | falseAlways
product.compareAtPriceFloat20.99If used
product.descriptionStringVintage cotton shirtIf used
product.handleStringvintage-shirtAlways
product.imagesArray[ "<https://example.com/image.jpg>" ]Always
product.optionsArray<ProductOption>[{ "name": "Color", "values": ["Black", "Blue"]}]Always
product.priceFloat15.99Always
product.tagsArray["Vintage", "Cotton", "New"]If used
product.titleStringVintage ShirtAlways
product.urlStringhttps://www.tapcartcustomblocks.com/products/vintage-shirtAlways
product.vendorStringTapcartIf used
product.selectedVariantString6875079049404Always
product.variantsArray<ProductVariant>"variants": [{ "selectedOptions","id","price", "title","isAvailable,"compareAtPrice","image", "sku"}]Always
product.metafieldsObject{ "my-namespace": { "my-key": "my-value" } }If used

product.options Properties

PropertyTypeExampleAvailability
product.options.nameStringColorAlways
product.options.valuesArray['Black', 'Blue']Always

product.variants Properties

Scroll to the right of the table to view more columns.

PropertyTypeExampleAvailability
product.variants.idString43577520193749Always
product.variants.titleStringBlueAlways
product.variants.imageStringhttps://example.com/image.jpgAlways
product.variants.isAvailableBooleantrue | falseAlways
product.variants.priceFloat10.99Always
product.variants.compareAtPriceFloat20.99If used
product.variants.selectedOptionsArray<SelectedOption>"selectedOptions": [{"name": "Color", "value": "Black"}]Always
product.variants.skuString12938412Always
product.variants.SellingPlanAllocationsArray<SellingPlanAllocations>"sellingPlanAllocations": [{"sellingPlan": { "id": "549355658","name": "Delivery every 1 week", "description": null,"recurringDeliveries": true, "SellingPlanPriceAdjustments","sellingPlanOptions", "sellingPlanAllocationPriceAdjustment"}}]If used
product.variants.metafieldsObject{ "my-namespace": { "my-key": "my-value" } }If used

selectedOptions Properties

PropertyTypeExampleAvailability
product.selectedOption.nameStringColorAlways
product.selectedOption.valueStringBlackAlways

SellingPlanAllocations Properties

Click 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.

PropertyTypeExampleAvailability
product.variants.SellingPlanAllocations.SellingPlan.idString549355658If used
product.variants.SellingPlanAllocations.SellingPlan.nameStringDelivery every 1 weekIf used
product.variants.SellingPlanAllocations.SellingPlan.descriptionStringSubscribe to these socks and get them monthlyIf used
product.variants.SellingPlanAllocations.SellingPlan.recurringDeliveriesBooleanTrue | FalseIf used
product.variants.SellingPlanAllocations.SellingPlan.SellingPlanPriceAdjustmentsArray<SellingPlanPriceAdjustments>"SellingPlanPriceAdjustments": [{ "orderCount": null, "SellingPlanPriceAdjustmentValue" }]If used
product.variants.SellingPlanAllocations.SellingPlan.SellingPlanOptionsArray<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.SellingPlanAllocationPriceAdjustmentsArray<SelectedPlanAllocationPriceAdjustments>"SellingPlanAllocationPriceAdjustments": [{"price": 32.3, "unitPrice": null, "compareAtPrice": 34, "perDeliveryPrice": 32.3}]If used

SellingPlanPriceAdjustments Properties

PropertyTypeExampleAvailability
product.variants.SellingPlanAllocations.SellingPlan.SellingPlanPriceAdjustments.orderCountInteger3If used
product.variants.SellingPlanAllocations.SellingPlan.SellingPlanPriceAdjustments.SellingPlanPriceAdjustmentValueArray<SellingPlanPriceAdjustmentValue>"SellingPlanPriceAdjustmentValue": {"amount": 5, "currencyCode": "USD", "type": "FIXEDAMOUNT"}If used

SellingPlanPriceAdjustmentValue Properties

Scroll to the right of the table to view more columns.

PropertyTypeExampleAvailability
product.variants.SellingPlanAllocations.SellingPlan.SellingPlanPriceAdjustments.SellingPlanPriceAdjustmentValue.typeStringFIXEDAMOUNT | PERCENTAGEIf used
product.variants.SellingPlanAllocations.SellingPlan.SellingPlanPriceAdjustments.SellingPlanPriceAdjustmentValue.currencyCodeStringUSDIf used
product.variants.SellingPlanAllocations.SellingPlan.SellingPlanPriceAdjustments.SellingPlanPriceAdjustmentValue.amountFloat5If type is FIXEDAMOUNT
product.variants.SellingPlanAllocations.SellingPlan.SellingPlanPriceAdjustments.SellingPlanPriceAdjustmentValue.percentageAmountFloat5If type is PERCENTAGE

SellingPlanOptions Properties

Scroll to the right of the table to view more columns.

PropertyTypeExampleAvailability
product.variants.SellingPlanAllocations.SellingPlan.SellingPlanOptions.nameString1 Week(s)If used
product.variants.SellingPlanAllocations.SellingPlan.SellingPlanOptions.valueString1 Week(s), 2 Week(s)If used

SellingPlanAllocationPriceAdjustments Properties

Scroll to the right of the table to view more columns.

PropertyTypeExampleAvailability
product.variants.SellingPlanAllocations.SellingPlan.SellingPlanAllocationPriceAdjustmentss.priceFloat32.20If used
product.variants.SellingPlanAllocations.SellingPlan.SellingPlanAllocationPriceAdjustments.unitPriceFloat32.20If used
product.variants.SellingPlanAllocations.SellingPlan.SellingPlanAllocationPriceAdjustments.compareAtPriceFloat34.00If used
product.variants.SellingPlanAllocations.SellingPlan.SellingPlanAllocationPriceAdjustments.perDeliveryPriceFloat32.30If used

sourceCollection Properties

Scroll to the right of the table to view more columns.

PropertyTypeExample.Availability
product.sourceCollection.idString238472398423Available when a PDP is opened from a collection
product.sourceCollection.titleStringVintage ShirtsAvailable when a PDP is opened from a collection
product.sourceCollection.handleStringvintage-shirtsAvailable when a PDP is opened from a collection
product.sourceCollection.metafields.namespace.keyObject{ "my-namespace": { "my-key": "my-value" } }If used/ Available when a PDP is opened from a collection

metafields Properties

Before 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.

PropertyTypeExampleAvailability
product.metafields.namespace.keyObject{ "my-namespace": { "my-key": "my-value" } }If used
customer.metafields.namespace.keyObject{ "my-namespace": { "my-key": "my-value" } }If used
product.variants.metafields.namespace.keyObject{ "my-namespace": { "my-key": "my-value" } }If used
shop.metafields.namespace.keyObject{ "my-namespace": { "my-key": "my-value" } }If Used

Permissions Properties

possible enums: notDetermined, denied, granted, grantedApproximate, whileUsingApp, notDetermined,granted

PropertyTypeExampleAvailability
permissions.notificationsStringnotDeterminedAlways
permissions.cameraStringdeniedAlways
permissions.trackingStringgrantedAlways
permissions.locationStringgrantedApproximateAlways
permissions.locationDurationStringwhileUsingAppAlways
permissions.smsOptInStringnotDeterminedAlways
permissions.emailOptInStringgrantedAlways

recentlyViewed Properties

PropertyTypeExampleAvailability
recentlyViewed.productsArray['7905425260731, 7909839732923']When user is logged in - product IDs

session

PropertyTypeExampleAvailability
session.idStringABCDE-1234-5678-XYZAlways

shop

Shop variables represent a Shopify stores 3rd party added information. These variables are refreshed when a 3rd party updates them

PropertyTypeExampleAvailability
shop.metafieldsObject{ "my-namespace": { "my-key": "my-value" } }If Available

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:

PropertyTypeExampleAvailability
$theme-tokens-colors-coreColors-brandColorPrimaryString# e21212Always
$theme-tokens-colors-coreColors-dividingLinesString# FFFFFFAlways
$theme-tokens-colors-coreColors-shadowsEnabledBooleantrueAlways

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