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.emailString[email protected]When 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.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.notesString“This is a cart note”If 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.urlString<https://www.tapcartcustomblocks.com/products/vintage-shirt>Always
product.vendorStringTapcartIf used
product.selectedVariantString6875079049404Always
product.variantsArray<ProductVariant>"variants": [{ "selectedOptions","id","price", "title","isAvailable,"compareAtPrice","image", "sku"}]Always
product.metafieldsArray<Metafields>{ "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.imageString<https://example.com/image.jpg>Always
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

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 us

sourceCollections Properties

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

Property
tapcart.variables.product.sourceCollection.metafields.namespace.key
tapcart.variables.customer.metafields.namespace.key

product.metafields Properties

Before using a product 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

Full Payload Example

{
  "customer": {
    "id": "779544431",
    "firstName": "John"
  },
  "device": {
    "id": "25679b7e-2348-44da-94ef-e218f6be4586",
    "locale": "en"
  },
  "cart": {
    "items": [
      {
        "quantity": 1,
        "productId": "7629735690428",
        "variantId": "43577520193749",
        "sellingPlanId": "1039518903",
        "attributes": [
          {
            "key": "value"
          }
        ]
      }
    ],
    "appliedDiscounts": [
      "TEST10"
    ],
    "subtotal": 0,
    "currency": "USD"
  },
  "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"
    },
    "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",
        "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
                }
              ]
            }
          }
        ]
      }
    ]
  }
}