Skip to main content

Product Added to Cart

When to Use​

This event should be triggered when a visitor successfully adds one or more products to their shopping cart, providing detailed product information for cart analytics and remarketing.

Add to Cart Button
When a visitor clicks the "Add to Cart" button on product pages or product listings.

Quick Add Actions
When products are added through quick-add functionality, one-click additions, or bulk cart operations.

Cart Updates
When the quantity of existing cart items is increased through cart page interactions.

Cross-sell Additions
When related or recommended products are added to the cart through suggestion widgets.

Complete Reference​

event object required

name string required

info

Use only static value product_added_to_cart for `event.name'.

name: "product_added_to_cart"

value number required

info

Event value in decimal format.

Represent the total value of products being added to cart (sum of price × quantity for each product)

value: 123.99

currency string required

info

Currency code that specifies the currency in which all monetary values from any object associated with this event are expressed.

Note: This value can be overridden in nested objects if they contain their own value key with a currency specified.

currency: "USD"

exchange_rate number

info

Custom exchange rate for multi-currency. Default has value 1.

Note: This value can be overridden in nested objects if they contain their own value key with a currency specified.

exchange_rate: 1

id string recommended

info

Event ID — required for any actions that require deduplication or uniqueness. Represents the unique identifier of an action ID used in your system.

id: "UNIQUE_ACTION_ID_123"

context object

info

Use only if exists new data. View complete Context Object documentation

url string required-if-applicable

info

Complete URL of the current page including all parameters

SPA Applications: context.url is particularly valuable for Single Page Applications where URL changes don’t automatically trigger page context updates. Manual implementation ensures accurate tracking of page transitions and user navigation within SPA frameworks.

url:"https://shop.example.com/products/laptop?color=silver&storage=512gb&utm_source=google"
warning

URL Parameter Sensitivity: Be mindful of sensitive information in URLs. Query parameters may contain personal identifiers, session tokens, or private information that should be handled according to privacy regulations.

page_type string recommended

info

Type of page (product, home ...)

page_type: "product"

environment string recommended

info

Allowed values: prod, dev

environment: "prod"

products array required

info

An array containing containing the added product details. View complete Product Object documentation

products[0] object required

id string required

info

Unique product identifier in your system.

id: "PRODUCT_ID"

parent_id string required

info

Parent product ID for variants or child products (can be same as id if no parent concept exists).

parent_id: "PRODUCT_PARENT_ID"

name string required

info

Product name or title displayed to users.

name: "PRODUCT_NAME"

parent_name string

info

Parent product name for variants or child products

parent_name: "PRODUCT_PARENT_NAME"

price_base number required

info

Original or base price before discounts (decimal format: 299.99)

price_base: 120.99

price number required

info

Current selling price after discounts (decimal format: 249.99)

price: 100.99

tax_included boolean required

info

Whether the price includes taxes (true/false)

tax_included: true

tax_percent number required

info

Tax percentage applied to the product (0-100)

tax_percent: 21

quantity number required

info

Quantity of this product in the context of the event

quantity: 1

category string required

info

Main product category name

category: "PRODUCT_MAIN_CATEGORY_NAME"

sku string

info

Product SKU (Stock Keeping Unit) for inventory tracking

sku: "PRODUCT_SKU"

parent_sku string

info

Parent product SKU for variants or child products

parent_sku: "PRODUCT_PARENT_SKU"

gtin string

info

Global Trade Item Number for product identification

gtin: "PRODUCT_GTIN"

mpn string

info

Manufacturer Part Number assigned by the manufacturer

mpn: "PRODUCT_MPN"

ean string

info

European Article Number for product barcoding

ean: "PRODUCT_EAN"

brand string

info

Product brand or manufacturer name

brand: "PRODUCT_BRAND"

type string

info

Product type: "simple", "variable", "virtual", "bundle", "subscription", "external".

Default: simple.

type: "simple"

stock_status boolean recommended

info

Product availability status (true = in stock, false = out of stock)

stock_status: true

stock_location string

info

Physical location or warehouse where product is stored

stock_location: "WAREHOUSE_NAME"

created_at string recommended

info

Timestamp when product was added to inventory (milliseconds)

created_at: 1754926521690

url string

info

Direct URL to the product page

url: "https://shop.example.com/products/laptop-page"

parent_url string

info

URL to the parent product page (for variants)

parent_url: "https://shop.example.com/products/laptop-page"

image string

info

Main product image URL

image: "https://cdn.example.com/products/laptop-image.jpg"

images array

info

Array of additional product image URLs

images: [
  "https://cdn.example.com/products/laptop-image-1.jpg",
  "https://cdn.example.com/products/laptop-image-2.jpg",
]

categories array

info

Array of category objects with name and id properties

  • name (string, required) - Category name
  • id (string) - Category identifier
categories: [
  {
    name: "PRODUCT_FIRST_CATEGORY_NAME",
    id: "1111"
  },
  {
    name: "PRODUCT_SECOND_CATEGORY_NAME",
    id: "1111"
  }
]

coupons array

info

Array of product-level coupons applied to this product. View complete Coupon Object documentation

coupons[0] (object) - required

name string required

info

Coupon name or code.

name: "FREE SHIPPING"

value number recommended

info

Coupon discount value.

value: 123.99

tax_included boolean recommended

info

Whether coupon value includes taxes

tax_included: true

tax_precent string recommended

info

Tax percentage for the coupon

tax_precent: 21

id string

info

Coupon internal identifier.

id: "COUPON_INTERNAL_ID"

type string

info

Coupon type (e.g., "LOYALTY", "SEASONAL", "FIRST_ORDER")

type: "SHIPPING"

currency string required-if-applicable

info

Currency code. Specifies the currency code when it differs from event.currency.

currency: "USD"

exchange_rate number

info

Custom exchange rate for multi-currency. Default has value 1. Specifies when it differs from event.exchange_rate.

exchange_rate: 1

properties object recommended

info

Custom product attributes for audience segmentation. Use custom properties that match your product catalog and business needs.

  • color (string|array) - Product color(s): "blue" or ["blue", "navy"]
  • size (string) - Product size: "S", "M", "L", "XL"
  • material (string|array) - Product material(s): "cotton" or ["cotton", "polyester"]
  • connectivity (string|array) - Connection types: "wireless" or ["wifi", "bluetooth"]
  • storage (string) - Storage capacity: "256GB", "512GB"
  • dimensions (string) - Physical dimensions: "120x60x75cm"
Product Segmentation

Use the properties object to store custom product attributes, with property names defined by each business as needed, that enable advanced segmentation, personalization, and analytics across your marketing campaigns.

properties: {
  color: "space_gray",
  storage: "256GB", 
  memory: "16GB",
  connectivity: ["wifi", "bluetooth"],
  warranty: "2_years",
  energy_rating: "A++",
  brand_series: "pro_line"
  }

currency string required-if-applicable

info

Currency code. Specifies the currency code when it differs from event.currency.

currency: "USD"

exchange_rate number

info

Custom exchange rate for multi-currency. Default has value 1. Specifies when it differs from event.exchange_rate.

exchange_rate: 1

user object recommended

info
View complete User Object documentation

id string recommended

info

Unique customer identifier in your system.

id: "CUSTOMER_INTERNAL_ID"

email string|array recommended

info

Customer email address(es) provided in plaintext or as SHA-256 hashed values.

email: "[email protected]" 
// or
email: ["[email protected]", "[email protected]"]
// or
email: ["3e1ufd1rdnh8l1rfz6xlreyw2yryd4zrf8zsk1pxh2x8wbsp2mw1g93rs5nx68dq"]

phone string|array recommended

info

Customer phone number(s) in E.164 format (plaintext) or as SHA-256 hashed values.

phone: "+40712345678"
// or
phone: ["+40712345678", "+4079876543"]
// or
phone: ["unw5r66oikql4n4tlg2c54bkd2npephsbwwhxuoxreu6ph8uv6k424y9x15opy9y"]

first_name string recommended

info

Customer first name

first_name: "John"

last_name string recommended

info

Customer last name

last_name: "Doe"

country string

info

Country name or ISO country code

country: "Romania"

region string recommended

info

State, province, or region name

region: "Bucuresti"

city string recommended

info

City or locality name

city: "Bucuresti"

street string

info

Street address including number

street: "Strada Principala 1"

postal_code string

info

Postal code or ZIP code

postal_code: "700000"

orders_total_number number recommended

info

Cumulative number of orders placed by this user

orders_total_number: 5

orders_canceled_number number recommended

info

Cumulative number of orders placed and canceled by this user

orders_canceled_number: 0

orders_total_value number recommended

info

Cumulative lifetime user orders value (decimal format: 2500.50)

orders_total_value: 1234.99

orders_refunded_value number recommended

info

Cumulative lifetime user orders value canceled (decimal format: 2500.50)

orders_refunded_value: 250.99

predicted_value number

info

Predicted lifetime value of a customer for your business

predicted_value: 100.99

created_at number recommended

info

Timestamp in milliseconds since Unix epoch representing the first time the user was recorded

created_at: 1754926521690

properties object recommended

info

Custom Customer Properties Examples

User Segmentation

Use the properties object to store custom user attributes, with property names defined by each business as needed, that enable advanced segmentation, personalization, and analytics across your marketing campaigns.

properties: {
  customer_type: "returning",
  membership_level: "platinum",
  preferred_category: ["electronics", "fashion"],
  last_purchase_date: "2024-12-15",
  average_order_value: "350.00",
  payment_method_preference: "card",
  registration_date: "2023-06-15"
}

Object Examples​

These examples demonstrate the complete data object structure for the product_added_to_cart event. Use the complete example for detailed implementations or the minimal example for quick integrations.

{
  "event": {
    "name": "product_added_to_cart",
    "value": 349.98,
    "currency": "USD",
    "exchange_rate": 1,
    "id": "ADD_TO_CART_789123",
    "properties": {
      "add_source": "product_page",
      "cart_items_before": 2,
      "cart_items_after": 4,
      "cart_value_before": 299.99,
      "cart_value_after": 649.97,
      "quantity_selected": 2,
      "variant_selection_time_seconds": 12,
      "recommendation_source": "none",
      "inventory_level": 45,
      "promotion_applied": false
    }
  },
  "context": {
    "environment": "prod",
    "data_source": "website",
    "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15",
    "overide_ip": "192.0.2.98",
    "url": "https://shop.example.com/wireless-earbuds-pro?color=white",
    "landing_url": "https://shop.example.com/audio/headphones",
    "referring_url": "https://google.com/search"
  },
  "products": [
    {
      "id": "EARBUDS_PRO_001",
      "parent_id": "EARBUDS_PRO_001",
      "sku": "EB-PRO-WHT-001",
      "parent_sku": "EB-PRO-001",
      "gtin": "9876543210987",
      "mpn": "EB-PRO-2024-001",
      "ean": "9876543210987",
      "name": "Wireless Earbuds Pro - White",
      "parent_name": "Wireless Earbuds Pro",
      "brand": "AudioTech",
      "type": "simple",
      "price_base": 199.99,
      "price": 174.99,
      "currency": "USD",
      "exchange_rate": 1,
      "tax_included": true,
      "tax_percent": 8.25,
      "quantity": 2,
      "stock_status": true,
      "stock_location": "Audio Warehouse US",
      "created_at": 1748505040077,
      "url": "https://shop.example.com/wireless-earbuds-pro?color=white",
      "parent_url": "https://shop.example.com/wireless-earbuds-pro",
      "image": "https://cdn.example.com/earbuds-pro-white-main.jpg",
      "images": [
        "https://cdn.example.com/earbuds-pro-white-case.jpg",
        "https://cdn.example.com/earbuds-pro-white-side.jpg",
        "https://cdn.example.com/earbuds-pro-white-charging.jpg"
      ],
      "category": "Electronics > Audio > Wireless Earbuds",
      "categories": [
        {
          "name": "Electronics",
          "id": "cat_electronics"
        },
        {
          "name": "Audio",
          "id": "cat_audio"
        },
        {
          "name": "Wireless Earbuds",
          "id": "cat_wireless_earbuds"
        }
      ],
      "properties": {
        "color": "white",
        "connectivity": "bluetooth_5.3",
        "noise_cancellation": "active",
        "battery_life": "24_hours_with_case",
        "water_resistance": "IPX4",
        "driver_size": "12mm",
        "frequency_response": "20Hz-20kHz",
        "charging_case": "wireless_charging",
        "compatibility": ["ios", "android", "windows"],
        "warranty": "1_year_manufacturer"
      }
    }
  ],
  "user": {
    "id": "CUST_456789",
    "email": ["[email protected]"],
    "phone": ["+1555444666"],
    "first_name": "James",
    "last_name": "Wilson",
    "country": "United States",
    "region": "New York",
    "city": "New York",
    "street": "567 Madison Avenue, Suite 12B",
    "postal_code": "10022",
    "properties": {
      "customer_segment": "regular",
      "acquisition_channel": "organic_search",
      "preferred_categories": ["electronics", "audio", "gadgets"],
      "preferred_language": "en",
      "browsing_behavior": "quick_decider",
      "purchase_frequency": "monthly",
      "average_order_value": 178.49,
      "loyalty_tier": "silver",
      "device_preference": "mobile",
      "marketing_consent": true
    }
  }
}

Implementation Methods​

These examples show how to send the data objects using different implementation approaches. Choose the method that best fits your technical setup.

// Web tracking implementation
window.reshape = window.reshape || [];

// Send the complete data object
reshape.push({
  "event": {
    "name": "product_added_to_cart",
    "value": 349.98,
    "currency": "USD",
    "id": "ADD_TO_CART_789123"
  },
  "context": {
    "environment": "prod",
    "data_source": "website"
  },
  "products": [
    {
      "id": "EARBUDS_PRO_001",
      "sku": "EB-PRO-WHT-001",
      "name": "Wireless Earbuds Pro - White",
      "brand": "AudioTech",
      "price": 174.99,
      "quantity": 2
    }
  ],
  "user": {
    "id": "CUST_456789",
    "email": ["[email protected]"]
  }
});

Product Properties Examples​

Audience Segmentation

Use the properties object to capture detailed product attributes that enable precise audience segmentation and better targeting in your advertising campaigns.

properties: {
  color: ["black", "white"],
  size: "M",
  material: "cotton",
  fit: "regular",
  season: "summer",
  collection: "2024_spring"
}
Cart Value Calculation

The value field should represent the total value of all products being added to cart (price × quantity for each product) to ensure accurate conversion tracking.

Implementation Best Practices​

Event Timing​

Button Click Implementation

// Trigger after successful add to cart action
document.getElementById('add-to-cart-btn').addEventListener('click', function() {
  // Validate cart addition first
  if (cartAdditionSuccessful) {
    // Then trigger the event
    reshape.push({
      event: {
        name: "product_added_to_cart",
        value: productPrice * quantity,
        currency: "USD"
      },
      products: [productData]
    });
  }
});

AJAX Cart Implementation

// For AJAX-based cart systems
fetch('/api/cart/add', {
  method: 'POST',
  body: JSON.stringify(cartData)
})
.then(response => response.json())
.then(data => {
  if (data.success) {
    // Trigger event only after successful cart update
    reshape.push(eventData);
  }
});

Data Collection Guidelines​

Value Calculation

  • Calculate total value as sum of (price × quantity) for all products
  • Use final price after discounts, not base price
  • Ensure currency consistency across all products

Quantity Tracking

  • Track actual quantity being added to cart
  • For quantity increases, track additional quantity only
  • Consider inventory limits and maximum order quantities