Guides

Available Variables

Built-in inputs for getting context on the user

Suggest Edits

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

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.appliedDiscountsArray ["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

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

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

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

Updated 3 months ago