# DATA Reshape Knowledge Base

> Server-side tracking implementation, data objects reference, and event documentation.


## search

- [Search the documentation](/search.md)

## api

Server-side data collection through webhooks for e-commerce platforms, CRM systems, and enterprise applications.

- [Webhooks Overview](/api.md): Server-side data collection through webhooks for e-commerce platforms, CRM systems, and enterprise applications.

### webhooks

- [Custom Integration](/api/webhooks/custom.md): Custom webhook endpoints tailored to your business requirements and workflows.
- [Event Create](/api/webhooks/reshape.md): Create and track event data with the Standard Integration

## destinations

Supported analytics and advertising destinations for DATA Reshape server-side tracking.

- [Destinations](/destinations.md): Supported analytics and advertising destinations for DATA Reshape server-side tracking.

### google-ads

- [Google Ads Platform Recommended Setup](/destinations/google-ads.md)
- [Google Ads Parameters](/destinations/google-ads/parameters.md)

### google-analytics

Recommended Google Analytics 4 configuration for use with DATA Reshape server-side tracking.

- [Google Analytics Setup](/destinations/google-analytics.md): Recommended Google Analytics 4 configuration for use with DATA Reshape server-side tracking.
- [Google Analytics Parameters](/destinations/google-analytics/parameters.md): Default and custom parameters sent by DATA Reshape to Google Analytics 4.

### meta

Recommended Meta Pixel and Conversions API configuration for use with DATA Reshape server-side tracking.

- [Meta (Facebook) Setup](/destinations/meta.md): Recommended Meta Pixel and Conversions API configuration for use with DATA Reshape server-side tracking.
- [Meta (Facebook) Parameters](/destinations/meta/parameters.md): Default and custom parameters sent by DATA Reshape to Meta Conversions API.

### tiktok

Recommended TikTok Pixel and Events API configuration for use with DATA Reshape server-side tracking.

- [TikTok Setup](/destinations/tiktok.md): Recommended TikTok Pixel and Events API configuration for use with DATA Reshape server-side tracking.
- [TikTok Parameters](/destinations/tiktok/parameters.md): Default and custom parameters sent by DATA Reshape to TikTok Events API.

## events

Events capture user interactions and business transactions on your website. They are pushed into the reshape array using window.reshape.push() and processed by the DATA Reshape script.

- [Events Overview](/events.md): Events capture user interactions and business transactions on your website. They are pushed into the reshape array using window.reshape.push() and processed by the DATA Reshape script.

### consent

- [Consent Updated](/events/consent/consent-updated.md): Push consent state to DATA Reshape — the explicit signal for analytics, personalization and marketing categories. Use this when no native CMP integration is available, or to relay a previously-stored consent decision.
- [Consent Overview](/events/consent/overview.md): How DATA Reshape handles user consent — default denied, native integrations with CMPs and Google Consent Mode v2, three operating modes (full restriction, anonymous ping with replay, server-side queue), per-destination enforcement and audit trail.

### ecommerce

- [Billing Address Added](/events/ecommerce/billing-address-added.md): Track when visitors add billing information during checkout. The DATA Reshape billing_address_added event maps to a custom event in Google Analytics 4 and equivalent events in other connected destinations — one push handles all of them.
- [Cart Viewed](/events/ecommerce/cart-viewed.md): Track when visitors view their shopping cart on your e-commerce website. The DATA Reshape cart_viewed event maps to view_cart in Google Analytics 4 and equivalent events in Meta, TikTok and other connected destinations — one push handles all of them.
- [Checkout Completed](/events/ecommerce/checkout-completed.md): Track when visitors complete a purchase on your e-commerce website. The DATA Reshape checkout_completed event maps to purchase in Google Analytics 4, Purchase in Meta, Purchase in TikTok, plus equivalents in other connected destinations — one push handles all of them.
- [Checkout Started](/events/ecommerce/checkout-started.md): Track when visitors begin the checkout process on your e-commerce website. The DATA Reshape checkout_started event maps to begin_checkout in Google Analytics 4, InitiateCheckout in Meta and TikTok, plus equivalents in other connected destinations — one push handles all of them.
- [Order Canceled](/events/ecommerce/order-canceled.md): Track when an order is canceled or refunded. The DATA Reshape order_canceled event maps to refund in Google Analytics 4, plus the cancellation/refund equivalent in other connected destinations — one push handles all of them. Can be fired client-side (browser) or server-side.
- [Payment Method Selected](/events/ecommerce/payment-method-selected.md): Track when visitors select a payment method during checkout. The DATA Reshape payment_method_selected event maps to add_payment_info in Google Analytics 4, AddPaymentInfo in Meta and TikTok, plus equivalents in other connected destinations — one push handles all of them.
- [Product Added to Cart](/events/ecommerce/product-added-to-cart.md): Track when visitors add products to their shopping cart on your e-commerce website. The DATA Reshape product_added_to_cart event maps to add_to_cart in Google Analytics 4, AddToCart in Meta and TikTok, plus equivalents in other connected destinations — one push handles all of them.
- [Product Added to Wishlist](/events/ecommerce/product-added-to-wishlist.md): Track when visitors save products to their wishlist on your e-commerce website. The DATA Reshape product_added_to_wishlist event maps to add_to_wishlist in Google Analytics 4, AddToWishlist in Meta and TikTok, plus equivalents in other connected destinations — one push handles all of them.
- [Product Removed from Cart](/events/ecommerce/product-removed-from-cart.md): Track when visitors remove products from their shopping cart on your e-commerce website. The DATA Reshape product_removed_from_cart event maps to remove_from_cart in Google Analytics 4 and equivalent custom events in other connected destinations — one push handles all of them.
- [Product Viewed](/events/ecommerce/product-viewed.md): Track when visitors view specific products on your e-commerce website. The DATA Reshape product_viewed event maps to view_item in Google Analytics 4, ViewContent in Meta Pixel and TikTok Events API, plus equivalents in other connected destinations — one push handles all of them.
- [Shipping Detail Added](/events/ecommerce/shipping-detail-added.md): Track when visitors add shipping information during checkout. The DATA Reshape shipping_detail_added event maps to add_shipping_info in Google Analytics 4 and equivalents in other connected destinations — one push handles all of them.

### forms

- [Email Subscribed](/events/forms/email-subscribed.md): Track when visitors subscribe to an email list — newsletter, product alert, back-in-stock or price-drop. The DATA Reshape email_subscribed event maps to subscribe in Google Analytics 4 and Subscribe in Meta and TikTok, plus equivalents in other connected destinations — one push handles all of them.
- [Lead Closed](/events/forms/lead-closed.md): Track when a lead reaches a final stage in your sales pipeline (Closed Won or Closed Lost). The DATA Reshape lead_closed event is forwarded to GA4 as a custom event, plus custom CamelCase events in Meta and TikTok and equivalents in other connected destinations — most valuable when uploaded as offline conversion for ad optimization.
- [Lead Created](/events/forms/lead-created.md): Track when visitors submit a form indicating business interest. The DATA Reshape lead_created event maps to generate_lead in Google Analytics 4, Lead in Meta, SubmitForm in TikTok, plus equivalents in other connected destinations — one push handles all of them.
- [Lead Disqualified](/events/forms/lead-disqualified.md): Track when a lead is disqualified by your marketing or sales process. The DATA Reshape lead_disqualified event is forwarded to GA4 as a custom event, plus custom CamelCase events in Meta and TikTok and equivalents in other connected destinations — useful as a negative signal for ad-targeting optimization.
- [Lead Qualified](/events/forms/lead-qualified.md): Track when a lead is qualified by your marketing or sales process. The DATA Reshape lead_qualified event is forwarded to GA4 as a custom event, plus custom CamelCase events in Meta and TikTok and equivalents in other connected destinations — one push handles all of them.
- [Login](/events/forms/login.md): Track when returning users authenticate on your website. The DATA Reshape login event maps to login in Google Analytics 4, plus custom CamelCase events in Meta and TikTok and equivalents in other connected destinations — one push handles all of them.
- [Sign Up](/events/forms/sign-up.md): Track when visitors create a new account on your website. The DATA Reshape sign_up event maps to sign_up in Google Analytics 4 and CompleteRegistration in Meta and TikTok, plus equivalents in other connected destinations — one push handles all of them.
- [User Updated](/events/forms/user-updated.md): Track when an authenticated user updates their profile information. The DATA Reshape user_updated event maps to a custom event in Google Analytics 4 and equivalent identity-update events in Meta, TikTok and other connected destinations — one push handles all of them.

### interactions

- [Click Interaction](/events/interactions/click.md): Track click interactions on your website — buttons, links, downloads, videos, social shares, and any other clickable element. The DATA Reshape click event is forwarded to GA4 as a custom event, plus custom CamelCase events in Meta and TikTok and equivalents in other connected destinations.
- [Click to Email](/events/interactions/click-to-email.md): Track when visitors click on email address links on your website.
- [Click to Phone](/events/interactions/click-to-phone.md): Track when visitors click on phone number links on your website.
- [Click to WhatsApp](/events/interactions/click-to-whatsapp.md): Track when visitors click on WhatsApp links on your website.

### spa

- [Page Viewed](/events/spa/page_viewed.md): Track manual page-view events for Single Page Applications (SPA) where route changes don't trigger automatic page loads. The DATA Reshape page_viewed event maps to page_view in Google Analytics 4, PageView in Meta and Pageview in TikTok, plus equivalents in other connected destinations — one push handles all of them.

## general

DATA Reshape is a server-side tracking platform that collects, processes, and streams data from your website to analytics and marketing destinations. It operates under your own domain (first-party) for accurate data collection, bypassing ad blockers and browser restrictions.

- [DATA Reshape Documentation](/general.md): DATA Reshape is a server-side tracking platform that collects, processes, and streams data from your website to analytics and marketing destinations. It operates under your own domain (first-party) for accurate data collection, bypassing ad blockers and browser restrictions.

### global-code

Guide to implementing the DATA Reshape tracking script on any website.

- [Global Code Setup](/general/global-code.md): Guide to implementing the DATA Reshape tracking script on any website.
- [Gomag Implementation Guide](/general/global-code/gomag.md): Install DATA Reshape on Gomag stores — overview, prerequisites, and how to grant DATA Reshape admin access for hands-on implementation support.
- [MerchantPro Implementation Guide](/general/global-code/merchantpro.md): Install DATA Reshape on MerchantPro stores — overview, prerequisites, and how to grant DATA Reshape admin access for hands-on implementation support.
- [Shopify Implementation Guide](/general/global-code/shopify.md): Install DATA Reshape on Shopify with a theme snippet and a Custom Pixel — covers Mixed mode (storefront + pixel) and Pixel-only mode.
- [WordPress Implementation Guide](/general/global-code/wordpress.md): Guide to implementing DATA Reshape tracking on WordPress websites.

### monitoring

How to allow the DATA Reshape tracking monitor through your firewall, WAF, or bot protection so it can verify your tracking setup.

- [Allow Monitoring Your Tracking](/general/monitoring.md): How to allow the DATA Reshape tracking monitor through your firewall, WAF, or bot protection so it can verify your tracking setup.

### subdomain

Guide to setting up a dedicated subdomain for server-side tracking.

- [Custom Domain Setup](/general/subdomain.md): Guide to setting up a dedicated subdomain for server-side tracking.
- [Cloudflare DNS Configuration](/general/subdomain/cloudflare.md): CNAME record configuration in Cloudflare with proper proxy settings.
- [cPanel DNS Configuration](/general/subdomain/cpanel.md): CNAME record configuration in cPanel hosting environments.

## objects

Data objects are the building blocks of the DATA Reshape tracking system. These standardized structures ensure consistent tracking across all events and implementations — both web (JavaScript) and webhook (server-to-server).

- [Objects Overview](/objects.md): Data objects are the building blocks of the DATA Reshape tracking system. These standardized structures ensure consistent tracking across all events and implementations — both web (JavaScript) and webhook (server-to-server).

### consent-api

The consent object captures the visitor's explicit preferences for analytics, personalization and marketing data processing. Used in both browser push and server-to-server webhook implementations.

- [Consent Object](/objects/consent-api.md): The consent object captures the visitor's explicit preferences for analytics, personalization and marketing data processing. Used in both browser push and server-to-server webhook implementations.

### context-api

The context API object contains server-side context for events, enabling accurate tracking and attribution in backend implementations.

- [Context API Object](/objects/context-api.md): The context API object contains server-side context for events, enabling accurate tracking and attribution in backend implementations.

### context-web

The context web object contains browser context for events, enabling page tracking and analytics in JavaScript environments.

- [Context Web Object](/objects/context-web.md): The context web object contains browser context for events, enabling page tracking and analytics in JavaScript environments.

### cookies

The cookies object is a flat key-value map of browser cookies used for platform attribution and destination tracking in API implementations.

- [Cookies Object](/objects/cookies.md): The cookies object is a flat key-value map of browser cookies used for platform attribution and destination tracking in API implementations.

### coupon

The coupon object contains information about coupons and discount codes used in e-commerce events for promotion tracking and marketing analytics.

- [Coupon Object](/objects/coupon.md): The coupon object contains information about coupons and discount codes used in e-commerce events for promotion tracking and marketing analytics.

### event

The event object contains information about events used in e-commerce and analytics, enabling comprehensive event tracking and analytics.

- [Event Object](/objects/event.md): The event object contains information about events used in e-commerce and analytics, enabling comprehensive event tracking and analytics.

### payment

The payment object contains information about payment methods used in e-commerce events for payment tracking and financial analytics.

- [Payment Object](/objects/payment.md): The payment object contains information about payment methods used in e-commerce events for payment tracking and financial analytics.

### product

The product object contains information about products in e-commerce events for product tracking and analytics.

- [Product Object](/objects/product.md): The product object contains information about products in e-commerce events for product tracking and analytics.

### shipping

The shipping object contains information about shipping methods and delivery options used in e-commerce events for logistics tracking and analytics.

- [Shipping Object](/objects/shipping.md): The shipping object contains information about shipping methods and delivery options used in e-commerce events for logistics tracking and analytics.

### user

The user object contains information about customers and visitors for user identification, personalization, and analytics.

- [User Object](/objects/user.md): The user object contains information about customers and visitors for user identification, personalization, and analytics.


---

# Full Documentation Content

[Skip to main content](#__docusaurus_skipToContent_fallback)

[![DATA Reshape Logo](https://www.datareshape.ro/images/orizontal-blk-transparent.svg)![DATA Reshape Logo](https://www.datareshape.ro/images/orizontal-wht-transparent.svg)](/)

[Setup](/general.md)[Events](/events.md)[API](/api.md)[Objects](/objects.md)[Destinations](/destinations.md)

[Website](https://www.datareshape.ro)[Status](https://status.datareshape.ro)

Search

# Search the documentation

Type your search here

Powered by[](https://www.algolia.com/)

[sitemap](https://kb.datareshape.ro/sitemap.xml)·[llms.txt](https://kb.datareshape.ro/llms.txt)·[llms-full.txt](https://kb.datareshape.ro/llms-full.txt)·[prompt.txt](https://kb.datareshape.ro/prompt.txt)

[![DATA Reshape Logo](https://www.datareshape.ro/images/orizontal-blk-transparent.svg)![DATA Reshape Logo](https://www.datareshape.ro/images/orizontal-wht-transparent.svg)](https://www.datareshape.ro)

Copyright © 2026 DATA Reshape.


---

# Webhooks Overview

DATA Reshape webhooks provide server-to-server endpoints for sending tracking data directly from your backend systems. This enables reliable data collection without browser dependencies — ideal for e-commerce platforms, CRM systems, and any scenario where server-side tracking is required.

## Prerequisites[​](#Prerequisites "Direct link to Prerequisites")

Plan Requirements

Webhook access is available with **Data Source Addon** on **FLEX plan** and above. Contact DATA Reshape team to enable access for your account.

Once approved, you'll receive:

* **Script ID** — your unique project identifier (8 characters, uppercase alphanumeric)
* **Access Token** — secret authentication key
* **Webhook Base URL** — your configured endpoint (e.g. `https://dre2.YOUR_DOMAIN.TLD`)

## Authentication[​](#Authentication "Direct link to Authentication")

All webhook requests require:

* **Method**: `POST`
* **Content-Type**: `application/json`
* **Header**: `X-Dre-Access-Token: YOUR_ACCESS_TOKEN`
* **Query Parameter**: `id=YOUR_SCRIPT_ID`

## Integration Methods[​](#Integration-Methods "Direct link to Integration Methods")

### Standard Integration[​](#Standard-Integration "Direct link to Standard Integration")

Universal endpoint for tracking any approved event using the Reshape Standard Syntax.

**[Event Create](/api/webhooks/reshape.md)** — single endpoint for all event types (checkout\_completed, lead\_created, order\_canceled, etc.) with support for products, shipping, payments, coupons, user data, cookies, and consent.

```
$endpoint = 'https://dre2.YOUR_DOMAIN.TLD/webhooks/reshape/event?id=YOUR_SCRIPT_ID';

$ch = curl_init($endpoint);
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload),
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'X-Dre-Access-Token: YOUR_ACCESS_TOKEN'
    ],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30
]);

$response = curl_exec($ch);
curl_close($ch);
```

### Custom Integration[​](#Custom-Integration "Direct link to Custom Integration")

CUSTOM Plan Exclusive

Available exclusively for **CUSTOM plan** subscribers with dedicated development resources.

**[About Custom Integration](/api/webhooks/custom.md)** — specialized webhook endpoints designed for your specific business logic, data structures, and operational workflows. Built by the DATA Reshape team in collaboration with your technical team.

## Testing[​](#Testing "Direct link to Testing")

Append **`/test`** to the endpoint path to validate a payload before going live:

```
POST https://dre2.YOUR_DOMAIN.TLD/webhooks/reshape/event/test?id=YOUR_SCRIPT_ID
```

The `/test` endpoint processes **synchronously**, does **not** send to any destination, and returns the full `errors`, `warnings` and `data_received`. Setting `context.environment: "dev"` in the body only skips destination delivery — it does not return this feedback.

## Response Format[​](#Response-Format "Direct link to Response Format")

### Production (async)[​](#Production-async "Direct link to Production (async)")

The production endpoint acknowledges immediately and processes in the background — no per-event feedback:

```
{
  "emitter": "DATA Reshape",
  "detail": "OK",
  "level": 2,
  "version": 6
}
```

### Test — Success[​](#Test--Success "Direct link to Test — Success")

```
{
  "emitter": "DATA Reshape",
  "detail": "Received. This has been processed.",
  "level": 2,
  "version": 6,
  "errors": [],
  "warnings": [
    "context.url is missing. Fallback to config host.",
    "consent object does not match the required format and will be set to an object with all values set to true."
  ],
  "data_received": { }
}
```

### Test — Validation Failure[​](#Test--Validation-Failure "Direct link to Test — Validation Failure")

```
{
  "emitter": "DATA Reshape",
  "detail": "Processing failed — see errors.",
  "level": 2,
  "version": 6,
  "errors": [
    "event.id is missing or does not match the required format."
  ],
  "warnings": [],
  "data_received": { }
}
```

## Getting Started[​](#Getting-Started "Direct link to Getting Started")

1. **Get credentials** — contact the DATA Reshape team for your Script ID and Access Token
2. **Review the data objects** — see [Objects Documentation](/objects.md) for the complete reference
3. **Implement the endpoint** — use [Event Create](/api/webhooks/reshape.md) for standard integration
4. **Test with `/test`** — validate payloads against the `/webhooks/reshape/event/test` endpoint before going to production
5. **Go live** — switch to the production `/webhooks/reshape/event` endpoint when ready

## Support[​](#Support "Direct link to Support")

* **Email**: <support@datareshape.ro>
* **Portal**: <https://www.datareshape.ro/contact>


---

# Custom Integration

Custom Integration enables your business to have dedicated webhook endpoints designed specifically for your data structures, business logic, and operational workflows. Unlike the Standard Integration which uses a fixed schema, custom endpoints are built to match exactly how your systems work.

CUSTOM Plan Exclusive

Available exclusively for **CUSTOM plan** subscribers. Includes dedicated development resources and ongoing support from the DATA Reshape team.

## What We Build[​](#What-We-Build "Direct link to What We Build")

A custom endpoint can handle any server-to-server data flow you need. The endpoint structure, validation rules, data transformation, and processing logic are all tailored to your requirements. There are no limitations on what can be built — if your system can send a POST request with JSON data, we can process it.

Examples of what clients use custom endpoints for:

* ERP order synchronization with custom data structures
* CRM lead and customer data ingestion
* Marketplace order imports with platform-specific formats
* Inventory and stock update webhooks
* Custom event tracking with business-specific schemas
* Legacy system integration where adapting to standard schema isn't practical

## How It Works[​](#How-It-Works "Direct link to How It Works")

1. **Consultation** — we discuss your requirements, data structures, and integration points
2. **Development** — our team builds and tests the custom endpoints
3. **Testing** — you validate in a dev environment before going live
4. **Deployment** — production launch with monitoring
5. **Ongoing support** — maintenance, updates, and evolution as your business grows

Typical delivery time is 5-9 weeks depending on complexity.

## What's Included[​](#Whats-Included "Direct link to What's Included")

* Dedicated endpoint development by the DATA Reshape team
* Technical consultation and architecture guidance
* Comprehensive testing and validation
* Documentation for your custom endpoints
* Ongoing maintenance and support
* Priority technical support with dedicated response times

## Get Started[​](#Get-Started "Direct link to Get Started")

Contact the DATA Reshape team to discuss your requirements:

* **Email**: <support@datareshape.ro>
* **Portal**: <https://www.datareshape.ro/contact>


---

# Event Create

## Overview[​](#Overview "Direct link to Overview")

The **`/webhooks/reshape/event`** endpoint provides a universal API for sending complete event data to DATA Reshape for tracking and analysis. This endpoint supports all approved event types with comprehensive data objects, enabling server-side tracking for e-commerce platforms, CRM systems, and enterprise applications.

## Endpoint Configuration[​](#Endpoint-Configuration "Direct link to Endpoint Configuration")

### **Request Details**[​](#Request-Details "Direct link to Request-Details")

* **URL (production)**: `/webhooks/reshape/event`
* **URL (testing)**: `/webhooks/reshape/event/test` — append **`/test`** to the path to validate a payload **synchronously**. The event is **not** sent to any destination; the response returns the full `errors`, `warnings` and the received payload. Always use this endpoint during integration.
* **Method**: `POST`
* **Content-Type**: `application/json`
* **Authentication**: Required

### **Authentication Requirements**[​](#Authentication-Requirements "Direct link to Authentication-Requirements")

**Headers**

* **`Content-Type`** *(required)* - Must be `application/json`
* **`X-Dre-Access-Token`** *(required)* - Your secret access token

**Query Parameters**

* **`id`** *(required)* - Your script ID provided by DATA Reshape Team

### **Request Structure**[​](#Request-Structure "Direct link to Request-Structure")

```
{
  "event": { /* Event object with name, value, currency, id */ },
  "context": { /* API context with environment, data source, user agent */ },
  "products": [ /* Product array for e-commerce events */ ],
  "shipping": [ /* Shipping methods array */ ],
  "payments": [ /* Payment methods array */ ],
  "coupons": [ /* Discount coupons array */ ],
  "user": { /* Customer data object */ },
  "cookies": { /* Platform cookies for attribution */ },
  "consent": { /* Customer explicit consent */ }
}
```

## Complete Reference[​](#Complete-Reference "Direct link to Complete Reference")

**event** object required

info

Core event object containing event identification, value, and properties. [**View complete Event Object documentation**](/objects/event.md)

<!-- -->

**name** string required

info

Name of the event to be sent.

```
name: "event_name"
```

**value** number required

info

Event value in decimal format. Represent the final total order amount, including all costs and discounts.

```
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 required-if-applicable

info

Event ID — required for transactions or any actions that require deduplication or uniqueness. Represents the unique identifier of a transaction, order, or lead. This can be the unique order, transaction, or action ID used in your system.

```
id: "ord_abc123"
```

**reason** string

info

Short human-readable reason associated with a lifecycle event — the cancellation reason for `order_canceled`, or the disqualification reason for `lead_disqualified`. Free-form string; keep it short and consistent across your implementations so it can be grouped for reporting.

```
reason: "out_of_stock"
```

**properties** object recommended

info

**Custom Event Properties Examples**

* Ecommerce Order
* B2B Lead
* Subscription Service

```
properties: {
  fulfillment_method: "delivery",
  gift_wrap: "true"
}
```

```
properties: {
  lead_status: "converted",
  sales_stage: "proposal"
}
```

```
properties: {
  subscription_tier: "premium",
  billing_cycle: "annual",
  trial_user: "false",
  renewal_date: "2025-06-30",
  support_level: "priority",
  usage_frequency: "daily"
}
```

**context** object required

info

API context object containing environment, data source, and preserved user interaction data. [**View complete Context API Object documentation**](/objects/context-api.md)

**environment** string required

info

Allowed values: prod, dev

```
environment: "prod"
```

**data\_source** string recommended

info

Identifies the origin system the event came from. If omitted, the worker falls back to a default value derived from your account configuration.

Recommended values:

* for website events: **website**
* for admin manual added orders events: **phone** or **admin**
* for app events: **app**
* for marketplace events: **marketplace** (you can replace "marketplace" with the real marketplace name)

```
data_source: "website"
```

**user\_agent** string recommended

info

User-Agent string from a browser when the event occurs

```
user_agent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/138.0.0.0 Safari/537.36"
```

**override\_ip** string recommended

info

Ip address. Support ipv4 or ipv6. Recommended ipv6 if exists.

```
override_ip: "203.0.113.1"
```

**url** string recommended

info

URL of the page where the event occurred

```
url:"https://example.com/thank-you"
```

**landing\_url** string recommended

info

URL of the first page visited in the session where the event occurred

```
landing_url:"https://example.com/landing-page?utm_source=example"
```

**referrer\_url** string recommended

info

URL of the external referring site

```
referrer_url:"https://example-search.com"
```

**products** array required-if-applicable

info

Array of product objects for e-commerce events. Required for product-related events. [**View complete Product Object documentation**](/objects/product.md)

**products\[0]** object required

**id** string required

info

Unique product identifier in your system.

```
id: "prod_abc123"
```

**parent\_id** string recommended

info

Parent product ID for variants or child products. Defaults to `id` if not provided.

```
parent_id: "prod_parent_xyz789"
```

**name** string required

info

Product name or title displayed to users.

```
name: "Example Product Name"
```

**parent\_name** string

info

Parent product name for variants or child products. Defaults to `name` if not provided.

```
parent_name: "Example Parent Product Name"
```

**price\_base** number required

info

Original or base price before discounts. Always equal to or greater than `price`.

```
price_base: 299.99
```

**price** number required

info

Current selling price after discounts. Always equal to or less than `price_base`.

```
price: 249.99
```

**tax\_included** boolean required

info

Whether the price includes taxes. Defaults to `true` if not provided.

```
tax_included: true
```

**tax\_percent** number required

info

Tax percentage applied to the product (0-50). If not provided, the site default tax rate will be used (generally the standard rate of the country).

```
tax_percent: 19
```

**quantity** number required

info

Quantity of this product in the context of the event. Defaults to 1 if not provided.

```
quantity: 2
```

**category** string recommended

info

Main product category name

```
category: "Example Category"
```

**sku** string

info

Product SKU (Stock Keeping Unit) for inventory tracking

```
sku: "sku_abc123"
```

**parent\_sku** string

info

Parent product SKU for variants or child products. Defaults to `sku` if not provided.

```
parent_sku: "sku_parent_xyz789"
```

**gtin** string

info

Global Trade Item Number for product identification

```
gtin: "1234567890123"
```

**mpn** string

info

Manufacturer Part Number assigned by the manufacturer

```
mpn: "MPN-EXAMPLE-001"
```

**ean** string

info

European Article Number for product barcoding

```
ean: "1234567890123"
```

**brand** string

info

Product brand or manufacturer name

```
brand: "Example Brand"
```

**type** string

info

Product type. Free-form string (e.g. "simple", "variable", "bundle", "subscription").

```
type: "simple"
```

**stock\_status** boolean | number | string recommended

info

Product availability, accepted in any of these forms:

* **boolean** — `true` (in stock) / `false` (out of stock)
* **number** — `> 0` = in stock, `0` or negative = out of stock
* **string** — the following (case-insensitive) are treated as **out of stock**: `0`, `no`, `nu`, `false`, `out of stock`, `sold out`, `unavailable`, `indisponibil`, `fara stoc`, `stoc epuizat`.

Any other value is treated as **in stock**. Defaults to `true` (in stock) if not provided.

```
stock_status: true
```

**stock\_location** string

info

Physical location or warehouse where product is stored

```
stock_location: "Example Warehouse"
```

**created\_at** number

info

Timestamp when product was added to inventory (milliseconds)

```
created_at: 1748505040077
```

**url** string

info

Direct URL to the product page

```
url: "https://example.com/products/prod_abc123"
```

**parent\_url** string

info

URL to the parent product page (for variants)

```
parent_url: "https://example.com/products/prod_parent_xyz789"
```

**image** string

info

Main product image URL

```
image: "https://example.com/cdn/prod_abc123-main.jpg"
```

**images** array

info

Array of additional product image URLs

```
images: [
  "https://example.com/cdn/prod_abc123-1.jpg",
  "https://example.com/cdn/prod_abc123-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: "Example Category", id: "cat_abc123" },
  { name: "Example Subcategory", id: "cat_xyz789" }
]
```

**coupons** array

info

Array of product-level coupons applied to this product. [**View complete Coupon Object documentation**](/objects/coupon.md)

**coupons\[0]** (object) - `required`

**name** string required

info

Coupon name or code.

```
name: "EXAMPLE_COUPON"
```

**value** number recommended

info

Coupon discount value.

```
value: 123.99
```

**tax\_included** boolean recommended

info

Whether coupon value includes taxes

```
tax_included: true
```

**tax\_percent** number recommended

info

Tax percentage for the coupon

```
tax_percent: 21
```

**id** string

info

Coupon internal identifier.

```
id: "cpn_abc123"
```

**type** string

info

Coupon type. Free-form string, use consistent naming (e.g. "LOYALTY", "SEASONAL", "FIRST\_ORDER", "SHIPPING").

```
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. Free-form key-value object. Use properties that match your product catalog and business needs.

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.

* IT & C
* Fashion
* Deco

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

```
properties: {
  color: ["black", "white"],
  size: "M",
  material: "cotton",
  fit: "regular", 
  season: "summer",
  collection: "2024_spring",
  care_instructions: "machine_wash"
}
```

```
properties: {
  color: ["natural", "oak"],
  dimensions: "120x80x75cm",
  material: ["wood", "metal"],
  style: "modern",
  room_type: ["living_room", "office"],
  assembly_required: "true"
}
```

**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
```

**shipping** array required-if-applicable

info

Array of shipping methods for checkout and order events. [**View complete Shipping Object documentation**](/objects/shipping.md)

**shipping\[0]** object required

**name** string required

info

Shipping method name

```
name: "Example Shipping Method"
```

**value** number required

info

Shipping cost value

```
value: 12.99
```

**tax\_included** boolean recommended

info

Whether shipping cost includes taxes

```
tax_included: true
```

**tax\_percent** number recommended

info

Tax percentage for shipping (0-50)

```
tax_percent: 19
```

**id** string

info

Shipping method identifier.

```
id: "shp_abc123"
```

**type** string

info

Shipping type. Free-form string, use consistent naming (e.g. "standard", "express", "next\_day", "pickup", "free").

```
type: "standard"
```

**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
```

**payments** array required-if-applicable

info

Array of payment methods for transaction events. [**View complete Payment Object documentation**](/objects/payment.md)

**payments\[0]** object required

**name** string required

info

Payment method name.

```
name: "Example Payment Method"
```

**value** number required

info

Amount paid with this payment method

```
value: 12.99
```

**id** string

info

Payment method internal identifier

```
id: "pay_abc123"
```

**type** string

info

Payment type. Free-form string, use consistent naming (e.g. "card", "paypal", "bank\_transfer", "gift\_card", "cash\_on\_delivery").

```
type: "card"
```

**coupons** array required-if-applicable

info

Array of discount coupons applied to the transaction. [**View complete Coupon Object documentation**](/objects/coupon.md)

**coupons\[0]** object required

**name** string required

info

Coupon name or code.

```
name: "EXAMPLE_COUPON"
```

**value** number recommended

info

Coupon discount value.

```
value: 123.99
```

**tax\_included** boolean recommended

info

Whether coupon value includes taxes

```
tax_included: true
```

**tax\_percent** number recommended

info

Tax percentage for the coupon

```
tax_percent: 21
```

**id** string

info

Coupon internal identifier.

```
id: "cpn_abc123"
```

**type** string

info

Coupon type. Free-form string, use consistent naming (e.g. "LOYALTY", "SEASONAL", "FIRST\_ORDER", "SHIPPING").

```
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
```

**user** object recommended

info

Customer data object for user identification and analytics. [**View complete User Object documentation**](/objects/user.md)

**id** string recommended

info

Unique customer identifier in your system.

```
id: "cust_abc123"
```

**email** string recommended

info

Customer email address in plaintext. Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.

```
email: "example.customer@example.com"
```

**phone** string recommended

info

Customer phone number in E.164 format (plaintext). Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.

```
phone: "+10000000000"
```

**first\_name** string recommended

info

Customer first name

```
first_name: "Example First Name"
```

**last\_name** string recommended

info

Customer last name

```
last_name: "Example Last Name"
```

**country** string

info

Country name or ISO country code

```
country: "US"
```

**region** string recommended

info

State, province, or region name

```
region: "Example Region"
```

**city** string recommended

info

City or locality name

```
city: "Example City"
```

**street** string

info

Street address including number

```
street: "123 Sample Street"
```

**postal\_code** string

info

Postal code or ZIP code

```
postal_code: "00000"
```

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

* E-commerce Customer
* B2B Lead/Customer
* Subscription Service
* Content Platform

```
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"
}
```

```
properties: {
  company_size: "enterprise",
  industry: "fintech",
  job_title: "marketing_director",
  decision_maker: "true",
  budget_range: "50000-100000",
  lead_source: ["linkedin", "webinar"],
  qualification_status: "qualified",
  sales_stage: "proposal"
}
```

```
properties: {
  subscription_tier: "premium",
  billing_cycle: "annual",
  feature_usage: ["analytics", "reporting", "api"],
  trial_user: "false",
  renewal_date: "2025-06-30",
  support_level: "priority",
  usage_frequency: "daily"
}
```

```
properties: {
  content_preferences: ["technology", "business"],
  engagement_level: "high",
  newsletter_subscriber: "true",
  social_media_follower: "true",
  content_consumption: "premium",
  device_preference: ["mobile", "desktop"],
  timezone: "Example/Timezone"
}
```

**consent** object recommended

info

Customer consent object. [**View complete Consent Object documentation**](/objects/consent-api.md)

**analytics** boolean required

info

Indicates the user’s explicit consent regarding the collection and processing of data for analytical purposes, such as performance monitoring, usage statistics, and service optimization.

```
analytics: true
```

**personalization** boolean required

info

Indicates the user’s explicit consent regarding the collection and processing of data for personalization purposes, enabling tailored experiences and content customization.

```
personalization: true
```

**marketing** boolean required

info

Indicates the user’s explicit consent regarding the collection and processing of data for marketing purposes, such as targeted advertising, remarketing, and campaign measurement.

```
marketing: true
```

**id** string

info

Optional consent-record identifier. When present, DATA Reshape can persist or relay the consent decision under this ID — useful when you want each stored decision to be tied to a verifiable reference from your Consent Management Platform (CMP consent ID, IAB TC string hash, internal record ID, etc.). Required when the optional audit-trail persistence feature is enabled on the account.

```
id: "consent_record_abc123"
```

**cookies** object recommended

info

Flat key-value object with platform cookies for attribution and tracking. Each key represents the cookie name and the value represents the cookie value. Both keys and values must be strings. Only cookies mapped by DATA Reshape will be processed — unmapped cookies are accepted but silently ignored. [**View complete Cookies Object documentation**](/objects/cookies.md)

## Event Examples[​](#Event-Examples "Direct link to Event Examples")

These examples demonstrate complete data object structures for key events. Each example includes both full implementation and minimal required fields.

* Complete All Fields
* Checkout Completed
* Order Canceled
* Lead Created
* Lead Qualified
* Lead Closed

### **Complete Example with All Possible Fields**[​](#Complete-Example-with-All-Possible-Fields "Direct link to Complete-Example-with-All-Possible-Fields")

```
{
  "event": {
    "name": "checkout_completed",
    "value": 2399.96,
    "currency": "USD",
    "exchange_rate": 1,
    "id": "ord_abc123",
    "properties": {}
  },
  "context": {
    "environment": "prod",
    "data_source": "website",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
    "override_ip": "203.0.113.1",
    "url": "https://example.com/checkout/success",
    "landing_url": "https://example.com/products/prod_abc123?utm_source=example&utm_medium=cpc&utm_campaign=example_campaign",
    "referrer_url": "https://example-search.com/search?q=example+query"
  },
  "products": [
    {
      "id": "prod_abc123",
      "parent_id": "prod_parent_xyz789",
      "sku": "sku_abc123",
      "parent_sku": "sku_parent_xyz789",
      "gtin": "1234567890123",
      "mpn": "MPN-EXAMPLE-001",
      "ean": "1234567890123",
      "name": "Example Product Name",
      "parent_name": "Example Parent Product Name",
      "brand": "Example Brand",
      "type": "simple",
      "price_base": 1599.99,
      "price": 1399.99,
      "currency": "USD",
      "exchange_rate": 1,
      "tax_included": true,
      "tax_percent": 8,
      "quantity": 1,
      "stock_status": true,
      "stock_location": "Example Warehouse",
      "created_at": 1748505040077,
      "url": "https://example.com/products/prod_abc123",
      "parent_url": "https://example.com/products/prod_parent_xyz789",
      "image": "https://example.com/cdn/prod_abc123-main.jpg",
      "images": [
        "https://example.com/cdn/prod_abc123-1.jpg",
        "https://example.com/cdn/prod_abc123-2.jpg"
      ],
      "category": "Example Category",
      "categories": [
        {
          "name": "Example Category",
          "id": "cat_electronics"
        },
        {
          "name": "Example Category",
          "id": "cat_cameras"
        },
        {
          "name": "Example Category",
          "id": "cat_dslr"
        }
      ],
      "coupons": [
        {
          "name": "EXAMPLE_PRODUCT_COUPON",
          "value": 200.00,
          "tax_included": true,
          "tax_percent": 8,
          "type": "SEASONAL"
        }
      ],
      "properties": {
        "sensor_type": "APS-C",
        "megapixels": 24.2,
        "video_resolution": "4K",
        "warranty_years": 2,
        "model_year": 2024
      }
    },
    {
      "id": "prod_xyz789",
      "sku": "sku_xyz789",
      "name": "Example Accessory Product Name",
      "brand": "Example Brand",
      "type": "simple",
      "price_base": 499.99,
      "price": 449.99,
      "currency": "USD",
      "tax_included": true,
      "tax_percent": 8,
      "quantity": 1,
      "category": "Example Category"
    }
  ],
  "shipping": [
    {
      "name": "Example Express Shipping",
      "value": 24.99,
      "currency": "USD",
      "exchange_rate": 1,
      "tax_included": true,
      "tax_percent": 8,
      "id": "shp_express_abc123",
      "type": "express"
    }
  ],
  "payments": [
    {
      "name": "Example Card Payment",
      "value": 2399.96,
      "id": "pay_abc123",
      "type": "card"
    }
  ],
  "coupons": [
    {
      "name": "EXAMPLE_WELCOME",
      "value": 400.00,
      "currency": "USD",
      "exchange_rate": 1,
      "tax_included": true,
      "tax_percent": 8,
      "id": "cpn_welcome_abc123",
      "type": "WELCOME"
    }
  ],
  "user": {
    "id": "cust_abc123",
    "email": "example.customer@example.com",
    "phone": "+10000000000",
    "first_name": "Example First Name",
    "last_name": "Example Last Name",
    "country": "US",
    "region": "Example Region",
    "city": "Example City",
    "street": "123 Sample Street",
    "postal_code": "00000",
    "orders_total_number": 3,
    "orders_canceled_number": 0,
    "orders_total_value": 3567.89,
    "orders_refunded_value": 0,
    "predicted_value": 5000.00,
    "created_at": 1640995200000,
    "properties": {
      "customer_segment": "loyal",
      "acquisition_channel": "paid_search",
      "preferred_categories": "electronics",
      "loyalty_tier": "gold"
    }
  },
  "consent": {
    "analytics": true,
    "personalization": true,
    "marketing": true
  },
  "cookies": {
    "_ga": "GA1.2.123456789.1640995200",
    "_gid": "GA1.2.987654321.1640995200",
    "_gcl_aw": "GCL.1640995200.CjwKCAiA",
    "_fbp": "fb.1.1640995200.123456789"
  }
}
```

### **Complete Example**[​](#Complete-Example "Direct link to Complete-Example")

```
{
  "event": {
    "name": "checkout_completed",
    "value": 1299.97,
    "currency": "USD",
    "exchange_rate": 1,
    "id": "ord_abc123",
    "properties": {}
  },
  "context": {
    "environment": "prod",
    "data_source": "website",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
    "override_ip": "203.0.113.1",
    "url": "https://example.com/checkout/success"
  },
  "products": [
    {
      "id": "prod_abc123",
      "sku": "sku_abc123",
      "name": "Example Product Name",
      "brand": "Example Brand",
      "type": "simple",
      "price_base": 1399.99,
      "price": 1199.99,
      "currency": "USD",
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Example Category"
    }
  ],
  "shipping": [
    {
      "name": "Example Express Shipping",
      "value": 24.99,
      "currency": "USD",
      "tax_included": true,
      "tax_percent": 19,
      "type": "express"
    }
  ],
  "payments": [
    {
      "name": "Example Card Payment",
      "value": 1299.97,
      "type": "card"
    }
  ],
  "coupons": [
    {
      "name": "EXAMPLE_WELCOME",
      "value": 300.00,
      "currency": "USD",
      "tax_included": true,
      "tax_percent": 19,
      "type": "WELCOME"
    }
  ],
  "user": {
    "id": "cust_abc123",
    "email": "example.customer@example.com",
    "phone": "+10000000000",
    "first_name": "Example First Name",
    "last_name": "Example Last Name",
    "country": "US",
    "city": "Example City"
  },
  "consent": {
    "analytics": true,
    "personalization": true,
    "marketing": true
  }
}
```

### **Minimal Required Example**[​](#Minimal-Required-Example "Direct link to Minimal-Required-Example")

```
{
  "event": {
    "name": "checkout_completed",
    "value": 1299.97,
    "currency": "USD",
    "id": "ord_abc123"
  },
  "context": {
    "environment": "prod",
    "data_source": "website"
  },
  "products": [
    {
      "id": "prod_abc123",
      "price": 1199.99,
      "quantity": 1
    }
  ],
  "shipping": [
    {
      "name": "Example Standard Shipping",
      "value": 15.99
    }
  ],
  "payments": [
    {
      "name": "Example Card Payment",
      "value": 1299.97
    }
  ]
}
```

### **Complete Example**[​](#Complete-Example-1 "Direct link to Complete-Example-1")

```
{
  "event": {
    "name": "order_canceled",
    "value": 1299.97,
    "currency": "USD",
    "exchange_rate": 1,
    "id": "ord_abc123",
    "reason": "customer_request"
  },
  "context": {
    "environment": "prod",
    "data_source": "website",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
    "override_ip": "203.0.113.2",
    "url": "https://example.com/checkout/success"
  },
  "products": [
    {
      "id": "prod_abc123",
      "sku": "sku_abc123",
      "name": "Example Product Name",
      "brand": "Example Brand",
      "type": "simple",
      "price_base": 1399.99,
      "price": 1199.99,
      "currency": "USD",
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Example Category"
    }
  ],
  "shipping": [
    {
      "name": "Example Express Shipping",
      "value": 24.99,
      "currency": "USD",
      "tax_included": true,
      "tax_percent": 19,
      "type": "express"
    }
  ],
  "payments": [
    {
      "name": "Example Card Payment",
      "value": 1299.97,
      "type": "card"
    }
  ],
  "coupons": [
    {
      "name": "EXAMPLE_WELCOME",
      "value": 300.00,
      "currency": "USD",
      "tax_included": true,
      "tax_percent": 19,
      "type": "WELCOME"
    }
  ],
  "user": {
    "id": "cust_abc123",
    "email": "example.customer@example.com",
    "phone": "+10000000000",
    "first_name": "Example First Name",
    "last_name": "Example Last Name",
    "country": "US",
    "city": "Example City"
  },
  "consent": {
    "analytics": true,
    "personalization": true,
    "marketing": true
  }
}
```

### **Minimal Required Example**[​](#Minimal-Required-Example-1 "Direct link to Minimal-Required-Example-1")

```
{
  "event": {
    "name": "order_canceled",
    "value": 1299.97,
    "currency": "USD",
    "id": "ord_abc123",
    "reason": "customer_request"
  },
  "context": {
    "environment": "prod",
    "data_source": "website"
  },
  "products": [
    {
      "id": "prod_abc123",
      "price": 1199.99,
      "quantity": 1
    }
  ],
  "shipping": [
    {
      "name": "Example Standard Shipping",
      "value": 15.99
    }
  ],
  "payments": [
    {
      "name": "Example Card Payment",
      "value": 1299.97
    }
  ]
}
```

### **Complete Example**[​](#Complete-Example-2 "Direct link to Complete-Example-2")

```
{
  "event": {
    "name": "lead_created",
    "value": 250.00,
    "currency": "USD",
    "id": "lead_abc123",
    "properties": {}
  },
  "context": {
    "environment": "prod",
    "data_source": "website",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
    "override_ip": "203.0.113.1",
    "url": "https://example.com/contact/web-development"
  },
  "user": {
    "email": "example.lead@example.com",
    "phone": "+10000000000",
    "first_name": "Example First Name",
    "last_name": "Example Last Name",
    "country": "US",
    "region": "Example City",
    "city": "Example City",
    "predicted_value": 2500.00,
    "created_at": 1754926521690,
    "properties": {
      "job_title": "Example Job Title",
      "company_industry": "software_development",
      "contact_preference": "email"
    }
  },
  "consent": {
    "analytics": true,
    "personalization": true,
    "marketing": true
  }
}
```

### **Minimal Required Example**[​](#Minimal-Required-Example-2 "Direct link to Minimal-Required-Example-2")

```
{
  "event": {
    "name": "lead_created",
    "id": "lead_abc123"
  },
  "context": {
    "environment": "prod",
    "data_source": "website"
  }
}
```

### **Complete Example**[​](#Complete-Example-3 "Direct link to Complete-Example-3")

```
{
  "event": {
    "name": "lead_qualified",
    "value": 1500.00,
    "currency": "USD",
    "id": "lead_abc123",
    "properties": {}
  },
  "context": {
    "environment": "prod",
    "data_source": "crm",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
    "override_ip": "203.0.113.3",
    "url": "https://crm.example.com/leads/qualify"
  },
  "user": {
    "id": "lead_user_abc123",
    "email": "example.prospect@example.com",
    "phone": "+10000000000",
    "first_name": "Example First Name",
    "last_name": "Example Last Name",
    "country": "US",
    "region": "Example Region",
    "predicted_value": 8500.00,
    "properties": {
      "company": "Example Company Inc.",
      "job_title": "Example Job Title",
      "company_size": "100-500",
      "industry": "technology"
    }
  }
}
```

### **Minimal Required Example**[​](#Minimal-Required-Example-3 "Direct link to Minimal-Required-Example-3")

```
{
  "event": {
    "name": "lead_qualified",
    "id": "lead_abc123"
  },
  "context": {
    "environment": "prod",
    "data_source": "crm"
  }
}
```

### **Complete Example**[​](#Complete-Example-4 "Direct link to Complete-Example-4")

```
{
  "event": {
    "name": "lead_closed",
    "value": 4500.00,
    "currency": "USD",
    "id": "lead_closed_abc123",
    "properties": {}
  },
  "context": {
    "environment": "prod",
    "data_source": "crm",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
    "override_ip": "203.0.113.4",
    "url": "https://crm.example.com/deals/close"
  },
  "user": {
    "id": "cust_xyz789",
    "email": "example.customer@example.com",
    "phone": "+10000000000",
    "first_name": "Example First Name",
    "last_name": "Example Last Name",
    "country": "US",
    "region": "Example City",
    "orders_total_value": 4500.00,
    "created_at": 1740000000000,
    "properties": {
      "company": "Example Company Inc.",
      "job_title": "Example Job Title",
      "company_size": "1000+",
      "industry": "finance"
    }
  }
}
```

### **Minimal Required Example**[​](#Minimal-Required-Example-4 "Direct link to Minimal-Required-Example-4")

```
{
  "event": {
    "name": "lead_closed",
    "id": "lead_closed_abc123"
  },
  "context": {
    "environment": "prod",
    "data_source": "crm"
  }
}
```

## Response Format[​](#Response-Format "Direct link to Response Format")

The response shape depends on which endpoint you call. The **production** endpoint acknowledges immediately and processes in the background; the **test** endpoint (`/test`) processes synchronously and returns detailed validation feedback.

### **Production Response**[​](#Production-Response "Direct link to Production-Response")

The production endpoint (`/webhooks/reshape/event`) returns `200` immediately and processes the event **in the background**. You do **not** receive per-event validation feedback here — only a plain acknowledgement:

```
{
  "emitter": "DATA Reshape",
  "detail": "OK",
  "level": 2,
  "version": 6
}
```

### **Test Response — Success**[​](#Test-Response--Success "Direct link to Test-Response--Success")

The test endpoint (`/webhooks/reshape/event/test`) processes **synchronously**, does **not** send to any destination, and returns the full `errors`, `warnings` and `data_received` (the payload you sent). On a valid payload you get `200`:

```
{
  "emitter": "DATA Reshape",
  "detail": "Received. This has been processed.",
  "level": 2,
  "version": 6,
  "errors": [],
  "warnings": [
    "context.url is missing. Fallback to config host.",
    "consent object does not match the required format and will be set to an object with all values set to true."
  ],
  "data_received": { }
}
```

### **Test Response — Validation Failure**[​](#Test-Response--Validation-Failure "Direct link to Test-Response--Validation-Failure")

If validation fails on the test endpoint you get `400`, with the reasons in `errors`:

```
{
  "emitter": "DATA Reshape",
  "detail": "Processing failed — see errors.",
  "level": 2,
  "version": 6,
  "errors": [
    "event.id is missing or does not match the required format."
  ],
  "warnings": [],
  "data_received": { }
}
```

### **Transport & Auth Errors**[​](#Transport--Auth-Errors "Direct link to Transport--Auth-Errors")

Returned before processing, on either endpoint:

* **`403`** — `{ "detail": "Config ID is wrong." }` — the `id` query parameter is missing or invalid.
* **`404`** — `{ "detail": "Invalid request pathname" }` — the path is not `/webhooks/reshape/event` or `/webhooks/reshape/event/test`.
* **`405`** — `{ "detail": "Method not allowed" }` — the method is not `POST`.
* **`400`** — `{ "detail": "Invalid request body.", "errors": ["Invalid request body."] }` — the body is not valid JSON, or not a JSON object.

An invalid `X-Dre-Access-Token` is rejected during processing: on the production endpoint the event is silently dropped in the background (you still get the `200` ack), while on the `/test` endpoint it is reported as an error — another reason to validate with `/test` first.

## Implementation[​](#Implementation "Direct link to Implementation")

### **PHP Example (Recommended)**[​](#PHP-Example-Recommended "Direct link to PHP-Example-Recommended")

```
$scriptId = 'YOUR_SCRIPT_ID';
$accessToken = 'YOUR_ACCESS_TOKEN';
$endpoint = 'https://your-subdomain.datareshape.net/webhooks/reshape/event?id=' . $scriptId;

$payload = [
    'event' => [
        'name' => 'checkout_completed',
        'value' => 299.99,
        'currency' => 'RON',
        'id' => $orderId
    ],
    'context' => [
        'environment' => 'prod',
        'data_source' => 'website',
        'user_agent' => $_SERVER['HTTP_USER_AGENT'] ?? '',
        'url' => 'https://example.com/checkout/success'
    ],
    'products' => $products,
    'shipping' => $shipping,
    'payments' => $payments,
    'user' => [
        'email' => $customer['email'],
        'first_name' => $customer['first_name'],
        'last_name' => $customer['last_name']
    ],
    'cookies' => [
        '_ga' => $_COOKIE['_ga'] ?? null,
        '_fbp' => $_COOKIE['_fbp'] ?? null
    ],
    'consent' => [
        'analytics' => true,
        'personalization' => true,
        'marketing' => true
    ]
];

$ch = curl_init($endpoint);
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload),
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'X-Dre-Access-Token: ' . $accessToken
    ],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode === 200) {
    $data = json_decode($response, true);
    // Check warnings array for any issues
    if (!empty($data['warnings'])) {
        error_log('DATA Reshape warnings: ' . implode(', ', $data['warnings']));
    }
} else {
    error_log('DATA Reshape error (' . $httpCode . '): ' . $response);
}
```

## Best Practices[​](#Best-Practices "Direct link to Best Practices")

1. **Event Validation** — validate event data before sending to ensure required fields are present
2. **Unique IDs** — use consistent, unique identifiers for events to prevent duplicate tracking
3. **Value Calculation** — ensure event values accurately represent business metrics
4. **Properties Limit** — keep custom properties focused and limit to 5 key properties for optimal performance
5. **Currency Consistency** — use consistent currency codes across related events
6. **Test with `/test`** — during integration, POST to `/webhooks/reshape/event/test`. It validates synchronously and returns the `errors`, `warnings` and `data_received` so you can confirm your payload before going live, without sending anything to destinations. Note: setting `context.environment: "dev"` in the body only skips destination delivery — it does **not** return the validation feedback; only the `/test` path (or `?env=dev` query) does.

## Support[​](#Support "Direct link to Support")

For technical support and integration assistance:

* **Email**: <support@datareshape.ro>


---

# Destinations

Destinations are the analytics and advertising platforms where DATA Reshape sends your tracking data. Each destination receives events processed through your server-side infrastructure, ensuring accurate attribution and improved data quality.

## Supported Destinations[​](#Supported-Destinations "Direct link to Supported Destinations")

| Destination                                             | Type        | Documentation                                                                                          |
| ------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------ |
| [Google Analytics 4](/destinations/google-analytics.md) | Analytics   | [Setup](/destinations/google-analytics.md), [Parameters](/destinations/google-analytics/parameters.md) |
| Google Ads                                              | Advertising | *Coming soon*                                                                                          |
| [Meta (Facebook)](/destinations/meta.md)                | Advertising | [Setup](/destinations/meta.md), [Parameters](/destinations/meta/parameters.md)                         |
| [TikTok](/destinations/tiktok.md)                       | Advertising | [Setup](/destinations/tiktok.md), [Parameters](/destinations/tiktok/parameters.md)                     |
| Criteo                                                  | Advertising | *Coming soon*                                                                                          |

## Documentation Structure[​](#Documentation-Structure "Direct link to Documentation Structure")

Each destination has two pages:

* **Setup** — recommended configuration in the destination's own interface for optimal tracking with DATA Reshape
* **Parameters** — default and custom parameters sent by DATA Reshape, and how to use them in the destination

## How It Works[​](#How-It-Works "Direct link to How It Works")

1. Events are collected via the tracking script or webhooks
2. DATA Reshape processes, validates, and enriches the data
3. Processed events are delivered server-side to each configured destination
4. Each destination receives only the events mapped in your account configuration


---

# Google Ads Platform Recommended Setup


---

# Google Ads Parameters


---

# Google Analytics Setup

Recommended configuration for your Google Analytics 4 property when using DATA Reshape server-side tracking.

info

These are our recommendations for optimal tracking accuracy. Your setup may vary based on your specific requirements.

This guide assumes you already have a GA4 property created. If not, create one first at [analytics.google.com](https://analytics.google.com).

## Reporting Identity[​](#Reporting-Identity "Direct link to Reporting Identity")

**Admin → Data display → Reporting identity**

Select **Blended**. This combines User-ID, Google Signals, device ID, and modeling to provide the most complete view of your users across sessions and devices.

## Google Signals[​](#Google-Signals "Direct link to Google Signals")

**Admin → Data collection and modification → Data collection → Google signals data collection**

Turn **On**. Google Signals enables cross-device reporting, remarketing audiences, and demographics data in your reports.

## User-ID and User-Provided Data[​](#User-ID-and-User-Provided-Data "Direct link to User-ID and User-Provided Data")

**Admin → Data collection and modification → Data collection → User-ID and user-provided data collection**

Enable both settings:

* **User-ID collection** → On
* **User-provided data collection** → On

Then set:

* **Collect automatically-detected user-provided data** → **Off**

User data (email, phone, etc.) is collected and hashed by DATA Reshape before being sent to GA4. Automatic detection by GA4 is not needed and may cause duplicates or collect data without proper consent.

## User Data Collection Acknowledgement[​](#User-Data-Collection-Acknowledgement "Direct link to User Data Collection Acknowledgement")

**Admin → Data collection and modification → Data collection → User Data Collection Acknowledgement**

Click **I acknowledge**. This is required by Google to confirm that you have appropriate consent mechanisms in place for collecting user data.

## Referral Exclusions[​](#Referral-Exclusions "Direct link to Referral Exclusions")

**Admin → Data collection and modification → Data streams → \[your stream] → Configure tag settings → List unwanted referrals**

Add your payment processors to prevent them from appearing as traffic sources and breaking attribution. Common examples:

| Payment Processor | Domain(s) to exclude   |
| ----------------- | ---------------------- |
| PayPal            | `paypal.com`           |
| Stripe            | `stripe.com`           |
| Netopia           | `netopia-payments.com` |
| euPlatesc         | `euplatesc.ro`         |
| Mobilpay          | `mobilpay.ro`          |
| 3D Secure pages   | Your bank's 3DS domain |

Add any other payment gateway domains that redirect users during checkout. Without these exclusions, returning users are attributed to the payment processor instead of the original traffic source.

## Official Documentation[​](#Official-Documentation "Direct link to Official Documentation")

* [Google Analytics 4 Admin overview](https://support.google.com/analytics/answer/6132368)
* [Reporting identity](https://support.google.com/analytics/answer/10976610)
* [Google Signals](https://support.google.com/analytics/answer/9445345)
* [User-ID](https://support.google.com/analytics/answer/9213390)
* [User-provided data collection](https://support.google.com/analytics/answer/14077171)
* [List unwanted referrals](https://support.google.com/analytics/answer/10327750)


---

# Google Analytics Parameters

## Default Parameters[​](#Default-Parameters "Direct link to Default Parameters")

DATA Reshape sends events to GA4 using the standard Measurement Protocol parameters. For the full list of default parameters and their descriptions, see the official documentation:

* [GA4 Measurement Protocol parameters](https://developers.google.com/analytics/devguides/collection/protocol/ga4/reference)
* [GA4 event parameters reference](https://developers.google.com/analytics/devguides/collection/protocol/ga4/reference/events)
* [Automatically collected events](https://support.google.com/analytics/answer/9234069)
* [Enhanced measurement events](https://support.google.com/analytics/answer/9216061)

## Custom Parameters[​](#Custom-Parameters "Direct link to Custom Parameters")

In addition to default parameters, DATA Reshape can send custom parameters with each event. These parameters carry additional data from your implementation that is not covered by GA4's standard schema.

Custom parameters are **not visible in GA4 reports by default**. To use them, you need to register them as **Custom Dimensions** or **Custom Metrics** in your GA4 property.

### How to register Custom Dimensions[​](#How-to-register-Custom-Dimensions "Direct link to How to register Custom Dimensions")

**Admin → Data display → Custom definitions → Custom dimensions → Create custom dimension**

For each parameter you want to use in reports:

| Field                               | Description                                                          |
| ----------------------------------- | -------------------------------------------------------------------- |
| **Dimension name**                  | Display name in your reports (e.g. "Payment Method")                 |
| **Scope**                           | **Event** for per-event data, **User** for user-level data           |
| **Event parameter / User property** | Exact parameter name as sent by DATA Reshape (e.g. `payment_method`) |

### Available Custom Parameters[​](#Available-Custom-Parameters "Direct link to Available Custom Parameters")

These are the custom parameters DATA Reshape sends to GA4. Some may be absent if the data source does not provide the underlying data.

#### Event Scope[​](#Event-Scope "Direct link to Event Scope")

| Parameter          | Description                                                                                |
| ------------------ | ------------------------------------------------------------------------------------------ |
| `payment_type`     | Payment method type(s) — `card`, `wallet`, `cod` (`purchase`/`refund`)                     |
| `payment_name`     | Friendly payment method name(s) — `Card`, `Klarna` (`purchase`/`refund`)                   |
| `shipping_tier`    | Shipping method name(s) for the order (`purchase`/`refund`)                                |
| `coupon`           | Order-level coupon code(s) (`purchase`/`refund`)                                           |
| `reason`           | Reason for the event (`order_canceled` cancellation, `lead_disqualified` disqualification) |
| `data_source`      | Origin of the event data (e.g. website, webhook)                                           |
| `integration`      | DATA Reshape integration source identifier                                                 |
| `browser_app`      | In-app browser / app context (e.g. facebook, instagram)                                    |
| `last_ad_source`   | Last advertising platform that drove the user                                              |
| `new_customer`     | `0` returning / `1` new (derived from order history)                                       |
| `browser_storage`  | Consent state string, e.g. `a:yes \| m:no` (a=analytics, m=marketing)                      |
| `event_prop_<key>` | Any custom `event.properties` key (see [Custom Properties](#Custom-Properties))            |

#### Item Scope[​](#Item-Scope "Direct link to Item Scope")

Sent per item in the GA4 `items[]` array.

| Parameter                          | Description                                                                           |
| ---------------------------------- | ------------------------------------------------------------------------------------- |
| `item_id`                          | Product ID (or the virtual grouped ID when `override.products.id` is configured)      |
| `item_name`                        | Product name                                                                          |
| `item_parent_name`                 | Parent product name (only when different from `item_name`)                            |
| `item_brand`                       | Product brand                                                                         |
| `item_category` … `item_category5` | Category levels (max 5)                                                               |
| `item_sku`                         | Product SKU                                                                           |
| `item_group_id`                    | Parent/group product ID                                                               |
| `item_group_sku`                   | Parent/group product SKU                                                              |
| `item_type`                        | Product type (e.g. `simple`, `variable`)                                              |
| `item_stock_status`                | Stock status (original value)                                                         |
| `item_stock_exists`                | Boolean stock availability                                                            |
| `item_tax_percent`                 | Tax percentage applied to the product                                                 |
| `price`                            | Unit price (with/without tax per `override.tax_included`)                             |
| `discount`                         | Discount amount (`price_base − price`, min 0)                                         |
| `quantity`                         | Quantity                                                                              |
| `coupon`                           | Product-level coupon code(s)                                                          |
| `last_ad_source`                   | Last ad source (replicated per item for BigQuery attribution)                         |
| `item_<key>`                       | Any custom `products[*].properties` key (see [Custom Properties](#Custom-Properties)) |

#### User Scope[​](#User-Scope "Direct link to User Scope")

Sent as GA4 user properties.

| Parameter                  | Description                                                                    | Type                 |
| -------------------------- | ------------------------------------------------------------------------------ | -------------------- |
| `customer_lifetime_value`  | Total revenue from this customer                                               | number (default `0`) |
| `customer_lifetime_orders` | Total number of orders                                                         | number (default `0`) |
| `customer_canceled_orders` | Number of canceled orders                                                      | number (default `0`) |
| `customer_refunded_value`  | Total refunded value                                                           | number (default `0`) |
| `new_customer`             | `0` returning / `1` new                                                        | number               |
| `customer_city`            | Customer city                                                                  | string               |
| `customer_region`          | Customer region/state                                                          | string               |
| `customer_country`         | Customer country                                                               | string               |
| `last_ad_source`           | Last advertising platform that drove the user                                  | string               |
| `<key>`                    | Any custom `user.properties` key (see [Custom Properties](#Custom-Properties)) | string               |

Lifetime metrics are numbers

`customer_lifetime_value`, `customer_lifetime_orders`, `customer_canceled_orders` and `customer_refunded_value` are always sent as **numbers, defaulting to `0`** when the source does not provide them — register them as GA4 **Custom Metrics** (not dimensions) to aggregate them.

### Custom Properties[​](#Custom-Properties "Direct link to Custom Properties")

DATA Reshape forwards your free-form `properties` objects to GA4 automatically — you do not need to configure per-key mapping, only register the ones you want to use as Custom Dimensions.

| Reshape source                 | GA4 mapping                    | Example                                                         |
| ------------------------------ | ------------------------------ | --------------------------------------------------------------- |
| `event.properties.<key>`       | event param `event_prop_<key>` | `event.properties.campaign_id` → `event_prop_campaign_id`       |
| `products[*].properties.<key>` | item param `item_<key>`        | `properties.color` → `item_color`                               |
| `user.properties.<key>`        | user property `<key>`          | `user.properties.billing_account_type` → `billing_account_type` |

* Keys are normalized to **snake\_case** (`event.properties` and item keys); overly long keys (> 45 chars) are skipped.
* Multi-value arrays are joined with `|` (e.g. `["red","blue"]` → `red|blue`).
* `user.properties` keys are sent **raw** (as provided) — e.g. send `user.properties.billing_account_type = "business"` to get the GA4 user property `billing_account_type = "business"`.

### GA4 Custom Dimensions Limits[​](#GA4-Custom-Dimensions-Limits "Direct link to GA4 Custom Dimensions Limits")

GA4 has limits on the number of custom dimensions you can create:

| Type         | Free Properties | Analytics 360 |
| ------------ | --------------- | ------------- |
| Event-scoped | 50              | 125           |
| User-scoped  | 25              | 100           |

Register only the parameters you actively use in reports or audiences to stay within limits.

## Official Documentation[​](#Official-Documentation "Direct link to Official Documentation")

* [Custom dimensions and metrics](https://support.google.com/analytics/answer/10075209)
* [GA4 Measurement Protocol](https://developers.google.com/analytics/devguides/collection/protocol/ga4)
* [Event parameters limits](https://support.google.com/analytics/answer/9267744)


---

# Meta (Facebook) Setup

Recommended configuration for your Meta Pixel and Conversions API when using DATA Reshape server-side tracking.

info

These are our recommendations for optimal tracking accuracy. Your setup may vary based on your specific requirements.

This guide assumes you already have a Meta Pixel created in Events Manager. If not, create one first at [business.facebook.com](https://business.facebook.com).

## Disable Tracking Without Code[​](#Disable-Tracking-Without-Code "Direct link to Disable Tracking Without Code")

**Events Manager → Data sources → \[your Pixel] → Settings → Tracking without code**

Turn **Off**. DATA Reshape handles all event tracking server-side via the Conversions API. Leaving this on may cause duplicate events or track interactions that don't match your intended event schema.

## Official Documentation[​](#Official-Documentation "Direct link to Official Documentation")

* [Meta Pixel overview](https://developers.facebook.com/docs/meta-pixel)
* [Conversions API overview](https://developers.facebook.com/docs/marketing-api/conversions-api)
* [Events Manager settings](https://www.facebook.com/business/help/898185560232180)
* [Event deduplication](https://developers.facebook.com/docs/marketing-api/conversions-api/deduplicate-pixel-and-server-events)


---

# Meta (Facebook) Parameters

## Default Parameters[​](#Default-Parameters "Direct link to Default Parameters")

DATA Reshape sends events to Meta via the Conversions API using the standard parameter schema. All supported parameters are sent in the most detailed format possible, including user data (hashed), event data, and product/content information.

For the full list of default parameters:

* [Conversions API parameters](https://developers.facebook.com/docs/marketing-api/conversions-api/parameters)
* [Standard events reference](https://developers.facebook.com/docs/meta-pixel/reference)
* [Server event parameters](https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/server-event)
* [Customer information parameters](https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/customer-information-parameters)

## Custom Parameters[​](#Custom-Parameters "Direct link to Custom Parameters")

In addition to default parameters, DATA Reshape sends custom parameters in the `custom_data` object. These can be used for custom audiences, custom conversions, and reporting in Events Manager.

| Parameter                  | Description                                                        |
| -------------------------- | ------------------------------------------------------------------ |
| `content_variants`         | Product variant identifiers                                        |
| `content_brand`            | Product brands                                                     |
| `content_category`         | Product categories                                                 |
| `customer_lifetime_value`  | Total revenue from this customer                                   |
| `customer_lifetime_orders` | Total number of orders for this customer                           |
| `last_ad_source`           | Last advertising platform that drove the user                      |
| `ad_sources_path`          | Full multi-touch path of ad sources (chronological, `>`-separated) |
| `integration`              | DATA Reshape integration source identifier (e.g. website, webhook) |
| `browser_app`              | In-app browser / app context (e.g. facebook, instagram)            |
| `device_type`              | Device category (e.g. mobile, desktop, tablet)                     |
| `browser_name`             | Browser name (e.g. chrome, safari)                                 |
| `operating_system`         | Operating system (e.g. ios, android, windows)                      |

info

These parameters are sent by default for all clients. Depending on your business requirements, additional custom parameters can be configured for your specific implementation. Some parameters may be absent if the data source does not provide the underlying data.

### Custom Properties[​](#Custom-Properties "Direct link to Custom Properties")

DATA Reshape forwards your free-form `properties` automatically into the `custom_data` object:

| Reshape source                 | Meta mapping                                 |
| ------------------------------ | -------------------------------------------- |
| `event.properties.<key>`       | `event_prop_<key>`                           |
| `products[*].properties.<key>` | aggregated across items into `product_<key>` |

Keys are normalized to snake\_case; multi-value arrays are joined with `|`.

## Using Custom Parameters in Meta[​](#Using-Custom-Parameters-in-Meta "Direct link to Using Custom Parameters in Meta")

Custom parameters appear in **Events Manager → \[your Pixel] → Test Events** and can be used to:

* **Create Custom Audiences** — segment users based on custom parameter values (e.g. `content_brand = "Nike"`)
* **Create Custom Conversions** — define conversions based on specific parameter combinations
* **Optimize Ad Delivery** — use `customer_lifetime_value` for value-based lookalike audiences

## Official Documentation[​](#Official-Documentation "Direct link to Official Documentation")

* [Custom data parameters](https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/custom-data)
* [Custom audiences from events](https://www.facebook.com/business/help/666509013483225)
* [Custom conversions](https://www.facebook.com/business/help/2372251876146528)


---

# TikTok Setup

Recommended configuration for your TikTok Pixel and Events API when using DATA Reshape server-side tracking.

info

These are our recommendations for optimal tracking accuracy. Your setup may vary based on your specific requirements.

This guide assumes you already have a TikTok Pixel created in TikTok Events Manager. If not, create one first at [ads.tiktok.com](https://ads.tiktok.com).

## Disable Event Builder[​](#Disable-Event-Builder "Direct link to Disable Event Builder")

**Events Manager → \[your Pixel] → Manage → Event Builder**

Ensure no events are configured through TikTok's Event Builder (the visual/codeless event setup tool). DATA Reshape handles all event tracking server-side via the Events API. Having events configured in the Event Builder may cause duplicates or track unintended interactions.

If any events exist in the Event Builder, remove them.

## Official Documentation[​](#Official-Documentation "Direct link to Official Documentation")

* [TikTok Pixel overview](https://ads.tiktok.com/help/article/tiktok-pixel)
* [TikTok Events API overview](https://business-api.tiktok.com/portal/docs?id=1741601162187777)
* [Event Builder setup](https://ads.tiktok.com/help/article/event-builder)
* [Event deduplication](https://business-api.tiktok.com/portal/docs?id=1771100865818625)


---

# TikTok Parameters

## Default Parameters[​](#Default-Parameters "Direct link to Default Parameters")

DATA Reshape sends events to TikTok via the Events API using the standard parameter schema. All supported parameters are sent in the most detailed format possible, including user data (hashed), event data, and product/content information.

For the full list of default parameters:

* [Events API parameters](https://business-api.tiktok.com/portal/docs?id=1741601162187777)
* [Standard events reference](https://ads.tiktok.com/help/article/standard-events-parameters)
* [Web events parameters](https://business-api.tiktok.com/portal/docs?id=1771100865818625)

## Custom Parameters[​](#Custom-Parameters "Direct link to Custom Parameters")

In addition to default parameters, DATA Reshape sends custom parameters in the event properties. These can be used for audience segmentation and reporting.

| Parameter                  | Description                                   |
| -------------------------- | --------------------------------------------- |
| `content_variants`         | Product variant identifiers                   |
| `content_brand`            | Product brand name                            |
| `content_category`         | Product category                              |
| `customer_lifetime_value`  | Total revenue from this customer              |
| `customer_lifetime_orders` | Total number of orders for this customer      |
| `last_ad_source`           | Last advertising platform that drove the user |

info

These parameters are sent by default for all clients. Depending on your business requirements, additional custom parameters can be configured for your specific implementation. Some parameters may be absent if the data source does not provide the underlying data.

### Custom Properties[​](#Custom-Properties "Direct link to Custom Properties")

DATA Reshape forwards your free-form `event.properties` automatically into the event `properties` object as `event_prop_<key>` (keys normalized to snake\_case, multi-value arrays joined with `|`). Product-level `products[*].properties` are aggregated into the content parameters above.

## Official Documentation[​](#Official-Documentation "Direct link to Official Documentation")

* [TikTok Events API](https://business-api.tiktok.com/portal/docs?id=1741601162187777)
* [Custom audience from events](https://ads.tiktok.com/help/article/custom-audience-website-traffic)


---

# Events Overview

Events capture user interactions and business transactions on your website. They are pushed into the `reshape` array using `window.reshape.push()` and processed by the DATA Reshape script.

All events use the same standardized structure based on the [Objects documentation](/objects.md) for both web and webhook implementations. The only differences are in the context object (web vs webhook) and how data is collected — automatically via JavaScript or manually via webhooks.

The `event.name` determines how each event is processed and which destinations receive it. Only events mapped in your account configuration will be accepted.

## E-commerce Events[​](#E-commerce-Events "Direct link to E-commerce Events")

Track the complete shopping journey from product discovery to purchase completion.

| Event                                                                       | Description                | Products | Shipping | Payments |
| --------------------------------------------------------------------------- | -------------------------- | -------- | -------- | -------- |
| [Product Viewed](/events/ecommerce/product-viewed.md)                       | Visitor views a product    | ✓        |          |          |
| [Product Added to Cart](/events/ecommerce/product-added-to-cart.md)         | Product added to cart      | ✓        |          |          |
| [Product Added to Wishlist](/events/ecommerce/product-added-to-wishlist.md) | Product saved for later    | ✓        |          |          |
| [Product Removed from Cart](/events/ecommerce/product-removed-from-cart.md) | Product removed from cart  | ✓        |          |          |
| [Cart Viewed](/events/ecommerce/cart-viewed.md)                             | Visitor views their cart   | ✓        |          |          |
| [Checkout Started](/events/ecommerce/checkout-started.md)                   | Checkout process initiated | ✓        |          |          |
| [Billing Address Added](/events/ecommerce/billing-address-added.md)         | Billing info provided      | ✓        |          |          |
| [Shipping Detail Added](/events/ecommerce/shipping-detail-added.md)         | Shipping method selected   | ✓        | ✓        |          |
| [Payment Method Selected](/events/ecommerce/payment-method-selected.md)     | Payment method chosen      | ✓        | ✓        | ✓        |
| [Checkout Completed](/events/ecommerce/checkout-completed.md)               | Order confirmed            | ✓        | ✓        | ✓        |

## Lead & Form Events[​](#Lead--Form-Events "Direct link to Lead & Form Events")

Track lead generation, qualification, and conversion.

| Event                                                   | Description                                                        |
| ------------------------------------------------------- | ------------------------------------------------------------------ |
| [Lead Created](/events/forms/lead-created.md)           | Contact form, demo request, quote request                          |
| [Lead Qualified](/events/forms/lead-qualified.md)       | Lead meets qualification criteria                                  |
| [Lead Disqualified](/events/forms/lead-disqualified.md) | Lead does not meet criteria                                        |
| [Lead Closed](/events/forms/lead-closed.md)             | Lead converts to customer                                          |
| [Sign Up](/events/forms/sign-up.md)                     | New account created                                                |
| [Email Subscribed](/events/forms/email-subscribed.md)   | User subscribes to an email list (newsletter, product alert, etc.) |
| [Login](/events/forms/login.md)                         | User authenticates                                                 |

## Interaction Events[​](#Interaction-Events "Direct link to Interaction Events")

Track click interactions and engagement across the website.

| Event                                                          | Description                                                               |
| -------------------------------------------------------------- | ------------------------------------------------------------------------- |
| [Click](/events/interactions/click.md)                         | Any tracked click interaction (buttons, links, downloads, shares, videos) |
| [Click to Phone](/events/interactions/click-to-phone.md)       | Click on phone number link                                                |
| [Click to WhatsApp](/events/interactions/click-to-whatsapp.md) | Click on WhatsApp link                                                    |
| [Click to Email](/events/interactions/click-to-email.md)       | Click on email address link                                               |

## SPA Events[​](#SPA-Events "Direct link to SPA Events")

For Single Page Applications where URL changes don't trigger automatic page loads.

| Event                                     | Description      |
| ----------------------------------------- | ---------------- |
| [Page Viewed](/events/spa/page_viewed.md) | SPA route change |

## Quick Start[​](#Quick-Start "Direct link to Quick Start")

Start with the two highest-impact events and expand from there:

```
window.reshape = window.reshape || [];

// 1. Track product views
reshape.push({
  "event": {
    "name": "product_viewed",
    "value": 249.99,
    "currency": "USD"
  },
  "products": [
    {
      "id": "prod_abc123",
      "name": "Example Product Name",
      "price_base": 249.99,
      "price": 249.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1
    }
  ]
});

// 2. Track purchases
reshape.push({
  "event": {
    "name": "checkout_completed",
    "value": 299.99,
    "currency": "USD",
    "id": "ord_abc123"
  },
  "products": [
    {
      "id": "prod_abc123",
      "name": "Example Product Name",
      "price_base": 249.99,
      "price": 249.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1
    }
  ],
  "shipping": [
    {
      "name": "Standard Shipping",
      "value": 15.99,
      "type": "standard"
    }
  ],
  "payments": [
    {
      "name": "Credit Card",
      "value": 299.99,
      "type": "card"
    }
  ],
  "user": {
    "email": "example.customer@example.com"
  }
});
```

For complete field reference and all available properties, see the [Objects documentation](/objects.md).


---

# Consent Updated

Push the consent state for the visitor — `analytics`, `personalization` and `marketing` — so DATA Reshape can enforce per-destination tracking restrictions. Without this signal (or an equivalent native CMP/Google Consent Mode v2 signal), Reshape stays in the **default-denied** state and tracking runs in GDPR-restricted mode.

Native CMP integrations

DATA Reshape is integrated with most major Consent Management Platforms and commerce platforms (Shopify, MerchantPro, Gomag and others) — when one is detected, the native consent signal is read automatically and you do not need to fire this event manually. The same applies to **Google Consent Mode v2** (`gtag('consent', 'update', ...)`), which Reshape listens to natively with anti-spoofing protection. See the [Consent Overview](/events/consent/overview.md) for the full list and detection logic.

Use this manual push only when your CMP is not auto-detected, or when you need to relay a stored consent decision programmatically (mobile webview, SPA route guard, server-rendered banner, etc.).

## When to push[​](#When-to-push "Direct link to When to push")

* **First-time consent decision** — push immediately after the visitor interacts with your consent banner.
* **Returning visitor with stored consent** — push **once** at the start of the session, before any tracked event, so Reshape exits the default-denied state immediately.
* **Mid-session change** — push every time the visitor opens preferences and updates the consent state. The new state applies to all subsequent events; in Queue+Replay mode, the new state is also applied to queued events before replay.
* **Programmatic update** from a non-DOM source (mobile webview bridge, SSO callback that restores a stored consent, etc.).

## Payload variants[​](#Payload-variants "Direct link to Payload variants")

The `consent_updated` push supports three shapes — pick the one that matches your scenario.

* Full event push
* Consent-only push (no event)
* Consent-only push with id

The standard variant — push as a normal Reshape event with an `event` object and the `consent` object.

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "consent_updated"
  },
  "consent": {
    "analytics": true,
    "personalization": true,
    "marketing": false
  }
});
```

When you only need to notify Reshape about the current consent state and do not need to fire an event at the same time, push **just** the `consent` object — the `event` object is optional in this case. This is the recommended shape for relaying a stored consent decision at session start, before any tracked event is fired.

```
window.reshape = window.reshape || [];
reshape.push({
  "consent": {
    "analytics": true,
    "personalization": true,
    "marketing": false
  }
});
```

Add an `id` to the `consent` object when you want Reshape to forward or persist the consent decision under a specific identifier — useful when your account is configured to relay the consent record to an audit destination or to a CRM, or when you want the consent decision pinned to a known consent-record ID for later traceability.

```
window.reshape = window.reshape || [];
reshape.push({
  "consent": {
    "id": "consent_record_abc123",
    "analytics": true,
    "personalization": true,
    "marketing": false
  }
});
```

## Complete Reference[​](#Complete-Reference "Direct link to Complete Reference")

The `consent_updated` push accepts the following objects.

**event** object

When present, contains a single static value. The `event` object is optional for `consent_updated` — pushing a payload with only the `consent` object is also valid (see the **Consent-only push** variant above).

**name** string required when event is present

info

Use only static value **consent\_updated** for `event.name`.

```
name: "consent_updated"
```

**consent** object required

info

The consent state for the three categories DATA Reshape enforces. Optionally include `id` to associate the consent decision with a record identifier (useful for relaying or persisting in an audit destination).

**analytics** boolean required

info

Consent for performance monitoring, usage statistics, and service optimization.

```
analytics: true
```

**personalization** boolean required

info

Consent for tailored experiences and content customization.

```
personalization: true
```

**marketing** boolean required

info

Consent for targeted advertising, remarketing, and campaign measurement.

```
marketing: false
```

**id** string

info

Optional consent-record identifier. When present, DATA Reshape can persist or relay the consent decision under this ID — useful when you want each stored decision to be tied to a verifiable reference from your Consent Management Platform (CMP consent ID, IAB TC string hash, internal record ID, etc.). Required when the optional [audit-trail persistence](/events/consent/overview.md#Audit-trail) feature is enabled on the account.

```
id: "consent_record_abc123"
```

One push, many native events

A single Reshape consent signal can produce **one or more native consent updates per destination**, with different shapes depending on each website's destination configuration (Google Consent Mode v2 updates, Meta CAPI `data_processing_options`, TikTok `limited_data_use`, etc.).

Custom properties

Custom properties (`event.properties`, `user.properties`, `products[*].properties`) are **fully processed server-side**. On **browser-side** pixels and tags, only a subset may be available. Server-side processing can also enrich the outgoing payload with additional parameters derived from context and data quality.

## Best Practices[​](#Best-Practices "Direct link to Best Practices")

* **Push as early as possible** — for returning visitors with stored consent, push the consent state at session start, **before** any tracked event. This avoids unnecessary queueing or anonymous-pinging in restricted modes.
* **Push every change** — every time the visitor updates their consent (cookie settings, withdrawal, etc.), push the new state immediately. Reshape applies it to all subsequent events and to queued events before replay.
* **Skip the manual push when a native integration handles it** — if your CMP or Google Consent Mode v2 is auto-detected, you do not need to fire this event. Double-firing is harmless (Reshape deduplicates) but unnecessary.
* **Use the consent-only variant for state relay** — when you are not also tracking an action, omit the `event` object to keep the payload minimal.
* **Treat `id` as opaque** — it is not validated by Reshape, it is just stored/relayed. Use a stable identifier from your consent platform (CMP consent ID, IAB TC string hash, internal record ID, etc.).
* **Server-side push** — for sensitive flows (mobile webview, server-rendered banner), prefer pushing the consent state from your server via the API instead of relying on the browser. Reshape applies it the same way.


---

# Consent Overview

DATA Reshape treats user consent as the **gatekeeper** for every piece of data that flows through the platform. Consent is enforced **across all connected destinations** automatically — you do not need to write per-destination logic to honor a user's privacy choices.

## Default state: denied[​](#Default-state-denied "Direct link to Default state: denied")

By default, every visitor starts with **consent denied** for `analytics`, `personalization` and `marketing`. Tracking runs in a **GDPR-restricted mode** until DATA Reshape receives an explicit consent signal. This default-deny posture is what keeps your implementation GDPR-compliant out of the box, even before a Consent Management Platform (CMP) is wired in.

## How DATA Reshape receives consent[​](#How-DATA-Reshape-receives-consent "Direct link to How DATA Reshape receives consent")

There are three sources, listed in order of preference. You almost never need more than one:

1. **Native CMP integrations.** DATA Reshape is integrated with most major Consent Management Platforms and commerce platforms (Shopify, MerchantPro, Gomag and others). On sites where one of these is detected, Reshape **listens to the native consent signal** automatically — no manual push needed.
2. **Google Consent Mode v2 (GCMv2).** If your site already implements GCMv2 via `gtag('consent', 'update', ...)`, Reshape listens to it natively. An **anti-spoofing protection layer** validates each signal against the expected origin and timing to prevent client-side tampering from bypassing consent enforcement.
3. **Manual `consent_updated` event.** Use this only when your CMP is not auto-detected, when relaying a stored consent decision from a non-DOM source (mobile webview, SPA route guard, server-rendered banner), or when the CMP/GCMv2 sources are unavailable. See **[Consent Updated event](/events/consent/consent-updated.md)** for payload shapes.

## Operating modes (when consent is denied)[​](#Operating-modes-when-consent-is-denied "Direct link to Operating modes (when consent is denied)")

DATA Reshape exposes three configurable modes that govern what happens to events fired **before consent is granted** and what continues to happen **after an explicit deny**. The mode is set per account and dramatically affects both compliance posture and server-side processing volume. They are listed below from the **strictest** to the most permissive.

### 1. Full restriction[​](#1-Full-restriction "Direct link to 1. Full restriction")

The strictest mode. The full DATA Reshape tracking JavaScript is **not loaded** until the visitor grants consent, and **nothing is sent anywhere** — no ping, no server-side call, no destination forwarding.

* **Decision pending on the current page** — each event is captured into a **per-key in-page queue** holding the **full event payload**. Nothing leaves the browser until consent lands.
* **Consent granted on the same page** — the script loads and the queued events are **replayed in full** in their original order, so destinations receive the complete pre-consent activity from this page.
* **Explicit deny + navigation** — the tracking JS continues **not to load** and **no tracking happens at all**, not even server-side. The visitor is completely **invisible** for the rest of the session, and any previously queued events for that page are dropped.

Highest legal protection in jurisdictions with strict pre-consent tracking rules; zero post-deny visibility on any page.

### 2. Anonymous ping (with optional Replay)[​](#2-Anonymous-ping-with-optional-Replay "Direct link to 2. Anonymous ping (with optional Replay)")

The JS loads from the start but operates in restricted mode until consent. **Recommended as the optimal balance** for most accounts.

* **Decision pending** — each event is sent as a **stripped-down anonymous ping** (no PII, no cookies, no fingerprint), giving you aggregate volume and a basic shape of the funnel. Full payloads are held in a **per-page in-memory queue**.
* **Consent granted on the same page** — full versions are **replayed** and deduplicated against the anonymous pings so destinations receive enriched events in the correct order.
* **Explicit deny + navigation** — the per-page queue is dropped, but **anonymous pings keep flowing** for each subsequent page, so you still get aggregate volume and funnel shape for the denied portion of the session. The visitor is **not invisible**.

Server-side pings for unsupported destinations

Some destinations (server-only APIs, destinations that reject low-fidelity browser hits, etc.) **do not support browser-side anonymous pings**. For those, DATA Reshape sends the pre-consent ping **server-side only**, so the destination still receives an event in a shape it can accept. This routing is automatic — you do not need to configure it per destination.

### 3. Server-side queue + Replay[​](#3-Server-side-queue--Replay "Direct link to 3. Server-side queue + Replay")

Events are accepted from the start and held in a **persistent server-side queue** for a configurable retention window (or until consent is granted, whichever comes first).

* **Cross-page and cross-session** — unlike the in-page queues in modes 1 and 2, this queue **survives page navigation** and even browser-close within the retention window.
* **Consent granted at any time inside the window** — the entire pre-consent journey is replayed in order with full deduplication on the **server-side path**. Practically **no server-side data is lost**.

Browser-side pixels cannot be replayed

While consent is **denied or still pending**, browser-side pixel calls (`fbq`, `ttq`, `gtag`, etc.) **are not fired** in the visitor's browser, even though the event is being queued server-side. Those browser pixel firings are tied to the visitor's session and **cannot be recovered later** — once the visitor leaves without consent, the browser-context signals (cookies set by the pixel, third-party ad IDs, browser fingerprint at that moment) are gone. Replay on consent will deliver the event **server-side only**, which is what most ad platforms expect via CAPI / Events API anyway — but if a destination relies specifically on the browser-side pixel for full attribution, that portion is lost.

On request + significant cost

This mode is available **on request** only and introduces **significant additional processing and storage costs** — every pre-consent event consumes server-side queue capacity for the full retention window, even if consent is never granted. Pick this only if losing pre-consent journey data is genuinely unacceptable for your use case and you are prepared for the cost impact.

### Choosing a mode[​](#Choosing-a-mode "Direct link to Choosing a mode")

The choice depends on your jurisdiction, your appetite for processing cost, and the analytics fidelity you need. Modes with **Replay** can noticeably increase request volume against your account quota — pick the one that matches your compliance and budget.

Per-destination parameter restrictions (any mode)

Independently of the operating mode chosen above, **each destination can be configured to receive only a subset of the available parameters** — for example, an analytics destination can be restricted to receive only context and product data while a marketing destination receives the full payload including hashed user identifiers. This is a **per-destination configuration** and applies in all three modes, both pre-consent (pings/replays) and post-consent (full forwarding). Use it to enforce data-minimization principles destination by destination, even when consent allows the broader category.

## Per-destination consent enforcement[​](#Per-destination-consent-enforcement "Direct link to Per-destination consent enforcement")

Each connected destination is configured with the consent categories it requires (`analytics`, `personalization`, `marketing`). When an event is processed, Reshape forwards it **only to the destinations whose required consent categories are all granted**. The same event can reach some destinations and be blocked from others — this is normal and intentional, and it's what lets a partial-consent user (e.g. accepted analytics but not marketing) still feed your analytics stack without leaking to ad platforms.

## Consent change mid-session[​](#Consent-change-mid-session "Direct link to Consent change mid-session")

If the visitor changes consent mid-session (opens cookie settings, revokes `marketing`, etc.), Reshape applies the new state **immediately** for all subsequent events. For events held in any replay-capable mode (in-page queue in modes 1 and 2, server-side queue in mode 3), the new state is also applied **before replay** — so a withdrawn consent will not cause queued events to leak to destinations that no longer have permission.

## Audit trail[​](#Audit-trail "Direct link to Audit trail")

DATA Reshape is **not a Consent Management Platform** — your CMP (or commerce platform integration) remains the source of truth for the consent record itself. For organizations that need an internal audit trail of consent decisions alongside their tracking data, DATA Reshape can persist each received consent signal with a timestamp and the originating source (native CMP plugin, GCMv2, manual `consent_updated` event, etc.), available for **GDPR compliance audits** and for responding to Data Subject Access Requests (DSARs) without having to instrument extra retrieval logic on your side.

This audit-trail persistence has two requirements:

* **You must push a `consent.id`** with every consent signal (your CMP consent record ID, IAB TC string hash, or any stable internal identifier) so each stored decision is tied to a verifiable reference. See the [`id` field](/events/consent/consent-updated.md) on the `consent_updated` event.
* The feature is **paid / on request** — it consumes long-term storage and is not part of the default tracking flow. Contact us to enable it on your account.

Without `consent.id` and without the feature enabled, DATA Reshape still enforces consent in real time (default-denied, per-destination gating, mid-session updates) but does **not** retain a queryable historical record — refer back to your CMP for that.


---

# Billing Address Added

Fire the **`billing_address_added`** event when a visitor adds or confirms billing information during checkout. This is a checkout-step signal that identifies users who have committed billing details but not yet completed payment.

Fire the event once when the billing address is confirmed. The `user` object should contain the billing address fields (`country`, `region`, `city`, `street`, `postal_code`) as entered by the visitor.

This event is the DATA Reshape equivalent of the standard billing-info event in every major advertising and analytics platform — push it once and Reshape fans it out to every connected destination with the correct platform-specific name and field mapping, so you do not need to fire `gtag`, `fbq`, `ttq` or other tracking function calls in parallel.

* **Google Analytics 4** — custom event (no standard GA4 event for billing-address-added; mapped as custom).
* **Meta, TikTok** — no dedicated standard event; Reshape can send a custom CamelCase event when connected.
* **Other connected destinations** — mapped automatically based on each destination's native schema.

One push, many native events

A single Reshape event can produce **one or more native events per destination**, with different characteristics depending on each website's destination configuration (active pixels, server endpoints, event-mapping rules).

## Complete Reference[​](#Complete-Reference "Direct link to Complete Reference")

The `billing_address_added` event accepts the following objects and fields. Required fields must always be present in the payload — everything else is optional but strongly recommended.

**event** object required

**name** string required

info

Use only static value **billing\_address\_added** for `event.name`.

```
name: "billing_address_added"
```

**value** number required

info

Current cart total at this checkout step.

```
value: 249.99
```

**currency** string required

info

Currency code, ISO 4217 three-letter format.

```
currency: "USD"
```

**exchange\_rate** number

info

Default is 1.

```
exchange_rate: 1
```

**id** string

info

Optional event identifier.

```
id: "evt_billing_abc123"
```

**context** object

info

[**View complete Context Object documentation**](/objects/context-web.md)

**url** string required-if-applicable

info

Collected automatically for standard websites. Required only for SPA applications where URL changes don't trigger automatic page context updates.

```
url:"https://example.com/products/prod_abc123?utm_source=example"
```

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

Array containing every product currently in the cart. [**View complete Product Object documentation**](/objects/product.md)

**products\[0]** object required

**id** string required

info

Unique product identifier in your system.

```
id: "prod_abc123"
```

**parent\_id** string recommended

info

Parent product ID for variants or child products. Defaults to `id` if not provided.

```
parent_id: "prod_parent_xyz789"
```

**name** string required

info

Product name or title displayed to users.

```
name: "Example Product Name"
```

**parent\_name** string

info

Parent product name for variants or child products. Defaults to `name` if not provided.

```
parent_name: "Example Parent Product Name"
```

**price\_base** number required

info

Original or base price before discounts. Always equal to or greater than `price`.

```
price_base: 299.99
```

**price** number required

info

Current selling price after discounts. Always equal to or less than `price_base`.

```
price: 249.99
```

**tax\_included** boolean required

info

Whether the price includes taxes. Defaults to `true` if not provided.

```
tax_included: true
```

**tax\_percent** number required

info

Tax percentage applied to the product (0-50). If not provided, the site default tax rate will be used (generally the standard rate of the country).

```
tax_percent: 19
```

**quantity** number required

info

Quantity of this product in the context of the event. Defaults to 1 if not provided.

```
quantity: 2
```

**category** string recommended

info

Main product category name

```
category: "Example Category"
```

**sku** string

info

Product SKU (Stock Keeping Unit) for inventory tracking

```
sku: "sku_abc123"
```

**parent\_sku** string

info

Parent product SKU for variants or child products. Defaults to `sku` if not provided.

```
parent_sku: "sku_parent_xyz789"
```

**gtin** string

info

Global Trade Item Number for product identification

```
gtin: "1234567890123"
```

**mpn** string

info

Manufacturer Part Number assigned by the manufacturer

```
mpn: "MPN-EXAMPLE-001"
```

**ean** string

info

European Article Number for product barcoding

```
ean: "1234567890123"
```

**brand** string

info

Product brand or manufacturer name

```
brand: "Example Brand"
```

**type** string

info

Product type. Free-form string (e.g. "simple", "variable", "bundle", "subscription").

```
type: "simple"
```

**stock\_status** boolean | number | string recommended

info

Product availability, accepted in any of these forms:

* **boolean** — `true` (in stock) / `false` (out of stock)
* **number** — `> 0` = in stock, `0` or negative = out of stock
* **string** — the following (case-insensitive) are treated as **out of stock**: `0`, `no`, `nu`, `false`, `out of stock`, `sold out`, `unavailable`, `indisponibil`, `fara stoc`, `stoc epuizat`.

Any other value is treated as **in stock**. Defaults to `true` (in stock) if not provided.

```
stock_status: true
```

**stock\_location** string

info

Physical location or warehouse where product is stored

```
stock_location: "Example Warehouse"
```

**created\_at** number

info

Timestamp when product was added to inventory (milliseconds)

```
created_at: 1748505040077
```

**url** string

info

Direct URL to the product page

```
url: "https://example.com/products/prod_abc123"
```

**parent\_url** string

info

URL to the parent product page (for variants)

```
parent_url: "https://example.com/products/prod_parent_xyz789"
```

**image** string

info

Main product image URL

```
image: "https://example.com/cdn/prod_abc123-main.jpg"
```

**images** array

info

Array of additional product image URLs

```
images: [
  "https://example.com/cdn/prod_abc123-1.jpg",
  "https://example.com/cdn/prod_abc123-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: "Example Category", id: "cat_abc123" },
  { name: "Example Subcategory", id: "cat_xyz789" }
]
```

**coupons** array

info

Array of product-level coupons applied to this product. [**View complete Coupon Object documentation**](/objects/coupon.md)

**coupons\[0]** (object) - `required`

**name** string required

info

Coupon name or code.

```
name: "EXAMPLE_COUPON"
```

**value** number recommended

info

Coupon discount value.

```
value: 123.99
```

**tax\_included** boolean recommended

info

Whether coupon value includes taxes

```
tax_included: true
```

**tax\_percent** number recommended

info

Tax percentage for the coupon

```
tax_percent: 21
```

**id** string

info

Coupon internal identifier.

```
id: "cpn_abc123"
```

**type** string

info

Coupon type. Free-form string, use consistent naming (e.g. "LOYALTY", "SEASONAL", "FIRST\_ORDER", "SHIPPING").

```
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. Free-form key-value object. Use properties that match your product catalog and business needs.

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.

* IT & C
* Fashion
* Deco

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

```
properties: {
  color: ["black", "white"],
  size: "M",
  material: "cotton",
  fit: "regular", 
  season: "summer",
  collection: "2024_spring",
  care_instructions: "machine_wash"
}
```

```
properties: {
  color: ["natural", "oak"],
  dimensions: "120x80x75cm",
  material: ["wood", "metal"],
  style: "modern",
  room_type: ["living_room", "office"],
  assembly_required: "true"
}
```

**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 required

info

The `user` object should contain the entered billing address — `country`, `region`, `city`, `street`, `postal_code` — plus contact details when available. These fields drive Advanced Matching in Meta, Enhanced Conversions in Google Ads, and equivalent profile/identity updates in other connected destinations. [**View complete User Object documentation**](/objects/user.md)

**id** string recommended

info

Unique customer identifier in your system.

```
id: "cust_abc123"
```

**email** string recommended

info

Customer email address in plaintext. Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.

```
email: "example.customer@example.com"
```

**phone** string recommended

info

Customer phone number in E.164 format (plaintext). Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.

```
phone: "+10000000000"
```

**first\_name** string recommended

info

Customer first name

```
first_name: "Example First Name"
```

**last\_name** string recommended

info

Customer last name

```
last_name: "Example Last Name"
```

**country** string

info

Country name or ISO country code

```
country: "US"
```

**region** string recommended

info

State, province, or region name

```
region: "Example Region"
```

**city** string recommended

info

City or locality name

```
city: "Example City"
```

**street** string

info

Street address including number

```
street: "123 Sample Street"
```

**postal\_code** string

info

Postal code or ZIP code

```
postal_code: "00000"
```

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

* E-commerce Customer
* B2B Lead/Customer
* Subscription Service
* Content Platform

```
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"
}
```

```
properties: {
  company_size: "enterprise",
  industry: "fintech",
  job_title: "marketing_director",
  decision_maker: "true",
  budget_range: "50000-100000",
  lead_source: ["linkedin", "webinar"],
  qualification_status: "qualified",
  sales_stage: "proposal"
}
```

```
properties: {
  subscription_tier: "premium",
  billing_cycle: "annual",
  feature_usage: ["analytics", "reporting", "api"],
  trial_user: "false",
  renewal_date: "2025-06-30",
  support_level: "priority",
  usage_frequency: "daily"
}
```

```
properties: {
  content_preferences: ["technology", "business"],
  engagement_level: "high",
  newsletter_subscriber: "true",
  social_media_follower: "true",
  content_consumption: "premium",
  device_preference: ["mobile", "desktop"],
  timezone: "Example/Timezone"
}
```

## Examples[​](#Examples "Direct link to Examples")

The examples below show how to push `billing_address_added` for four common e-commerce niches — **Fashion**, **Electronics**, **Beauty** and **Home & Deco** — each with representative product attributes, plus an additional **Minimal** tab with only the required fields.

* Fashion
* Electronics
* Beauty
* Home & Deco
* Minimal

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "billing_address_added",
    "value": 129.98,
    "currency": "USD",
    "exchange_rate": 1
  },
  "context": {
    "url": "https://example.com/checkout/billing",
    "page_type": "checkout",
    "environment": "prod"
  },
  "products": [
    {
      "id": "prod_tshirt_navy_m",
      "parent_id": "prod_tshirt_model",
      "name": "Example Cotton T-Shirt - Navy / M",
      "parent_name": "Example Cotton T-Shirt",
      "price_base": 59.99,
      "price": 49.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Apparel",
      "sku": "sku_tshirt_navy_m",
      "brand": "Example Brand",
      "type": "variable",
      "properties": { "variant": "Navy / M", "color": "navy", "size": "M" }
    },
    {
      "id": "prod_jeans_blue_32",
      "parent_id": "prod_jeans_model",
      "name": "Example Slim Jeans - Indigo / 32",
      "parent_name": "Example Slim Jeans",
      "price_base": 89.99,
      "price": 79.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Apparel",
      "sku": "sku_jeans_blue_32",
      "brand": "Example Brand",
      "type": "variable",
      "properties": { "variant": "Indigo / 32", "color": "indigo", "size": "32" }
    }
  ],
  "user": {
    "id": "cust_abc123",
    "email": "example.customer@example.com",
    "phone": "+10000000000",
    "first_name": "Example First Name",
    "last_name": "Example Last Name",
    "country": "US",
    "region": "Example Region",
    "city": "Example City",
    "street": "123 Sample Street",
    "postal_code": "00000"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "billing_address_added",
    "value": 1349.98,
    "currency": "USD",
    "exchange_rate": 1
  },
  "context": {
    "url": "https://example.com/checkout/billing",
    "page_type": "checkout",
    "environment": "prod"
  },
  "products": [
    {
      "id": "prod_headphones_black",
      "parent_id": "prod_headphones_model",
      "name": "Example Wireless Headphones - Black",
      "parent_name": "Example Wireless Headphones",
      "price_base": 299.99,
      "price": 249.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Electronics",
      "sku": "sku_headphones_black",
      "brand": "Example Brand",
      "type": "variable",
      "properties": { "variant": "Black", "color": "black" }
    },
    {
      "id": "prod_laptop_15_512",
      "parent_id": "prod_laptop_model",
      "name": "Example Laptop 15 - 512GB / Silver",
      "parent_name": "Example Laptop 15",
      "price_base": 1299.99,
      "price": 1099.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Electronics",
      "sku": "sku_laptop_15_512",
      "brand": "Example Brand",
      "type": "variable",
      "properties": { "variant": "512GB / Silver", "storage_gb": 512 }
    }
  ],
  "user": {
    "id": "cust_abc123",
    "email": "example.customer@example.com",
    "phone": "+10000000000",
    "first_name": "Example First Name",
    "last_name": "Example Last Name",
    "country": "US",
    "region": "Example Region",
    "city": "Example City",
    "street": "123 Sample Street",
    "postal_code": "00000"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "billing_address_added",
    "value": 74.97,
    "currency": "USD",
    "exchange_rate": 1
  },
  "context": {
    "url": "https://example.com/checkout/billing",
    "page_type": "checkout",
    "environment": "prod"
  },
  "products": [
    {
      "id": "prod_foundation_shade04",
      "parent_id": "prod_foundation_model",
      "name": "Example Liquid Foundation - Shade 04 / 30ml",
      "parent_name": "Example Liquid Foundation",
      "price_base": 39.99,
      "price": 34.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Beauty",
      "sku": "sku_foundation_shade04_30ml",
      "brand": "Example Brand",
      "type": "variable",
      "properties": { "variant": "Shade 04 / 30ml", "shade": "shade_04_warm_beige" }
    },
    {
      "id": "prod_lipstick_rose",
      "parent_id": "prod_lipstick_model",
      "name": "Example Matte Lipstick - Rose Petal",
      "parent_name": "Example Matte Lipstick",
      "price_base": 24.99,
      "price": 19.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 2,
      "category": "Beauty",
      "sku": "sku_lipstick_rose",
      "brand": "Example Brand",
      "type": "variable",
      "properties": { "variant": "Rose Petal", "shade": "rose_petal" }
    }
  ],
  "user": {
    "id": "cust_abc123",
    "email": "example.customer@example.com",
    "phone": "+10000000000",
    "first_name": "Example First Name",
    "last_name": "Example Last Name",
    "country": "US",
    "region": "Example Region",
    "city": "Example City",
    "street": "123 Sample Street",
    "postal_code": "00000"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "billing_address_added",
    "value": 389.98,
    "currency": "USD",
    "exchange_rate": 1
  },
  "context": {
    "url": "https://example.com/checkout/billing",
    "page_type": "checkout",
    "environment": "prod"
  },
  "products": [
    {
      "id": "prod_lamp_brass",
      "parent_id": "prod_lamp_model",
      "name": "Example Floor Lamp - Brass",
      "parent_name": "Example Floor Lamp",
      "price_base": 229.99,
      "price": 189.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Home & Living",
      "sku": "sku_lamp_brass",
      "brand": "Example Brand",
      "type": "variable",
      "properties": { "variant": "Brass", "color": "brass" }
    },
    {
      "id": "prod_rug_natural_160",
      "parent_id": "prod_rug_model",
      "name": "Example Wool Rug - Natural / 160x230",
      "parent_name": "Example Wool Rug",
      "price_base": 249.99,
      "price": 199.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Home & Living",
      "sku": "sku_rug_natural_160",
      "brand": "Example Brand",
      "type": "variable",
      "properties": { "variant": "Natural / 160x230", "material": "wool" }
    }
  ],
  "user": {
    "id": "cust_abc123",
    "email": "example.customer@example.com",
    "phone": "+10000000000",
    "first_name": "Example First Name",
    "last_name": "Example Last Name",
    "country": "US",
    "region": "Example Region",
    "city": "Example City",
    "street": "123 Sample Street",
    "postal_code": "00000"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "billing_address_added",
    "value": 249.99,
    "currency": "USD"
  },
  "products": [
    {
      "id": "prod_abc123",
      "name": "Example Product Name",
      "brand": "Example Brand",
      "price_base": 299.99,
      "price": 249.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Example Category"
    }
  ],
  "user": {
    "email": "example.customer@example.com",
    "country": "US",
    "city": "Example City",
    "postal_code": "00000"
  }
});
```

Custom properties

Custom properties (`event.properties`, `user.properties`, `products[*].properties`) are **fully processed server-side**. On **browser-side** pixels and tags, only a subset may be available. Server-side processing can also enrich the outgoing payload with additional parameters derived from context and data quality.

## Best Practices[​](#Best-Practices "Direct link to Best Practices")

* **Fire once per confirmed address** — not on every keystroke. Wait until the user submits the billing form.
* **Always include the `user` object** with billing-address fields filled in — this is what makes the event valuable for Advanced Matching, Enhanced Conversions and equivalent flows in other connected destinations.
* **Use plaintext email/phone** — DATA Reshape normalizes and hashes automatically before forwarding to destinations.
* **Keep cart consistency** — `products[]` must reflect the current cart at this checkout step.


---

# Cart Viewed

Fire the **`cart_viewed`** event when a visitor lands on the cart page or opens a cart drawer/modal with the full list of items they intend to purchase. This event is a high-intent mid-funnel signal — visitors who view their cart are statistically much more likely to convert, which makes them a prime audience for retargeting and abandonment recovery flows.

Fire it once per cart page view, with `products[]` reflecting the current state of the cart (every line item with its current quantity). If the visitor stays on the cart page and modifies quantities or removes items, do not re-fire `cart_viewed` — use `product_added_to_cart` and `product_removed_from_cart` for those individual actions.

This event is the DATA Reshape equivalent of the standard view-cart event in every major advertising and analytics platform — push it once and Reshape fans it out to every connected destination with the correct platform-specific name and field mapping, so you do not need to fire `gtag`, `fbq`, `ttq` or other tracking function calls in parallel.

* **Google Analytics 4** — `view_cart` (with `items`, `value`, `currency`).
* **Google Ads** — dynamic remarketing cart-view signal, used for cart-abandonment audiences.
* **Meta Pixel / Meta Conversions API** — `ViewContent` with cart context (Meta has no dedicated `ViewCart`).
* **TikTok Pixel / TikTok Events API** — `ViewContent` with cart context (TikTok has no dedicated `ViewCart`).
* **Other connected destinations** — mapped automatically based on each destination's native schema.

One push, many native events

A single Reshape event can produce **one or more native events per destination**, with different characteristics depending on each website's destination configuration (active pixels, server endpoints, event-mapping rules).

## Complete Reference[​](#Complete-Reference "Direct link to Complete Reference")

The `cart_viewed` event accepts the following objects and fields. Required fields must always be present in the payload — everything else is optional but strongly recommended. The `products` array must reflect the current cart at the moment of the view, with `event.value` equal to the cart total (sum of `price × quantity` across all line items).

**event** object required

**name** string required

info

Use only static value **cart\_viewed** for `event.name`. DATA Reshape maps this to `view_cart` (GA4) and `ViewContent` with cart context (Meta, TikTok) automatically.

```
name: "cart_viewed"
```

**value** number required

info

Current cart total (sum of `price × quantity` across all line items, before shipping and order-level discounts).

```
value: 249.99
```

**currency** string required

info

Currency code for all monetary values in this event, ISO 4217 three-letter format.

```
currency: "USD"
```

**exchange\_rate** number

info

Custom exchange rate for multi-currency. Default is 1.

```
exchange_rate: 1
```

**id** string

info

Optional event identifier.

```
id: "evt_cart_view_abc123"
```

**context** object

info

[**View complete Context Object documentation**](/objects/context-web.md)

**url** string required-if-applicable

info

Collected automatically for standard websites. Required only for SPA applications where URL changes don't trigger automatic page context updates.

```
url:"https://example.com/products/prod_abc123?utm_source=example"
```

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

Array containing every product currently in the cart, with `quantity` set to the cart quantity for each SKU. Use the same `id` as in `product_viewed` and `product_added_to_cart`. [**View complete Product Object documentation**](/objects/product.md)

**products\[0]** object required

**id** string required

info

Unique product identifier in your system.

```
id: "prod_abc123"
```

**parent\_id** string recommended

info

Parent product ID for variants or child products. Defaults to `id` if not provided.

```
parent_id: "prod_parent_xyz789"
```

**name** string required

info

Product name or title displayed to users.

```
name: "Example Product Name"
```

**parent\_name** string

info

Parent product name for variants or child products. Defaults to `name` if not provided.

```
parent_name: "Example Parent Product Name"
```

**price\_base** number required

info

Original or base price before discounts. Always equal to or greater than `price`.

```
price_base: 299.99
```

**price** number required

info

Current selling price after discounts. Always equal to or less than `price_base`.

```
price: 249.99
```

**tax\_included** boolean required

info

Whether the price includes taxes. Defaults to `true` if not provided.

```
tax_included: true
```

**tax\_percent** number required

info

Tax percentage applied to the product (0-50). If not provided, the site default tax rate will be used (generally the standard rate of the country).

```
tax_percent: 19
```

**quantity** number required

info

Quantity of this product in the context of the event. Defaults to 1 if not provided.

```
quantity: 2
```

**category** string recommended

info

Main product category name

```
category: "Example Category"
```

**sku** string

info

Product SKU (Stock Keeping Unit) for inventory tracking

```
sku: "sku_abc123"
```

**parent\_sku** string

info

Parent product SKU for variants or child products. Defaults to `sku` if not provided.

```
parent_sku: "sku_parent_xyz789"
```

**gtin** string

info

Global Trade Item Number for product identification

```
gtin: "1234567890123"
```

**mpn** string

info

Manufacturer Part Number assigned by the manufacturer

```
mpn: "MPN-EXAMPLE-001"
```

**ean** string

info

European Article Number for product barcoding

```
ean: "1234567890123"
```

**brand** string

info

Product brand or manufacturer name

```
brand: "Example Brand"
```

**type** string

info

Product type. Free-form string (e.g. "simple", "variable", "bundle", "subscription").

```
type: "simple"
```

**stock\_status** boolean | number | string recommended

info

Product availability, accepted in any of these forms:

* **boolean** — `true` (in stock) / `false` (out of stock)
* **number** — `> 0` = in stock, `0` or negative = out of stock
* **string** — the following (case-insensitive) are treated as **out of stock**: `0`, `no`, `nu`, `false`, `out of stock`, `sold out`, `unavailable`, `indisponibil`, `fara stoc`, `stoc epuizat`.

Any other value is treated as **in stock**. Defaults to `true` (in stock) if not provided.

```
stock_status: true
```

**stock\_location** string

info

Physical location or warehouse where product is stored

```
stock_location: "Example Warehouse"
```

**created\_at** number

info

Timestamp when product was added to inventory (milliseconds)

```
created_at: 1748505040077
```

**url** string

info

Direct URL to the product page

```
url: "https://example.com/products/prod_abc123"
```

**parent\_url** string

info

URL to the parent product page (for variants)

```
parent_url: "https://example.com/products/prod_parent_xyz789"
```

**image** string

info

Main product image URL

```
image: "https://example.com/cdn/prod_abc123-main.jpg"
```

**images** array

info

Array of additional product image URLs

```
images: [
  "https://example.com/cdn/prod_abc123-1.jpg",
  "https://example.com/cdn/prod_abc123-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: "Example Category", id: "cat_abc123" },
  { name: "Example Subcategory", id: "cat_xyz789" }
]
```

**coupons** array

info

Array of product-level coupons applied to this product. [**View complete Coupon Object documentation**](/objects/coupon.md)

**coupons\[0]** (object) - `required`

**name** string required

info

Coupon name or code.

```
name: "EXAMPLE_COUPON"
```

**value** number recommended

info

Coupon discount value.

```
value: 123.99
```

**tax\_included** boolean recommended

info

Whether coupon value includes taxes

```
tax_included: true
```

**tax\_percent** number recommended

info

Tax percentage for the coupon

```
tax_percent: 21
```

**id** string

info

Coupon internal identifier.

```
id: "cpn_abc123"
```

**type** string

info

Coupon type. Free-form string, use consistent naming (e.g. "LOYALTY", "SEASONAL", "FIRST\_ORDER", "SHIPPING").

```
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. Free-form key-value object. Use properties that match your product catalog and business needs.

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.

* IT & C
* Fashion
* Deco

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

```
properties: {
  color: ["black", "white"],
  size: "M",
  material: "cotton",
  fit: "regular", 
  season: "summer",
  collection: "2024_spring",
  care_instructions: "machine_wash"
}
```

```
properties: {
  color: ["natural", "oak"],
  dimensions: "120x80x75cm",
  material: ["wood", "metal"],
  style: "modern",
  room_type: ["living_room", "office"],
  assembly_required: "true"
}
```

**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**](/objects/user.md)

**id** string recommended

info

Unique customer identifier in your system.

```
id: "cust_abc123"
```

**email** string recommended

info

Customer email address in plaintext. Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.

```
email: "example.customer@example.com"
```

**phone** string recommended

info

Customer phone number in E.164 format (plaintext). Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.

```
phone: "+10000000000"
```

**first\_name** string recommended

info

Customer first name

```
first_name: "Example First Name"
```

**last\_name** string recommended

info

Customer last name

```
last_name: "Example Last Name"
```

**country** string

info

Country name or ISO country code

```
country: "US"
```

**region** string recommended

info

State, province, or region name

```
region: "Example Region"
```

**city** string recommended

info

City or locality name

```
city: "Example City"
```

**street** string

info

Street address including number

```
street: "123 Sample Street"
```

**postal\_code** string

info

Postal code or ZIP code

```
postal_code: "00000"
```

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

* E-commerce Customer
* B2B Lead/Customer
* Subscription Service
* Content Platform

```
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"
}
```

```
properties: {
  company_size: "enterprise",
  industry: "fintech",
  job_title: "marketing_director",
  decision_maker: "true",
  budget_range: "50000-100000",
  lead_source: ["linkedin", "webinar"],
  qualification_status: "qualified",
  sales_stage: "proposal"
}
```

```
properties: {
  subscription_tier: "premium",
  billing_cycle: "annual",
  feature_usage: ["analytics", "reporting", "api"],
  trial_user: "false",
  renewal_date: "2025-06-30",
  support_level: "priority",
  usage_frequency: "daily"
}
```

```
properties: {
  content_preferences: ["technology", "business"],
  engagement_level: "high",
  newsletter_subscriber: "true",
  social_media_follower: "true",
  content_consumption: "premium",
  device_preference: ["mobile", "desktop"],
  timezone: "Example/Timezone"
}
```

## Examples[​](#Examples "Direct link to Examples")

The examples below show how to push `cart_viewed` for four common e-commerce niches — **Fashion**, **Electronics**, **Beauty** and **Home & Deco** — each with representative product attributes for that niche, plus an additional **Minimal** tab with only the required fields.

* Fashion
* Electronics
* Beauty
* Home & Deco
* Minimal

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "cart_viewed",
    "value": 129.98,
    "currency": "USD",
    "exchange_rate": 1
  },
  "context": {
    "url": "https://example.com/cart",
    "page_type": "cart",
    "environment": "prod"
  },
  "products": [
    {
      "id": "prod_tshirt_navy_m",
      "parent_id": "prod_tshirt_model",
      "name": "Example Cotton T-Shirt - Navy / M",
      "parent_name": "Example Cotton T-Shirt",
      "price_base": 59.99,
      "price": 49.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Apparel",
      "sku": "sku_tshirt_navy_m",
      "parent_sku": "sku_tshirt_model",
      "brand": "Example Brand",
      "type": "variable",
      "stock_status": true,
      "url": "https://example.com/products/cotton-tshirt-navy-m",
      "image": "https://example.com/cdn/tshirt-navy-main.jpg",
      "properties": {
        "variant": "Navy / M",
        "color": "navy",
        "size": "M",
        "material": "100% cotton",
        "fit": "regular"
      }
    },
    {
      "id": "prod_jeans_blue_32",
      "parent_id": "prod_jeans_model",
      "name": "Example Slim Jeans - Indigo / 32",
      "parent_name": "Example Slim Jeans",
      "price_base": 89.99,
      "price": 79.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Apparel",
      "sku": "sku_jeans_blue_32",
      "parent_sku": "sku_jeans_model",
      "brand": "Example Brand",
      "type": "variable",
      "stock_status": true,
      "url": "https://example.com/products/slim-jeans-indigo-32",
      "image": "https://example.com/cdn/jeans-indigo.jpg",
      "properties": {
        "variant": "Indigo / 32",
        "color": "indigo",
        "size": "32",
        "fit": "slim"
      }
    }
  ],
  "user": {
    "email": "example.customer@example.com",
    "country": "US"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "cart_viewed",
    "value": 1349.98,
    "currency": "USD",
    "exchange_rate": 1
  },
  "context": {
    "url": "https://example.com/cart",
    "page_type": "cart",
    "environment": "prod"
  },
  "products": [
    {
      "id": "prod_headphones_black",
      "parent_id": "prod_headphones_model",
      "name": "Example Wireless Headphones - Black",
      "parent_name": "Example Wireless Headphones",
      "price_base": 299.99,
      "price": 249.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Electronics",
      "sku": "sku_headphones_black",
      "parent_sku": "sku_headphones_model",
      "brand": "Example Brand",
      "type": "variable",
      "stock_status": true,
      "url": "https://example.com/products/wireless-headphones-black",
      "image": "https://example.com/cdn/headphones-black-main.jpg",
      "properties": {
        "variant": "Black",
        "color": "black",
        "connectivity": ["bluetooth", "wired"]
      }
    },
    {
      "id": "prod_laptop_15_512",
      "parent_id": "prod_laptop_model",
      "name": "Example Laptop 15 - 512GB / Silver",
      "parent_name": "Example Laptop 15",
      "price_base": 1299.99,
      "price": 1099.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Electronics",
      "sku": "sku_laptop_15_512",
      "parent_sku": "sku_laptop_model",
      "brand": "Example Brand",
      "type": "variable",
      "stock_status": true,
      "url": "https://example.com/products/laptop-15-512",
      "image": "https://example.com/cdn/laptop-silver.jpg",
      "properties": {
        "variant": "512GB / Silver",
        "color": "silver",
        "storage_gb": 512,
        "memory_gb": 16
      }
    }
  ],
  "user": {
    "email": "example.customer@example.com",
    "country": "US"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "cart_viewed",
    "value": 74.97,
    "currency": "USD",
    "exchange_rate": 1
  },
  "context": {
    "url": "https://example.com/cart",
    "page_type": "cart",
    "environment": "prod"
  },
  "products": [
    {
      "id": "prod_foundation_shade04",
      "parent_id": "prod_foundation_model",
      "name": "Example Liquid Foundation - Shade 04 / 30ml",
      "parent_name": "Example Liquid Foundation",
      "price_base": 39.99,
      "price": 34.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Beauty",
      "sku": "sku_foundation_shade04_30ml",
      "parent_sku": "sku_foundation_model",
      "brand": "Example Brand",
      "type": "variable",
      "stock_status": true,
      "url": "https://example.com/products/liquid-foundation-shade-04",
      "image": "https://example.com/cdn/foundation-shade04-main.jpg",
      "properties": {
        "variant": "Shade 04 / 30ml",
        "shade": "shade_04_warm_beige",
        "volume_ml": 30,
        "finish": "matte"
      }
    },
    {
      "id": "prod_lipstick_rose",
      "parent_id": "prod_lipstick_model",
      "name": "Example Matte Lipstick - Rose Petal",
      "parent_name": "Example Matte Lipstick",
      "price_base": 24.99,
      "price": 19.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 2,
      "category": "Beauty",
      "sku": "sku_lipstick_rose",
      "parent_sku": "sku_lipstick_model",
      "brand": "Example Brand",
      "type": "variable",
      "stock_status": true,
      "url": "https://example.com/products/matte-lipstick-rose-petal",
      "image": "https://example.com/cdn/lipstick-rose.jpg",
      "properties": {
        "variant": "Rose Petal",
        "shade": "rose_petal",
        "finish": "matte"
      }
    }
  ],
  "user": {
    "email": "example.customer@example.com",
    "country": "US"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "cart_viewed",
    "value": 389.98,
    "currency": "USD",
    "exchange_rate": 1
  },
  "context": {
    "url": "https://example.com/cart",
    "page_type": "cart",
    "environment": "prod"
  },
  "products": [
    {
      "id": "prod_lamp_brass",
      "parent_id": "prod_lamp_model",
      "name": "Example Floor Lamp - Brass",
      "parent_name": "Example Floor Lamp",
      "price_base": 229.99,
      "price": 189.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Home & Living",
      "sku": "sku_lamp_brass",
      "parent_sku": "sku_lamp_model",
      "brand": "Example Brand",
      "type": "variable",
      "stock_status": true,
      "url": "https://example.com/products/floor-lamp-brass",
      "image": "https://example.com/cdn/lamp-brass-main.jpg",
      "properties": {
        "variant": "Brass",
        "color": "brass",
        "material": ["metal", "fabric"],
        "style": "mid_century"
      }
    },
    {
      "id": "prod_rug_natural_160",
      "parent_id": "prod_rug_model",
      "name": "Example Wool Rug - Natural / 160x230",
      "parent_name": "Example Wool Rug",
      "price_base": 249.99,
      "price": 199.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Home & Living",
      "sku": "sku_rug_natural_160",
      "parent_sku": "sku_rug_model",
      "brand": "Example Brand",
      "type": "variable",
      "stock_status": true,
      "url": "https://example.com/products/wool-rug-natural-160",
      "image": "https://example.com/cdn/rug-natural.jpg",
      "properties": {
        "variant": "Natural / 160x230",
        "color": "natural",
        "material": "wool",
        "style": "scandinavian"
      }
    }
  ],
  "user": {
    "email": "example.customer@example.com",
    "country": "US"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "cart_viewed",
    "value": 249.99,
    "currency": "USD"
  },
  "products": [
    {
      "id": "prod_abc123",
      "name": "Example Product Name",
      "brand": "Example Brand",
      "price_base": 299.99,
      "price": 249.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Example Category"
    }
  ]
});
```

Custom properties

Custom properties (`event.properties`, `user.properties`, `products[*].properties`) are **fully processed server-side**. On **browser-side** pixels and tags, only a subset may be available. Server-side processing can also enrich the outgoing payload with additional parameters derived from context and data quality.

## Best Practices[​](#Best-Practices "Direct link to Best Practices")

* **Fire on cart page load** — fire once when the cart page loads or the cart drawer opens, not on each cart-state update.
* **Include the full cart** — `products[]` must contain every line item with current quantities. Missing items hurt cart-abandonment audience quality.
* **`event.value` = sum of `price × quantity`** — before shipping and order-level discounts.
* **Use consistent product IDs across the funnel** — same `products[*].id` as in `product_viewed` and `product_added_to_cart`, so destinations can build proper view→cart→checkout→purchase funnels.
* **Include `user` when available** — even just an email enables high-intent audience targeting and equivalent flows in connected destinations.


---

# Checkout Completed

Fire the **`checkout_completed`** event when a visitor finalizes their purchase and the order is confirmed — typically on the order confirmation or "thank you" page, immediately after successful payment processing. This is the most important conversion event in any e-commerce funnel: it powers ROAS reporting, conversion-based bidding, lookalike audiences, post-purchase email flows, and lifetime-value attribution across every connected destination.

Do not fire `checkout_completed` if the payment is still pending or unverified (e.g. bank transfer awaiting confirmation, cash on delivery before pickup). For those cases, fire `checkout_completed` only when the order status flips to confirmed/paid. Always include a stable, unique `event.id` (your order or transaction ID) — DATA Reshape uses it for cross-destination deduplication, so the same purchase is never double-counted even if the user reloads the thank-you page.

This event is the DATA Reshape equivalent of the standard purchase/order-completed event in every major advertising and analytics platform — push it once and Reshape fans it out to every connected destination with the correct platform-specific name and field mapping, so you do not need to fire `gtag`, `fbq`, `ttq` or other tracking function calls in parallel.

* **Google Analytics 4** — `purchase` (with `transaction_id`, `items`, `value`, `currency`, `tax`, `shipping`, `coupon`).
* **Google Ads** — conversion tracking with `transaction_id`, plus dynamic remarketing signal.
* **Meta Pixel / Meta Conversions API** — `Purchase` (with `content_ids`, `contents`, `value`, `currency`, `num_items`, `order_id`).
* **TikTok Pixel / TikTok Events API** — `Purchase` (with `content_id`, `contents`, `value`, `currency`, `order_id`).
* **Other connected destinations** — mapped automatically based on each destination's native schema.

One push, many native events

A single Reshape event can produce **one or more native events per destination**, with different characteristics depending on each website's destination configuration (active pixels, server endpoints, event-mapping rules).

Required: event.id

This event requires a unique `event.id` (your order or transaction ID). DATA Reshape uses it for deduplication across destinations — events with duplicate IDs are silently dropped, so the same purchase is never reported twice.

## Complete Reference[​](#Complete-Reference "Direct link to Complete Reference")

The `checkout_completed` event accepts the following objects and fields. Required fields must always be present in the payload — everything else is optional but strongly recommended, because richer payloads produce better attribution, more accurate conversion-value optimization, and better-quality offline conversion uploads. The `products` array must contain every line item in the order; the `shipping` and `payments` arrays must reflect the actual shipping methods and payment instruments used. The `user` object enables Advanced Matching for Meta, Enhanced Conversions for Google Ads, and Advanced Matching for TikTok.

**event** object required

**name** string required

info

Use only static value **checkout\_completed** for `event.name`. DATA Reshape maps this to `purchase` (GA4, Google Ads), `Purchase` (Meta), and `Purchase` (TikTok) automatically.

```
name: "checkout_completed"
```

**value** number required

info

Final total order amount, including all line items, shipping, taxes, and discounts. This is the value used by every destination for ROAS calculation and conversion-value bidding.

Canonical rule — event.value for checkout\_completed

`event.value` MUST always equal **products + shipping + any other costs − order-level coupons, with tax INCLUDED**. This exact composition is a hard contract: the framework relies on it to correctly derive tax-excluded and shipping-excluded values per destination (e.g. GA4 `value` overrides, Google Ads conversion value). If your integration sends anything else here (net values, product-only totals, tax-excluded amounts), destination values will be wrong — fix the integration, never expect the framework to compensate. Note this differs from `order_canceled`, where `event.value` contains **only** the canceled/refunded products (no shipping).

```
value: 299.99
```

**currency** string required

info

Currency code for all monetary values in this event (ISO 4217). Can be overridden per nested object when items are sold in different currencies.

```
currency: "USD"
```

**exchange\_rate** number

info

Custom exchange rate for multi-currency reporting. Default is 1.

```
exchange_rate: 1
```

**id** string required

info

Unique order or transaction ID from your system. Required for cross-destination deduplication — events with duplicate IDs are silently dropped.

```
id: "ord_abc123"
```

**context** object

info

[**View complete Context Object documentation**](/objects/context-web.md)

**url** string required-if-applicable

info

Collected automatically for standard websites. Required only for SPA applications where URL changes don't trigger automatic page context updates.

```
url:"https://example.com/products/prod_abc123?utm_source=example"
```

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

Array containing every line item in the order. This is what populates the `items` array in GA4 `purchase`, the `contents` array in Meta `Purchase` and TikTok `Purchase`, and the per-item product events in other connected destinations. [**View complete Product Object documentation**](/objects/product.md)

**products\[0]** object required

**id** string required

info

Unique product identifier in your system.

```
id: "prod_abc123"
```

**parent\_id** string recommended

info

Parent product ID for variants or child products. Defaults to `id` if not provided.

```
parent_id: "prod_parent_xyz789"
```

**name** string required

info

Product name or title displayed to users.

```
name: "Example Product Name"
```

**parent\_name** string

info

Parent product name for variants or child products. Defaults to `name` if not provided.

```
parent_name: "Example Parent Product Name"
```

**price\_base** number required

info

Original or base price before discounts. Always equal to or greater than `price`.

```
price_base: 299.99
```

**price** number required

info

Current selling price after discounts. Always equal to or less than `price_base`.

```
price: 249.99
```

**tax\_included** boolean required

info

Whether the price includes taxes. Defaults to `true` if not provided.

```
tax_included: true
```

**tax\_percent** number required

info

Tax percentage applied to the product (0-50). If not provided, the site default tax rate will be used (generally the standard rate of the country).

```
tax_percent: 19
```

**quantity** number required

info

Quantity of this product in the context of the event. Defaults to 1 if not provided.

```
quantity: 2
```

**category** string recommended

info

Main product category name

```
category: "Example Category"
```

**sku** string

info

Product SKU (Stock Keeping Unit) for inventory tracking

```
sku: "sku_abc123"
```

**parent\_sku** string

info

Parent product SKU for variants or child products. Defaults to `sku` if not provided.

```
parent_sku: "sku_parent_xyz789"
```

**gtin** string

info

Global Trade Item Number for product identification

```
gtin: "1234567890123"
```

**mpn** string

info

Manufacturer Part Number assigned by the manufacturer

```
mpn: "MPN-EXAMPLE-001"
```

**ean** string

info

European Article Number for product barcoding

```
ean: "1234567890123"
```

**brand** string

info

Product brand or manufacturer name

```
brand: "Example Brand"
```

**type** string

info

Product type. Free-form string (e.g. "simple", "variable", "bundle", "subscription").

```
type: "simple"
```

**stock\_status** boolean | number | string recommended

info

Product availability, accepted in any of these forms:

* **boolean** — `true` (in stock) / `false` (out of stock)
* **number** — `> 0` = in stock, `0` or negative = out of stock
* **string** — the following (case-insensitive) are treated as **out of stock**: `0`, `no`, `nu`, `false`, `out of stock`, `sold out`, `unavailable`, `indisponibil`, `fara stoc`, `stoc epuizat`.

Any other value is treated as **in stock**. Defaults to `true` (in stock) if not provided.

```
stock_status: true
```

**stock\_location** string

info

Physical location or warehouse where product is stored

```
stock_location: "Example Warehouse"
```

**created\_at** number

info

Timestamp when product was added to inventory (milliseconds)

```
created_at: 1748505040077
```

**url** string

info

Direct URL to the product page

```
url: "https://example.com/products/prod_abc123"
```

**parent\_url** string

info

URL to the parent product page (for variants)

```
parent_url: "https://example.com/products/prod_parent_xyz789"
```

**image** string

info

Main product image URL

```
image: "https://example.com/cdn/prod_abc123-main.jpg"
```

**images** array

info

Array of additional product image URLs

```
images: [
  "https://example.com/cdn/prod_abc123-1.jpg",
  "https://example.com/cdn/prod_abc123-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: "Example Category", id: "cat_abc123" },
  { name: "Example Subcategory", id: "cat_xyz789" }
]
```

**coupons** array

info

Array of product-level coupons applied to this product. [**View complete Coupon Object documentation**](/objects/coupon.md)

**coupons\[0]** (object) - `required`

**name** string required

info

Coupon name or code.

```
name: "EXAMPLE_COUPON"
```

**value** number recommended

info

Coupon discount value.

```
value: 123.99
```

**tax\_included** boolean recommended

info

Whether coupon value includes taxes

```
tax_included: true
```

**tax\_percent** number recommended

info

Tax percentage for the coupon

```
tax_percent: 21
```

**id** string

info

Coupon internal identifier.

```
id: "cpn_abc123"
```

**type** string

info

Coupon type. Free-form string, use consistent naming (e.g. "LOYALTY", "SEASONAL", "FIRST\_ORDER", "SHIPPING").

```
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. Free-form key-value object. Use properties that match your product catalog and business needs.

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.

* IT & C
* Fashion
* Deco

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

```
properties: {
  color: ["black", "white"],
  size: "M",
  material: "cotton",
  fit: "regular", 
  season: "summer",
  collection: "2024_spring",
  care_instructions: "machine_wash"
}
```

```
properties: {
  color: ["natural", "oak"],
  dimensions: "120x80x75cm",
  material: ["wood", "metal"],
  style: "modern",
  room_type: ["living_room", "office"],
  assembly_required: "true"
}
```

**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
```

**shipping** array required

info

Array of shipping methods used for the order. Used to compute `shipping` in GA4 `purchase` and per-destination shipping breakdowns. [**View complete Shipping Object documentation**](/objects/shipping.md)

**shipping\[0]** object required

**name** string required

info

Shipping method name

```
name: "Example Shipping Method"
```

**value** number required

info

Shipping cost value

```
value: 12.99
```

**tax\_included** boolean recommended

info

Whether shipping cost includes taxes

```
tax_included: true
```

**tax\_percent** number recommended

info

Tax percentage for shipping (0-50)

```
tax_percent: 19
```

**id** string

info

Shipping method identifier.

```
id: "shp_abc123"
```

**type** string

info

Shipping type. Free-form string, use consistent naming (e.g. "standard", "express", "next\_day", "pickup", "free").

```
type: "standard"
```

**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
```

**payments** array required

info

Array of payment methods used for the order. Supports split payments (multiple methods per order). Drives the `payment_type` parameter in GA4 and equivalent fields in other destinations. [**View complete Payment Object documentation**](/objects/payment.md)

**payments\[0]** object required

**name** string required

info

Payment method name.

```
name: "Example Payment Method"
```

**value** number required

info

Amount paid with this payment method

```
value: 12.99
```

**id** string

info

Payment method internal identifier

```
id: "pay_abc123"
```

**type** string

info

Payment type. Free-form string, use consistent naming (e.g. "card", "paypal", "bank\_transfer", "gift\_card", "cash\_on\_delivery").

```
type: "card"
```

**coupons** array

info

Array of order-level coupons applied to the order. Drives the `coupon` field in GA4 `purchase` and equivalent fields in other destinations. Product-level coupons go inside each product's own `coupons` array. [**View complete Coupon Object documentation**](/objects/coupon.md)

**coupons\[0]** object

**name** string required

info

Coupon name or code.

```
name: "EXAMPLE_COUPON"
```

**value** number recommended

info

Coupon discount value.

```
value: 123.99
```

**tax\_included** boolean recommended

info

Whether coupon value includes taxes

```
tax_included: true
```

**tax\_percent** number recommended

info

Tax percentage for the coupon

```
tax_percent: 21
```

**id** string

info

Coupon internal identifier.

```
id: "cpn_abc123"
```

**type** string

info

Coupon type. Free-form string, use consistent naming (e.g. "LOYALTY", "SEASONAL", "FIRST\_ORDER", "SHIPPING").

```
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
```

**user** object recommended

info

Include user identifiers whenever available — even a single email or phone number dramatically improves match rates for **Meta Advanced Matching**, **Google Enhanced Conversions** and **TikTok Advanced Matching**, which directly translates to better-reported ROAS and more accurate audience targeting. [**View complete User Object documentation**](/objects/user.md)

**id** string recommended

info

Unique customer identifier in your system.

```
id: "cust_abc123"
```

**email** string recommended

info

Customer email address in plaintext. Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.

```
email: "example.customer@example.com"
```

**phone** string recommended

info

Customer phone number in E.164 format (plaintext). Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.

```
phone: "+10000000000"
```

**first\_name** string recommended

info

Customer first name

```
first_name: "Example First Name"
```

**last\_name** string recommended

info

Customer last name

```
last_name: "Example Last Name"
```

**country** string

info

Country name or ISO country code

```
country: "US"
```

**region** string recommended

info

State, province, or region name

```
region: "Example Region"
```

**city** string recommended

info

City or locality name

```
city: "Example City"
```

**street** string

info

Street address including number

```
street: "123 Sample Street"
```

**postal\_code** string

info

Postal code or ZIP code

```
postal_code: "00000"
```

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

* E-commerce Customer
* B2B Lead/Customer
* Subscription Service
* Content Platform

```
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"
}
```

```
properties: {
  company_size: "enterprise",
  industry: "fintech",
  job_title: "marketing_director",
  decision_maker: "true",
  budget_range: "50000-100000",
  lead_source: ["linkedin", "webinar"],
  qualification_status: "qualified",
  sales_stage: "proposal"
}
```

```
properties: {
  subscription_tier: "premium",
  billing_cycle: "annual",
  feature_usage: ["analytics", "reporting", "api"],
  trial_user: "false",
  renewal_date: "2025-06-30",
  support_level: "priority",
  usage_frequency: "daily"
}
```

```
properties: {
  content_preferences: ["technology", "business"],
  engagement_level: "high",
  newsletter_subscriber: "true",
  social_media_follower: "true",
  content_consumption: "premium",
  device_preference: ["mobile", "desktop"],
  timezone: "Example/Timezone"
}
```

**consent** object recommended

info

Customer consent preferences. Drives Consent Mode behavior in GA4, the `consent` object in Meta CAPI, and limited-data-use flags in TikTok and other destinations. [**View complete Consent Object documentation**](/objects/consent-api.md)

**analytics** boolean required

info

Indicates the user’s explicit consent regarding the collection and processing of data for analytical purposes, such as performance monitoring, usage statistics, and service optimization.

```
analytics: true
```

**personalization** boolean required

info

Indicates the user’s explicit consent regarding the collection and processing of data for personalization purposes, enabling tailored experiences and content customization.

```
personalization: true
```

**marketing** boolean required

info

Indicates the user’s explicit consent regarding the collection and processing of data for marketing purposes, such as targeted advertising, remarketing, and campaign measurement.

```
marketing: true
```

**id** string

info

Optional consent-record identifier. When present, DATA Reshape can persist or relay the consent decision under this ID — useful when you want each stored decision to be tied to a verifiable reference from your Consent Management Platform (CMP consent ID, IAB TC string hash, internal record ID, etc.). Required when the optional audit-trail persistence feature is enabled on the account.

```
id: "consent_record_abc123"
```

## Examples[​](#Examples "Direct link to Examples")

The examples below show how to push `checkout_completed` for four common e-commerce niches — **Fashion**, **Electronics**, **Beauty** and **Home & Deco** — each with representative product attributes for that niche, including the `variant` property for product variants, plus an additional **Minimal** tab with only the required fields. DATA Reshape transforms any of these payloads into the correct shape for every connected destination: a GA4 `purchase`, a Meta `Purchase` (Pixel + Conversions API), a TikTok `Purchase` (Pixel + Events API), plus equivalents in other connected destinations. You do not need to write platform-specific code.

* Fashion
* Electronics
* Beauty
* Home & Deco
* Minimal

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "checkout_completed",
    "value": 134.97,
    "currency": "USD",
    "exchange_rate": 1,
    "id": "ord_abc123",
    "properties": {}
  },
  "context": {
    "url": "https://example.com/checkout/success",
    "page_type": "checkout",
    "environment": "prod"
  },
  "products": [
    {
      "id": "prod_tshirt_navy_m",
      "parent_id": "prod_tshirt_model",
      "name": "Example Cotton T-Shirt - Navy / M",
      "parent_name": "Example Cotton T-Shirt",
      "price_base": 59.99,
      "price": 49.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 2,
      "category": "Apparel",
      "sku": "sku_tshirt_navy_m",
      "parent_sku": "sku_tshirt_model",
      "gtin": "1234567890123",
      "mpn": "MPN-TSHIRT-001",
      "ean": "1234567890123",
      "brand": "Example Brand",
      "type": "variable",
      "stock_status": true,
      "stock_location": "Example Warehouse",
      "created_at": 1748505040077,
      "url": "https://example.com/products/cotton-tshirt-navy-m",
      "parent_url": "https://example.com/products/cotton-tshirt",
      "image": "https://example.com/cdn/tshirt-navy-main.jpg",
      "images": [
        "https://example.com/cdn/tshirt-navy-front.jpg",
        "https://example.com/cdn/tshirt-navy-back.jpg"
      ],
      "categories": [
        { "name": "Apparel", "id": "cat_apparel" },
        { "name": "T-Shirts", "id": "cat_tshirts" }
      ],
      "currency": "USD",
      "exchange_rate": 1,
      "coupons": [
        {
          "name": "EXAMPLE_SEASONAL",
          "value": 10.00,
          "tax_included": true,
          "tax_percent": 19,
          "type": "SEASONAL"
        }
      ],
      "properties": {
        "variant": "Navy / M",
        "color": "navy",
        "size": "M",
        "material": "100% cotton",
        "gender": "unisex",
        "fit": "regular",
        "season": "summer",
        "collection_drop": "essentials_2025",
        "sleeve_length": "short",
        "neckline": "crew",
        "care_instructions": "machine_wash_cold"
      }
    },
    {
      "id": "prod_jeans_blue_32",
      "parent_id": "prod_jeans_model",
      "name": "Example Slim Jeans - Indigo / 32",
      "parent_name": "Example Slim Jeans",
      "price_base": 89.99,
      "price": 79.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Apparel",
      "sku": "sku_jeans_blue_32",
      "parent_sku": "sku_jeans_model",
      "brand": "Example Brand",
      "type": "variable",
      "stock_status": true,
      "url": "https://example.com/products/slim-jeans-indigo-32",
      "image": "https://example.com/cdn/jeans-indigo.jpg",
      "properties": {
        "variant": "Indigo / 32",
        "color": "indigo",
        "size": "32",
        "material": "98% cotton, 2% elastane",
        "fit": "slim",
        "rise": "mid",
        "wash": "dark"
      }
    }
  ],
  "shipping": [
    {
      "name": "Example Standard Shipping",
      "value": 9.99,
      "tax_included": true,
      "tax_percent": 19,
      "id": "shp_abc123",
      "type": "standard",
      "currency": "USD",
      "exchange_rate": 1
    }
  ],
  "payments": [
    {
      "name": "Example Card Payment",
      "value": 134.97,
      "id": "pay_abc123",
      "type": "card"
    }
  ],
  "coupons": [
    {
      "name": "EXAMPLE_FIRSTORDER",
      "value": 15.00,
      "tax_included": true,
      "tax_percent": 19,
      "id": "cpn_first_abc123",
      "type": "FIRST_ORDER",
      "currency": "USD",
      "exchange_rate": 1
    }
  ],
  "user": {
    "id": "cust_abc123",
    "email": "example.customer@example.com",
    "phone": "+10000000000",
    "first_name": "Example First Name",
    "last_name": "Example Last Name",
    "country": "US",
    "region": "Example Region",
    "city": "Example City",
    "street": "123 Sample Street",
    "postal_code": "00000",
    "orders_total_number": 3,
    "orders_canceled_number": 0,
    "orders_total_value": 350.47,
    "orders_refunded_value": 0,
    "predicted_value": 800.00,
    "created_at": 1640995200000,
    "properties": {
      "customer_segment": "returning",
      "acquisition_channel": "organic_search",
      "loyalty_tier": "silver",
      "preferred_categories": ["apparel", "accessories"]
    }
  },
  "consent": {
    "analytics": true,
    "personalization": true,
    "marketing": true
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "checkout_completed",
    "value": 1399.97,
    "currency": "USD",
    "exchange_rate": 1,
    "id": "ord_abc123",
    "properties": {}
  },
  "context": {
    "url": "https://example.com/checkout/success",
    "page_type": "checkout",
    "environment": "prod"
  },
  "products": [
    {
      "id": "prod_headphones_black",
      "parent_id": "prod_headphones_model",
      "name": "Example Wireless Headphones - Black",
      "parent_name": "Example Wireless Headphones",
      "price_base": 299.99,
      "price": 249.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Electronics",
      "sku": "sku_headphones_black",
      "parent_sku": "sku_headphones_model",
      "gtin": "1234567890123",
      "mpn": "MPN-HEADPHONES-001",
      "ean": "1234567890123",
      "brand": "Example Brand",
      "type": "variable",
      "stock_status": true,
      "stock_location": "Example Warehouse",
      "created_at": 1748505040077,
      "url": "https://example.com/products/wireless-headphones-black",
      "parent_url": "https://example.com/products/wireless-headphones",
      "image": "https://example.com/cdn/headphones-black-main.jpg",
      "images": [
        "https://example.com/cdn/headphones-black-front.jpg",
        "https://example.com/cdn/headphones-black-side.jpg"
      ],
      "categories": [
        { "name": "Electronics", "id": "cat_electronics" },
        { "name": "Audio", "id": "cat_audio" },
        { "name": "Headphones", "id": "cat_headphones" }
      ],
      "currency": "USD",
      "exchange_rate": 1,
      "properties": {
        "variant": "Black",
        "color": "black",
        "connectivity": ["bluetooth", "wired"],
        "noise_cancellation": "active",
        "battery_life_hours": 30,
        "warranty_years": 2,
        "model_year": 2025,
        "energy_rating": "A+",
        "wireless_range_meters": 10,
        "weight_grams": 250
      }
    },
    {
      "id": "prod_laptop_15_512",
      "parent_id": "prod_laptop_model",
      "name": "Example Laptop 15 - 512GB / Silver",
      "parent_name": "Example Laptop 15",
      "price_base": 1299.99,
      "price": 1099.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Electronics",
      "sku": "sku_laptop_15_512",
      "parent_sku": "sku_laptop_model",
      "brand": "Example Brand",
      "type": "variable",
      "stock_status": true,
      "url": "https://example.com/products/laptop-15-512",
      "image": "https://example.com/cdn/laptop-silver.jpg",
      "properties": {
        "variant": "512GB / Silver",
        "color": "silver",
        "storage_gb": 512,
        "memory_gb": 16,
        "screen_size_inches": 15.6,
        "processor": "example_cpu_x12",
        "warranty_years": 2,
        "model_year": 2025
      }
    }
  ],
  "shipping": [
    {
      "name": "Example Express Shipping",
      "value": 24.99,
      "tax_included": true,
      "tax_percent": 19,
      "id": "shp_express_abc123",
      "type": "express",
      "currency": "USD",
      "exchange_rate": 1
    }
  ],
  "payments": [
    {
      "name": "Example Card Payment",
      "value": 1399.97,
      "id": "pay_abc123",
      "type": "card"
    }
  ],
  "coupons": [
    {
      "name": "EXAMPLE_BUNDLE",
      "value": 75.00,
      "tax_included": true,
      "tax_percent": 19,
      "id": "cpn_bundle_abc123",
      "type": "BUNDLE",
      "currency": "USD",
      "exchange_rate": 1
    }
  ],
  "user": {
    "id": "cust_abc123",
    "email": "example.customer@example.com",
    "phone": "+10000000000",
    "first_name": "Example First Name",
    "last_name": "Example Last Name",
    "country": "US",
    "region": "Example Region",
    "city": "Example City",
    "street": "123 Sample Street",
    "postal_code": "00000",
    "orders_total_number": 5,
    "orders_canceled_number": 0,
    "orders_total_value": 2639.97,
    "orders_refunded_value": 0,
    "predicted_value": 4500.00,
    "created_at": 1640995200000,
    "properties": {
      "customer_segment": "tech_enthusiast",
      "acquisition_channel": "paid_search",
      "loyalty_tier": "gold",
      "preferred_categories": ["electronics", "audio"]
    }
  },
  "consent": {
    "analytics": true,
    "personalization": true,
    "marketing": true
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "checkout_completed",
    "value": 89.97,
    "currency": "USD",
    "exchange_rate": 1,
    "id": "ord_abc123",
    "properties": {}
  },
  "context": {
    "url": "https://example.com/checkout/success",
    "page_type": "checkout",
    "environment": "prod"
  },
  "products": [
    {
      "id": "prod_foundation_shade04",
      "parent_id": "prod_foundation_model",
      "name": "Example Liquid Foundation - Shade 04 / 30ml",
      "parent_name": "Example Liquid Foundation",
      "price_base": 39.99,
      "price": 34.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Beauty",
      "sku": "sku_foundation_shade04_30ml",
      "parent_sku": "sku_foundation_model",
      "gtin": "1234567890123",
      "mpn": "MPN-FOUNDATION-001",
      "ean": "1234567890123",
      "brand": "Example Brand",
      "type": "variable",
      "stock_status": true,
      "stock_location": "Example Warehouse",
      "created_at": 1748505040077,
      "url": "https://example.com/products/liquid-foundation-shade-04",
      "parent_url": "https://example.com/products/liquid-foundation",
      "image": "https://example.com/cdn/foundation-shade04-main.jpg",
      "images": [
        "https://example.com/cdn/foundation-shade04-bottle.jpg",
        "https://example.com/cdn/foundation-shade04-swatch.jpg"
      ],
      "categories": [
        { "name": "Beauty", "id": "cat_beauty" },
        { "name": "Makeup", "id": "cat_makeup" },
        { "name": "Foundation", "id": "cat_foundation" }
      ],
      "currency": "USD",
      "exchange_rate": 1,
      "properties": {
        "variant": "Shade 04 / 30ml",
        "shade": "shade_04_warm_beige",
        "volume_ml": 30,
        "skin_type": ["normal", "combination"],
        "finish": "matte",
        "coverage": "medium_to_full",
        "spf": 15,
        "formulation": "vegan",
        "fragrance_free": true,
        "cruelty_free": true,
        "ingredients_highlight": ["hyaluronic_acid", "niacinamide"]
      }
    },
    {
      "id": "prod_lipstick_rose",
      "parent_id": "prod_lipstick_model",
      "name": "Example Matte Lipstick - Rose Petal",
      "parent_name": "Example Matte Lipstick",
      "price_base": 24.99,
      "price": 19.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 2,
      "category": "Beauty",
      "sku": "sku_lipstick_rose",
      "parent_sku": "sku_lipstick_model",
      "brand": "Example Brand",
      "type": "variable",
      "stock_status": true,
      "url": "https://example.com/products/matte-lipstick-rose-petal",
      "image": "https://example.com/cdn/lipstick-rose.jpg",
      "properties": {
        "variant": "Rose Petal",
        "shade": "rose_petal",
        "finish": "matte",
        "formulation": "vegan",
        "cruelty_free": true,
        "long_wear_hours": 8
      }
    }
  ],
  "shipping": [
    {
      "name": "Example Standard Shipping",
      "value": 9.99,
      "tax_included": true,
      "tax_percent": 19,
      "id": "shp_abc123",
      "type": "standard",
      "currency": "USD",
      "exchange_rate": 1
    }
  ],
  "payments": [
    {
      "name": "Example Card Payment",
      "value": 89.97,
      "id": "pay_abc123",
      "type": "card"
    }
  ],
  "coupons": [
    {
      "name": "EXAMPLE_LOYALTY",
      "value": 5.00,
      "tax_included": true,
      "tax_percent": 19,
      "id": "cpn_loyalty_abc123",
      "type": "LOYALTY",
      "currency": "USD",
      "exchange_rate": 1
    }
  ],
  "user": {
    "id": "cust_abc123",
    "email": "example.customer@example.com",
    "phone": "+10000000000",
    "first_name": "Example First Name",
    "last_name": "Example Last Name",
    "country": "US",
    "region": "Example Region",
    "city": "Example City",
    "street": "123 Sample Street",
    "postal_code": "00000",
    "orders_total_number": 8,
    "orders_canceled_number": 1,
    "orders_total_value": 502.27,
    "orders_refunded_value": 39.99,
    "predicted_value": 1500.00,
    "created_at": 1640995200000,
    "properties": {
      "customer_segment": "beauty_enthusiast",
      "acquisition_channel": "social_paid",
      "loyalty_tier": "gold",
      "preferred_categories": ["beauty", "skincare"]
    }
  },
  "consent": {
    "analytics": true,
    "personalization": true,
    "marketing": true
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "checkout_completed",
    "value": 419.97,
    "currency": "USD",
    "exchange_rate": 1,
    "id": "ord_abc123",
    "properties": {}
  },
  "context": {
    "url": "https://example.com/checkout/success",
    "page_type": "checkout",
    "environment": "prod"
  },
  "products": [
    {
      "id": "prod_lamp_brass",
      "parent_id": "prod_lamp_model",
      "name": "Example Floor Lamp - Brass",
      "parent_name": "Example Floor Lamp",
      "price_base": 229.99,
      "price": 189.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Home & Living",
      "sku": "sku_lamp_brass",
      "parent_sku": "sku_lamp_model",
      "gtin": "1234567890123",
      "mpn": "MPN-LAMP-001",
      "ean": "1234567890123",
      "brand": "Example Brand",
      "type": "variable",
      "stock_status": true,
      "stock_location": "Example Warehouse",
      "created_at": 1748505040077,
      "url": "https://example.com/products/floor-lamp-brass",
      "parent_url": "https://example.com/products/floor-lamp",
      "image": "https://example.com/cdn/lamp-brass-main.jpg",
      "images": [
        "https://example.com/cdn/lamp-brass-living-room.jpg",
        "https://example.com/cdn/lamp-brass-detail.jpg"
      ],
      "categories": [
        { "name": "Home & Living", "id": "cat_home" },
        { "name": "Lighting", "id": "cat_lighting" },
        { "name": "Floor Lamps", "id": "cat_floor_lamps" }
      ],
      "currency": "USD",
      "exchange_rate": 1,
      "properties": {
        "variant": "Brass",
        "color": "brass",
        "material": ["metal", "fabric"],
        "dimensions_cm": "30x30x150",
        "weight_kg": 4.5,
        "style": "mid_century",
        "room_type": ["living_room", "bedroom"],
        "finish": "brushed",
        "assembly_required": true,
        "bulb_included": false,
        "wattage_max": 60,
        "cord_length_cm": 200
      }
    },
    {
      "id": "prod_rug_natural_160",
      "parent_id": "prod_rug_model",
      "name": "Example Wool Rug - Natural / 160x230",
      "parent_name": "Example Wool Rug",
      "price_base": 249.99,
      "price": 199.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Home & Living",
      "sku": "sku_rug_natural_160",
      "parent_sku": "sku_rug_model",
      "brand": "Example Brand",
      "type": "variable",
      "stock_status": true,
      "url": "https://example.com/products/wool-rug-natural-160",
      "image": "https://example.com/cdn/rug-natural.jpg",
      "properties": {
        "variant": "Natural / 160x230",
        "color": "natural",
        "material": "wool",
        "dimensions_cm": "160x230",
        "weight_kg": 6.0,
        "style": "scandinavian",
        "room_type": ["living_room"],
        "pile_height_mm": 12
      }
    }
  ],
  "shipping": [
    {
      "name": "Example Standard Shipping",
      "value": 29.99,
      "tax_included": true,
      "tax_percent": 19,
      "id": "shp_abc123",
      "type": "standard",
      "currency": "USD",
      "exchange_rate": 1
    }
  ],
  "payments": [
    {
      "name": "Example Card Payment",
      "value": 419.97,
      "id": "pay_abc123",
      "type": "card"
    }
  ],
  "coupons": [
    {
      "name": "EXAMPLE_CLEARANCE",
      "value": 40.00,
      "tax_included": true,
      "tax_percent": 19,
      "id": "cpn_clearance_abc123",
      "type": "CLEARANCE",
      "currency": "USD",
      "exchange_rate": 1
    }
  ],
  "user": {
    "id": "cust_abc123",
    "email": "example.customer@example.com",
    "phone": "+10000000000",
    "first_name": "Example First Name",
    "last_name": "Example Last Name",
    "country": "US",
    "region": "Example Region",
    "city": "Example City",
    "street": "123 Sample Street",
    "postal_code": "00000",
    "orders_total_number": 2,
    "orders_canceled_number": 0,
    "orders_total_value": 740.00,
    "orders_refunded_value": 0,
    "predicted_value": 2500.00,
    "created_at": 1640995200000,
    "properties": {
      "customer_segment": "home_decorator",
      "acquisition_channel": "pinterest_organic",
      "loyalty_tier": "silver",
      "preferred_categories": ["home", "lighting"]
    }
  },
  "consent": {
    "analytics": true,
    "personalization": true,
    "marketing": true
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "checkout_completed",
    "value": 299.99,
    "currency": "USD",
    "id": "ord_abc123"
  },
  "products": [
    {
      "id": "prod_abc123",
      "name": "Example Product Name",
      "brand": "Example Brand",
      "price_base": 299.99,
      "price": 249.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Example Category"
    }
  ],
  "shipping": [
    {
      "name": "Example Standard Shipping",
      "value": 9.99,
      "type": "standard"
    }
  ],
  "payments": [
    {
      "name": "Example Card Payment",
      "value": 299.99,
      "type": "card"
    }
  ],
  "user": {
    "email": "example.customer@example.com"
  }
});
```

Custom properties

Custom properties (`event.properties`, `user.properties`, `products[*].properties`) are **fully processed server-side**. On **browser-side** pixels and tags, only a subset may be available. Server-side processing can also enrich the outgoing payload with additional parameters derived from context and data quality.

## Best Practices[​](#Best-Practices "Direct link to Best Practices")

* **Always provide `event.id`** — use your internal order or transaction ID. DATA Reshape deduplicates by this value across destinations, so a page reload, double click on the thank-you page, or webhook retry will never produce a double-counted purchase.
* **Fire only when the order is confirmed** — never fire `checkout_completed` for pending or unverified payments (e.g. bank transfer awaiting confirmation). Wait until the order is fully paid/confirmed, otherwise you inflate reported revenue and pollute lookalike-audience training.
* **Include every line item in `products[]`** — Meta `Purchase`, GA4 `purchase` and TikTok `Purchase` all use the item-level breakdown for product-affinity audiences and Catalog optimization. Missing items hurt audience quality.
* **`event.value` must equal the actual amount charged** — including shipping, taxes and after all discounts. This is the value used for ROAS, conversion-value bidding, and lookalike seed thresholds across every destination.
* **Always include the `user` object** — email, phone, name and address dramatically improve match rates for Meta Advanced Matching, Google Enhanced Conversions and TikTok Advanced Matching, and enable post-purchase audience-based flows in other connected destinations. For server-side firing (post-purchase webhook), this is especially important.
* **Consistent product IDs across the funnel** — use the same `products[*].id` here as in `product_viewed`, `product_added_to_cart` and `checkout_started`. This is what lets GA4, Meta and TikTok build proper conversion paths and product-affinity audiences.
* **Fire client-side AND server-side when possible** — client-side push from the thank-you page captures the browser context (cookies, user agent) for pixel-style destinations; a parallel server-side push from your order webhook ensures the conversion is recorded even if the user closes the browser or uses an ad blocker. DATA Reshape deduplicates via `event.id`.


---

# Checkout Started

Fire the **`checkout_started`** event when a visitor initiates the checkout process — typically by clicking "Proceed to Checkout", "Buy Now", or a similar action that leaves the cart and enters the multi-step checkout flow. This is the most important signal for checkout-abandonment audiences and post-checkout-funnel optimization across every advertising and email platform.

Fire the event once when checkout starts, not on each step transition (use `billing_address_added`, `shipping_detail_added`, `payment_method_selected` for individual steps). The `products` array must contain the full cart at the moment checkout begins, with `event.value` equal to the cart total (sum of `price × quantity` across all line items). If the visitor returns to the cart and re-enters checkout, fire `checkout_started` again — each entry into the funnel is a distinct signal.

This event is the DATA Reshape equivalent of the standard begin-checkout event in every major advertising and analytics platform — push it once and Reshape fans it out to every connected destination with the correct platform-specific name and field mapping, so you do not need to fire `gtag`, `fbq`, `ttq` or other tracking function calls in parallel.

* **Google Analytics 4** — `begin_checkout` (with `items`, `value`, `currency`, `coupon`).
* **Google Ads** — dynamic remarketing checkout-start signal, used for checkout-abandonment audiences.
* **Meta Pixel / Meta Conversions API** — `InitiateCheckout` (with `content_ids`, `contents`, `value`, `currency`, `num_items`).
* **TikTok Pixel / TikTok Events API** — `InitiateCheckout` (with `content_id`, `contents`, `value`, `currency`).
* **Other connected destinations** — mapped automatically based on each destination's native schema.

One push, many native events

A single Reshape event can produce **one or more native events per destination**, with different characteristics depending on each website's destination configuration (active pixels, server endpoints, event-mapping rules).

## Complete Reference[​](#Complete-Reference "Direct link to Complete Reference")

The `checkout_started` event accepts the following objects and fields. Required fields must always be present in the payload — everything else is optional but strongly recommended, because richer payloads produce better checkout-abandonment audiences and more accurate dynamic-remarketing creatives. The `products` array must reflect the entire cart at the moment checkout starts.

**event** object required

**name** string required

info

Use only static value **checkout\_started** for `event.name`. DATA Reshape maps this to `begin_checkout` (GA4) and `InitiateCheckout` (Meta, TikTok) automatically.

```
name: "checkout_started"
```

**value** number required

info

Total cart value at the moment checkout starts (sum of `price × quantity` across all line items, before shipping and order-level discounts).

```
value: 249.99
```

**currency** string required

info

Currency code for all monetary values in this event, ISO 4217 three-letter format. Can be overridden in nested objects.

```
currency: "USD"
```

**exchange\_rate** number

info

Custom exchange rate for multi-currency. Default is 1.

```
exchange_rate: 1
```

**id** string

info

Optional event identifier. Useful for correlating multi-entry checkout flows.

```
id: "evt_checkout_abc123"
```

**context** object

info

[**View complete Context Object documentation**](/objects/context-web.md)

**url** string required-if-applicable

info

Collected automatically for standard websites. Required only for SPA applications where URL changes don't trigger automatic page context updates.

```
url:"https://example.com/products/prod_abc123?utm_source=example"
```

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

Array containing every product currently in the cart, with `quantity` set to the cart quantity for each SKU. Use the same `id` as in `product_viewed` and `product_added_to_cart` so destinations can build consistent funnels. [**View complete Product Object documentation**](/objects/product.md)

**products\[0]** object required

**id** string required

info

Unique product identifier in your system.

```
id: "prod_abc123"
```

**parent\_id** string recommended

info

Parent product ID for variants or child products. Defaults to `id` if not provided.

```
parent_id: "prod_parent_xyz789"
```

**name** string required

info

Product name or title displayed to users.

```
name: "Example Product Name"
```

**parent\_name** string

info

Parent product name for variants or child products. Defaults to `name` if not provided.

```
parent_name: "Example Parent Product Name"
```

**price\_base** number required

info

Original or base price before discounts. Always equal to or greater than `price`.

```
price_base: 299.99
```

**price** number required

info

Current selling price after discounts. Always equal to or less than `price_base`.

```
price: 249.99
```

**tax\_included** boolean required

info

Whether the price includes taxes. Defaults to `true` if not provided.

```
tax_included: true
```

**tax\_percent** number required

info

Tax percentage applied to the product (0-50). If not provided, the site default tax rate will be used (generally the standard rate of the country).

```
tax_percent: 19
```

**quantity** number required

info

Quantity of this product in the context of the event. Defaults to 1 if not provided.

```
quantity: 2
```

**category** string recommended

info

Main product category name

```
category: "Example Category"
```

**sku** string

info

Product SKU (Stock Keeping Unit) for inventory tracking

```
sku: "sku_abc123"
```

**parent\_sku** string

info

Parent product SKU for variants or child products. Defaults to `sku` if not provided.

```
parent_sku: "sku_parent_xyz789"
```

**gtin** string

info

Global Trade Item Number for product identification

```
gtin: "1234567890123"
```

**mpn** string

info

Manufacturer Part Number assigned by the manufacturer

```
mpn: "MPN-EXAMPLE-001"
```

**ean** string

info

European Article Number for product barcoding

```
ean: "1234567890123"
```

**brand** string

info

Product brand or manufacturer name

```
brand: "Example Brand"
```

**type** string

info

Product type. Free-form string (e.g. "simple", "variable", "bundle", "subscription").

```
type: "simple"
```

**stock\_status** boolean | number | string recommended

info

Product availability, accepted in any of these forms:

* **boolean** — `true` (in stock) / `false` (out of stock)
* **number** — `> 0` = in stock, `0` or negative = out of stock
* **string** — the following (case-insensitive) are treated as **out of stock**: `0`, `no`, `nu`, `false`, `out of stock`, `sold out`, `unavailable`, `indisponibil`, `fara stoc`, `stoc epuizat`.

Any other value is treated as **in stock**. Defaults to `true` (in stock) if not provided.

```
stock_status: true
```

**stock\_location** string

info

Physical location or warehouse where product is stored

```
stock_location: "Example Warehouse"
```

**created\_at** number

info

Timestamp when product was added to inventory (milliseconds)

```
created_at: 1748505040077
```

**url** string

info

Direct URL to the product page

```
url: "https://example.com/products/prod_abc123"
```

**parent\_url** string

info

URL to the parent product page (for variants)

```
parent_url: "https://example.com/products/prod_parent_xyz789"
```

**image** string

info

Main product image URL

```
image: "https://example.com/cdn/prod_abc123-main.jpg"
```

**images** array

info

Array of additional product image URLs

```
images: [
  "https://example.com/cdn/prod_abc123-1.jpg",
  "https://example.com/cdn/prod_abc123-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: "Example Category", id: "cat_abc123" },
  { name: "Example Subcategory", id: "cat_xyz789" }
]
```

**coupons** array

info

Array of product-level coupons applied to this product. [**View complete Coupon Object documentation**](/objects/coupon.md)

**coupons\[0]** (object) - `required`

**name** string required

info

Coupon name or code.

```
name: "EXAMPLE_COUPON"
```

**value** number recommended

info

Coupon discount value.

```
value: 123.99
```

**tax\_included** boolean recommended

info

Whether coupon value includes taxes

```
tax_included: true
```

**tax\_percent** number recommended

info

Tax percentage for the coupon

```
tax_percent: 21
```

**id** string

info

Coupon internal identifier.

```
id: "cpn_abc123"
```

**type** string

info

Coupon type. Free-form string, use consistent naming (e.g. "LOYALTY", "SEASONAL", "FIRST\_ORDER", "SHIPPING").

```
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. Free-form key-value object. Use properties that match your product catalog and business needs.

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.

* IT & C
* Fashion
* Deco

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

```
properties: {
  color: ["black", "white"],
  size: "M",
  material: "cotton",
  fit: "regular", 
  season: "summer",
  collection: "2024_spring",
  care_instructions: "machine_wash"
}
```

```
properties: {
  color: ["natural", "oak"],
  dimensions: "120x80x75cm",
  material: ["wood", "metal"],
  style: "modern",
  room_type: ["living_room", "office"],
  assembly_required: "true"
}
```

**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
```

**coupons** array

info

Array of order-level coupons currently applied to the cart. Product-level coupons go inside each product's own `coupons` array. [**View complete Coupon Object documentation**](/objects/coupon.md)

**coupons\[0]** object

**name** string required

info

Coupon name or code.

```
name: "EXAMPLE_COUPON"
```

**value** number recommended

info

Coupon discount value.

```
value: 123.99
```

**tax\_included** boolean recommended

info

Whether coupon value includes taxes

```
tax_included: true
```

**tax\_percent** number recommended

info

Tax percentage for the coupon

```
tax_percent: 21
```

**id** string

info

Coupon internal identifier.

```
id: "cpn_abc123"
```

**type** string

info

Coupon type. Free-form string, use consistent naming (e.g. "LOYALTY", "SEASONAL", "FIRST\_ORDER", "SHIPPING").

```
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
```

**user** object recommended

info

Include user identifiers whenever they are available — even a single email or phone number dramatically improves match rates for **Meta Advanced Matching**, **Google Enhanced Conversions** and **TikTok Advanced Matching**. [**View complete User Object documentation**](/objects/user.md)

**id** string recommended

info

Unique customer identifier in your system.

```
id: "cust_abc123"
```

**email** string recommended

info

Customer email address in plaintext. Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.

```
email: "example.customer@example.com"
```

**phone** string recommended

info

Customer phone number in E.164 format (plaintext). Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.

```
phone: "+10000000000"
```

**first\_name** string recommended

info

Customer first name

```
first_name: "Example First Name"
```

**last\_name** string recommended

info

Customer last name

```
last_name: "Example Last Name"
```

**country** string

info

Country name or ISO country code

```
country: "US"
```

**region** string recommended

info

State, province, or region name

```
region: "Example Region"
```

**city** string recommended

info

City or locality name

```
city: "Example City"
```

**street** string

info

Street address including number

```
street: "123 Sample Street"
```

**postal\_code** string

info

Postal code or ZIP code

```
postal_code: "00000"
```

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

* E-commerce Customer
* B2B Lead/Customer
* Subscription Service
* Content Platform

```
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"
}
```

```
properties: {
  company_size: "enterprise",
  industry: "fintech",
  job_title: "marketing_director",
  decision_maker: "true",
  budget_range: "50000-100000",
  lead_source: ["linkedin", "webinar"],
  qualification_status: "qualified",
  sales_stage: "proposal"
}
```

```
properties: {
  subscription_tier: "premium",
  billing_cycle: "annual",
  feature_usage: ["analytics", "reporting", "api"],
  trial_user: "false",
  renewal_date: "2025-06-30",
  support_level: "priority",
  usage_frequency: "daily"
}
```

```
properties: {
  content_preferences: ["technology", "business"],
  engagement_level: "high",
  newsletter_subscriber: "true",
  social_media_follower: "true",
  content_consumption: "premium",
  device_preference: ["mobile", "desktop"],
  timezone: "Example/Timezone"
}
```

## Examples[​](#Examples "Direct link to Examples")

The examples below show how to push `checkout_started` for four common e-commerce niches — **Fashion**, **Electronics**, **Beauty** and **Home & Deco** — each with representative product attributes for that niche, plus an additional **Minimal** tab with only the required fields. DATA Reshape transforms any of these payloads into the correct shape for every connected destination: a GA4 `begin_checkout`, a Meta `InitiateCheckout` (Pixel + Conversions API), a TikTok `InitiateCheckout` (Pixel + Events API), plus equivalents in other connected destinations. You do not need to write platform-specific code.

* Fashion
* Electronics
* Beauty
* Home & Deco
* Minimal

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "checkout_started",
    "value": 129.98,
    "currency": "USD",
    "exchange_rate": 1
  },
  "context": {
    "url": "https://example.com/checkout",
    "page_type": "checkout",
    "environment": "prod"
  },
  "products": [
    {
      "id": "prod_tshirt_navy_m",
      "parent_id": "prod_tshirt_model",
      "name": "Example Cotton T-Shirt - Navy / M",
      "parent_name": "Example Cotton T-Shirt",
      "price_base": 59.99,
      "price": 49.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Apparel",
      "sku": "sku_tshirt_navy_m",
      "parent_sku": "sku_tshirt_model",
      "gtin": "1234567890123",
      "mpn": "MPN-TSHIRT-001",
      "ean": "1234567890123",
      "brand": "Example Brand",
      "type": "variable",
      "stock_status": true,
      "stock_location": "Example Warehouse",
      "created_at": 1748505040077,
      "url": "https://example.com/products/cotton-tshirt-navy-m",
      "parent_url": "https://example.com/products/cotton-tshirt",
      "image": "https://example.com/cdn/tshirt-navy-main.jpg",
      "images": [
        "https://example.com/cdn/tshirt-navy-front.jpg",
        "https://example.com/cdn/tshirt-navy-back.jpg"
      ],
      "categories": [
        { "name": "Apparel", "id": "cat_apparel" },
        { "name": "T-Shirts", "id": "cat_tshirts" }
      ],
      "currency": "USD",
      "exchange_rate": 1,
      "properties": {
        "variant": "Navy / M",
        "color": "navy",
        "size": "M",
        "material": "100% cotton",
        "gender": "unisex",
        "fit": "regular",
        "season": "summer",
        "collection_drop": "essentials_2025"
      }
    },
    {
      "id": "prod_jeans_blue_32",
      "parent_id": "prod_jeans_model",
      "name": "Example Slim Jeans - Indigo / 32",
      "parent_name": "Example Slim Jeans",
      "price_base": 89.99,
      "price": 79.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Apparel",
      "sku": "sku_jeans_blue_32",
      "parent_sku": "sku_jeans_model",
      "brand": "Example Brand",
      "type": "variable",
      "stock_status": true,
      "url": "https://example.com/products/slim-jeans-indigo-32",
      "image": "https://example.com/cdn/jeans-indigo.jpg",
      "properties": {
        "variant": "Indigo / 32",
        "color": "indigo",
        "size": "32",
        "material": "98% cotton, 2% elastane",
        "fit": "slim",
        "rise": "mid",
        "wash": "dark"
      }
    }
  ],
  "coupons": [
    {
      "name": "EXAMPLE_FIRSTORDER",
      "value": 15.00,
      "tax_included": true,
      "tax_percent": 19,
      "id": "cpn_first_abc123",
      "type": "FIRST_ORDER"
    }
  ],
  "user": {
    "id": "cust_abc123",
    "email": "example.customer@example.com",
    "phone": "+10000000000",
    "first_name": "Example First Name",
    "last_name": "Example Last Name",
    "country": "US",
    "city": "Example City",
    "properties": {
      "customer_segment": "returning",
      "acquisition_channel": "organic_search",
      "loyalty_tier": "silver"
    }
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "checkout_started",
    "value": 1349.98,
    "currency": "USD",
    "exchange_rate": 1
  },
  "context": {
    "url": "https://example.com/checkout",
    "page_type": "checkout",
    "environment": "prod"
  },
  "products": [
    {
      "id": "prod_headphones_black",
      "parent_id": "prod_headphones_model",
      "name": "Example Wireless Headphones - Black",
      "parent_name": "Example Wireless Headphones",
      "price_base": 299.99,
      "price": 249.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Electronics",
      "sku": "sku_headphones_black",
      "parent_sku": "sku_headphones_model",
      "gtin": "1234567890123",
      "brand": "Example Brand",
      "type": "variable",
      "stock_status": true,
      "url": "https://example.com/products/wireless-headphones-black",
      "image": "https://example.com/cdn/headphones-black-main.jpg",
      "properties": {
        "variant": "Black",
        "color": "black",
        "connectivity": ["bluetooth", "wired"],
        "battery_life_hours": 30,
        "warranty_years": 2,
        "model_year": 2025
      }
    },
    {
      "id": "prod_laptop_15_512",
      "parent_id": "prod_laptop_model",
      "name": "Example Laptop 15 - 512GB / Silver",
      "parent_name": "Example Laptop 15",
      "price_base": 1299.99,
      "price": 1099.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Electronics",
      "sku": "sku_laptop_15_512",
      "parent_sku": "sku_laptop_model",
      "brand": "Example Brand",
      "type": "variable",
      "stock_status": true,
      "url": "https://example.com/products/laptop-15-512",
      "image": "https://example.com/cdn/laptop-silver.jpg",
      "properties": {
        "variant": "512GB / Silver",
        "color": "silver",
        "storage_gb": 512,
        "memory_gb": 16,
        "screen_size_inches": 15.6,
        "processor": "example_cpu_x12"
      }
    }
  ],
  "user": {
    "id": "cust_abc123",
    "email": "example.customer@example.com",
    "phone": "+10000000000",
    "country": "US",
    "city": "Example City",
    "properties": {
      "customer_segment": "tech_enthusiast",
      "loyalty_tier": "gold"
    }
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "checkout_started",
    "value": 74.97,
    "currency": "USD",
    "exchange_rate": 1
  },
  "context": {
    "url": "https://example.com/checkout",
    "page_type": "checkout",
    "environment": "prod"
  },
  "products": [
    {
      "id": "prod_foundation_shade04",
      "parent_id": "prod_foundation_model",
      "name": "Example Liquid Foundation - Shade 04 / 30ml",
      "parent_name": "Example Liquid Foundation",
      "price_base": 39.99,
      "price": 34.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Beauty",
      "sku": "sku_foundation_shade04_30ml",
      "parent_sku": "sku_foundation_model",
      "gtin": "1234567890123",
      "brand": "Example Brand",
      "type": "variable",
      "stock_status": true,
      "url": "https://example.com/products/liquid-foundation-shade-04",
      "image": "https://example.com/cdn/foundation-shade04-main.jpg",
      "properties": {
        "variant": "Shade 04 / 30ml",
        "shade": "shade_04_warm_beige",
        "volume_ml": 30,
        "finish": "matte",
        "spf": 15,
        "formulation": "vegan",
        "cruelty_free": true
      }
    },
    {
      "id": "prod_lipstick_rose",
      "parent_id": "prod_lipstick_model",
      "name": "Example Matte Lipstick - Rose Petal",
      "parent_name": "Example Matte Lipstick",
      "price_base": 24.99,
      "price": 19.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 2,
      "category": "Beauty",
      "sku": "sku_lipstick_rose",
      "parent_sku": "sku_lipstick_model",
      "brand": "Example Brand",
      "type": "variable",
      "stock_status": true,
      "url": "https://example.com/products/matte-lipstick-rose-petal",
      "image": "https://example.com/cdn/lipstick-rose.jpg",
      "properties": {
        "variant": "Rose Petal",
        "shade": "rose_petal",
        "finish": "matte",
        "formulation": "vegan",
        "cruelty_free": true
      }
    }
  ],
  "user": {
    "id": "cust_abc123",
    "email": "example.customer@example.com",
    "phone": "+10000000000",
    "country": "US",
    "city": "Example City",
    "properties": {
      "customer_segment": "beauty_enthusiast",
      "loyalty_tier": "gold"
    }
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "checkout_started",
    "value": 389.98,
    "currency": "USD",
    "exchange_rate": 1
  },
  "context": {
    "url": "https://example.com/checkout",
    "page_type": "checkout",
    "environment": "prod"
  },
  "products": [
    {
      "id": "prod_lamp_brass",
      "parent_id": "prod_lamp_model",
      "name": "Example Floor Lamp - Brass",
      "parent_name": "Example Floor Lamp",
      "price_base": 229.99,
      "price": 189.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Home & Living",
      "sku": "sku_lamp_brass",
      "parent_sku": "sku_lamp_model",
      "gtin": "1234567890123",
      "brand": "Example Brand",
      "type": "variable",
      "stock_status": true,
      "url": "https://example.com/products/floor-lamp-brass",
      "image": "https://example.com/cdn/lamp-brass-main.jpg",
      "properties": {
        "variant": "Brass",
        "color": "brass",
        "material": ["metal", "fabric"],
        "dimensions_cm": "30x30x150",
        "style": "mid_century",
        "room_type": ["living_room", "bedroom"]
      }
    },
    {
      "id": "prod_rug_natural_160",
      "parent_id": "prod_rug_model",
      "name": "Example Wool Rug - Natural / 160x230",
      "parent_name": "Example Wool Rug",
      "price_base": 249.99,
      "price": 199.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Home & Living",
      "sku": "sku_rug_natural_160",
      "parent_sku": "sku_rug_model",
      "brand": "Example Brand",
      "type": "variable",
      "stock_status": true,
      "url": "https://example.com/products/wool-rug-natural-160",
      "image": "https://example.com/cdn/rug-natural.jpg",
      "properties": {
        "variant": "Natural / 160x230",
        "color": "natural",
        "material": "wool",
        "dimensions_cm": "160x230",
        "style": "scandinavian",
        "room_type": ["living_room"]
      }
    }
  ],
  "user": {
    "id": "cust_abc123",
    "email": "example.customer@example.com",
    "phone": "+10000000000",
    "country": "US",
    "city": "Example City",
    "properties": {
      "customer_segment": "home_decorator",
      "loyalty_tier": "silver"
    }
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "checkout_started",
    "value": 249.99,
    "currency": "USD"
  },
  "products": [
    {
      "id": "prod_abc123",
      "name": "Example Product Name",
      "brand": "Example Brand",
      "price_base": 299.99,
      "price": 249.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Example Category"
    }
  ]
});
```

Custom properties

Custom properties (`event.properties`, `user.properties`, `products[*].properties`) are **fully processed server-side**. On **browser-side** pixels and tags, only a subset may be available. Server-side processing can also enrich the outgoing payload with additional parameters derived from context and data quality.

## Best Practices[​](#Best-Practices "Direct link to Best Practices")

* **Fire once per checkout entry** — fire when the user enters the checkout flow, not on each step (use `billing_address_added`, `shipping_detail_added`, `payment_method_selected` for individual steps).
* **Include the full cart in `products[]`** — every line item with its current `quantity`. Missing items hurt checkout-abandonment audience quality.
* **`event.value` = sum of `price × quantity`** — before shipping costs and order-level discounts. Match what the user sees in the cart total at the top of checkout.
* **Use consistent product IDs across the funnel** — same `products[*].id` as in `product_viewed` and `product_added_to_cart`. This is what lets destinations build view→cart→checkout→purchase funnels.
* **Include the `user` object** — even just an email improves match rates for Meta Advanced Matching, Google Enhanced Conversions and TikTok Advanced Matching, and enables similar audience-based flows in other connected destinations.
* **Re-fire on re-entry** — if the user returns to the cart and enters checkout again, fire `checkout_started` again. Each entry is a distinct funnel signal.


---

# Order Canceled

Fire the **`order_canceled`** event when a confirmed order is canceled or refunded — either fully (the whole order is reversed) or partially (only some line items are returned). This is the negative counterpart of `checkout_completed`: it lets every connected destination subtract the reversed revenue, keep ROAS reporting accurate, and avoid optimizing toward customers who cancel.

This event can be fired **client-side** from the browser (e.g. a customer canceling from their account page or an order-status page) **or server-side** from your order-management webhook. Always include the same stable, unique `event.id` you used for the original `checkout_completed` (your order or transaction ID) — DATA Reshape uses it to tie the cancellation back to the original purchase and to deduplicate across destinations.

Like every DATA Reshape event, you push it once and Reshape fans it out to every connected destination with the correct platform-specific name and field mapping — you do not need to fire `gtag`, `fbq`, `ttq` or other tracking function calls in parallel.

* **Google Analytics 4** — `refund` (with `transaction_id`, `items`, `value`, `currency`). A full cancellation refunds the whole transaction; a partial one refunds only the `items` you include.
* **Other connected destinations** — mapped to each destination's cancellation/refund equivalent based on your account's event-mapping configuration (many ad platforms have no native cancel event, in which case it is used as a server-side signal or skipped).

One push, many native events

A single Reshape event can produce **one or more native events per destination**, with different characteristics depending on each website's destination configuration (active pixels, server endpoints, event-mapping rules).

Required: event.id

This event requires a unique `event.id` — use the **same** order/transaction ID as the original `checkout_completed`. DATA Reshape uses it to match the cancellation to the original purchase and to deduplicate across destinations.

## Complete Reference[​](#Complete-Reference "Direct link to Complete Reference")

The `order_canceled` event accepts the following objects and fields. Required fields must always be present in the payload — everything else is optional but recommended. Include in `products` only the line items being canceled/refunded (all of them for a full cancellation, a subset for a partial refund). Unlike `checkout_completed`, there is **no `payments` array** — payment instruments are irrelevant to a cancellation. Set `event.value` to the amount being reversed — only the value of the canceled products, tax included, without shipping (see the canonical rule below).

**event** object required

**name** string required

info

Use only static value **order\_canceled** for `event.name`. DATA Reshape maps this to `refund` (GA4) and to the cancellation/refund equivalent in other connected destinations automatically.

```
name: "order_canceled"
```

**value** number required

info

Amount being reversed — the value of the canceled products for a full cancellation, or the refunded portion for a partial refund. This is the value destinations subtract from reported revenue.

Canonical rule — event.value for order\_canceled

`event.value` MUST always equal **only the value of the returned/canceled products, with tax INCLUDED** — no shipping, no other costs. This exact composition is a hard contract: the framework relies on it to correctly derive tax-excluded values per destination (e.g. GA4 `refund` value overrides, Google Ads adjustments). If your integration sends anything else here (order totals with shipping, tax-excluded amounts), destination values will be wrong — fix the integration, never expect the framework to compensate. Note this differs from `checkout_completed`, where `event.value` is **products + shipping + other costs − order coupons** (tax included).

```
value: 299.99
```

**currency** string required

info

Currency code for all monetary values in this event (ISO 4217). Use the same currency as the original order.

```
currency: "USD"
```

**exchange\_rate** number

info

Custom exchange rate for multi-currency reporting. Default is 1.

```
exchange_rate: 1
```

**id** string required

info

Order or transaction ID from your system — use the **same** ID as the original `checkout_completed`. Required for cross-destination deduplication and to match the cancellation to the original purchase.

```
id: "ord_abc123"
```

**reason** string recommended

info

Short, human-readable cancellation reason. Lands in a predictable, queryable place across destinations (e.g. the `reason` parameter in GA4). Use a consistent vocabulary — e.g. `customer_request`, `out_of_stock`, `payment_declined`, `fraud`, `duplicate`.

```
reason: "customer_request"
```

**context** object

info

[**View complete Context Object documentation**](/objects/context-web.md)

**url** string required-if-applicable

info

Collected automatically for standard websites. Required only for SPA applications where URL changes don't trigger automatic page context updates.

```
url:"https://example.com/products/prod_abc123?utm_source=example"
```

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

The line items being canceled/refunded — every item for a full cancellation, or only the returned items for a partial refund. This populates the `items` array in the GA4 `refund` and the per-item breakdown in other connected destinations. [**View complete Product Object documentation**](/objects/product.md)

**products\[0]** object required

**id** string required

info

Unique product identifier in your system.

```
id: "prod_abc123"
```

**parent\_id** string recommended

info

Parent product ID for variants or child products. Defaults to `id` if not provided.

```
parent_id: "prod_parent_xyz789"
```

**name** string required

info

Product name or title displayed to users.

```
name: "Example Product Name"
```

**parent\_name** string

info

Parent product name for variants or child products. Defaults to `name` if not provided.

```
parent_name: "Example Parent Product Name"
```

**price\_base** number required

info

Original or base price before discounts. Always equal to or greater than `price`.

```
price_base: 299.99
```

**price** number required

info

Current selling price after discounts. Always equal to or less than `price_base`.

```
price: 249.99
```

**tax\_included** boolean required

info

Whether the price includes taxes. Defaults to `true` if not provided.

```
tax_included: true
```

**tax\_percent** number required

info

Tax percentage applied to the product (0-50). If not provided, the site default tax rate will be used (generally the standard rate of the country).

```
tax_percent: 19
```

**quantity** number required

info

Quantity of this product in the context of the event. Defaults to 1 if not provided.

```
quantity: 2
```

**category** string recommended

info

Main product category name

```
category: "Example Category"
```

**sku** string

info

Product SKU (Stock Keeping Unit) for inventory tracking

```
sku: "sku_abc123"
```

**parent\_sku** string

info

Parent product SKU for variants or child products. Defaults to `sku` if not provided.

```
parent_sku: "sku_parent_xyz789"
```

**gtin** string

info

Global Trade Item Number for product identification

```
gtin: "1234567890123"
```

**mpn** string

info

Manufacturer Part Number assigned by the manufacturer

```
mpn: "MPN-EXAMPLE-001"
```

**ean** string

info

European Article Number for product barcoding

```
ean: "1234567890123"
```

**brand** string

info

Product brand or manufacturer name

```
brand: "Example Brand"
```

**type** string

info

Product type. Free-form string (e.g. "simple", "variable", "bundle", "subscription").

```
type: "simple"
```

**stock\_status** boolean | number | string recommended

info

Product availability, accepted in any of these forms:

* **boolean** — `true` (in stock) / `false` (out of stock)
* **number** — `> 0` = in stock, `0` or negative = out of stock
* **string** — the following (case-insensitive) are treated as **out of stock**: `0`, `no`, `nu`, `false`, `out of stock`, `sold out`, `unavailable`, `indisponibil`, `fara stoc`, `stoc epuizat`.

Any other value is treated as **in stock**. Defaults to `true` (in stock) if not provided.

```
stock_status: true
```

**stock\_location** string

info

Physical location or warehouse where product is stored

```
stock_location: "Example Warehouse"
```

**created\_at** number

info

Timestamp when product was added to inventory (milliseconds)

```
created_at: 1748505040077
```

**url** string

info

Direct URL to the product page

```
url: "https://example.com/products/prod_abc123"
```

**parent\_url** string

info

URL to the parent product page (for variants)

```
parent_url: "https://example.com/products/prod_parent_xyz789"
```

**image** string

info

Main product image URL

```
image: "https://example.com/cdn/prod_abc123-main.jpg"
```

**images** array

info

Array of additional product image URLs

```
images: [
  "https://example.com/cdn/prod_abc123-1.jpg",
  "https://example.com/cdn/prod_abc123-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: "Example Category", id: "cat_abc123" },
  { name: "Example Subcategory", id: "cat_xyz789" }
]
```

**coupons** array

info

Array of product-level coupons applied to this product. [**View complete Coupon Object documentation**](/objects/coupon.md)

**coupons\[0]** (object) - `required`

**name** string required

info

Coupon name or code.

```
name: "EXAMPLE_COUPON"
```

**value** number recommended

info

Coupon discount value.

```
value: 123.99
```

**tax\_included** boolean recommended

info

Whether coupon value includes taxes

```
tax_included: true
```

**tax\_percent** number recommended

info

Tax percentage for the coupon

```
tax_percent: 21
```

**id** string

info

Coupon internal identifier.

```
id: "cpn_abc123"
```

**type** string

info

Coupon type. Free-form string, use consistent naming (e.g. "LOYALTY", "SEASONAL", "FIRST\_ORDER", "SHIPPING").

```
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. Free-form key-value object. Use properties that match your product catalog and business needs.

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.

* IT & C
* Fashion
* Deco

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

```
properties: {
  color: ["black", "white"],
  size: "M",
  material: "cotton",
  fit: "regular", 
  season: "summer",
  collection: "2024_spring",
  care_instructions: "machine_wash"
}
```

```
properties: {
  color: ["natural", "oak"],
  dimensions: "120x80x75cm",
  material: ["wood", "metal"],
  style: "modern",
  room_type: ["living_room", "office"],
  assembly_required: "true"
}
```

**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
```

**shipping** array

info

Shipping methods from the original order. Include only if the shipping cost is part of the reversed amount. [**View complete Shipping Object documentation**](/objects/shipping.md)

**shipping\[0]** object

**name** string required

info

Shipping method name

```
name: "Example Shipping Method"
```

**value** number required

info

Shipping cost value

```
value: 12.99
```

**tax\_included** boolean recommended

info

Whether shipping cost includes taxes

```
tax_included: true
```

**tax\_percent** number recommended

info

Tax percentage for shipping (0-50)

```
tax_percent: 19
```

**id** string

info

Shipping method identifier.

```
id: "shp_abc123"
```

**type** string

info

Shipping type. Free-form string, use consistent naming (e.g. "standard", "express", "next\_day", "pickup", "free").

```
type: "standard"
```

**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
```

**coupons** array

info

Order-level coupons that were applied to the original order. Product-level coupons go inside each product's own `coupons` array. [**View complete Coupon Object documentation**](/objects/coupon.md)

**coupons\[0]** object

**name** string required

info

Coupon name or code.

```
name: "EXAMPLE_COUPON"
```

**value** number recommended

info

Coupon discount value.

```
value: 123.99
```

**tax\_included** boolean recommended

info

Whether coupon value includes taxes

```
tax_included: true
```

**tax\_percent** number recommended

info

Tax percentage for the coupon

```
tax_percent: 21
```

**id** string

info

Coupon internal identifier.

```
id: "cpn_abc123"
```

**type** string

info

Coupon type. Free-form string, use consistent naming (e.g. "LOYALTY", "SEASONAL", "FIRST\_ORDER", "SHIPPING").

```
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
```

**user** object recommended

info

Include user identifiers whenever available — the same `user.id` (and email/phone) as the original order lets destinations attribute the reversal to the correct customer and audience. [**View complete User Object documentation**](/objects/user.md)

**id** string recommended

info

Unique customer identifier in your system.

```
id: "cust_abc123"
```

**email** string recommended

info

Customer email address in plaintext. Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.

```
email: "example.customer@example.com"
```

**phone** string recommended

info

Customer phone number in E.164 format (plaintext). Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.

```
phone: "+10000000000"
```

**first\_name** string recommended

info

Customer first name

```
first_name: "Example First Name"
```

**last\_name** string recommended

info

Customer last name

```
last_name: "Example Last Name"
```

**country** string

info

Country name or ISO country code

```
country: "US"
```

**region** string recommended

info

State, province, or region name

```
region: "Example Region"
```

**city** string recommended

info

City or locality name

```
city: "Example City"
```

**street** string

info

Street address including number

```
street: "123 Sample Street"
```

**postal\_code** string

info

Postal code or ZIP code

```
postal_code: "00000"
```

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

* E-commerce Customer
* B2B Lead/Customer
* Subscription Service
* Content Platform

```
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"
}
```

```
properties: {
  company_size: "enterprise",
  industry: "fintech",
  job_title: "marketing_director",
  decision_maker: "true",
  budget_range: "50000-100000",
  lead_source: ["linkedin", "webinar"],
  qualification_status: "qualified",
  sales_stage: "proposal"
}
```

```
properties: {
  subscription_tier: "premium",
  billing_cycle: "annual",
  feature_usage: ["analytics", "reporting", "api"],
  trial_user: "false",
  renewal_date: "2025-06-30",
  support_level: "priority",
  usage_frequency: "daily"
}
```

```
properties: {
  content_preferences: ["technology", "business"],
  engagement_level: "high",
  newsletter_subscriber: "true",
  social_media_follower: "true",
  content_consumption: "premium",
  device_preference: ["mobile", "desktop"],
  timezone: "Example/Timezone"
}
```

**consent** object recommended

info

Customer consent preferences. Drives Consent Mode behavior in GA4, the `consent` object in Meta CAPI, and limited-data-use flags in TikTok and other destinations. [**View complete Consent Object documentation**](/objects/consent-api.md)

**analytics** boolean required

info

Indicates the user’s explicit consent regarding the collection and processing of data for analytical purposes, such as performance monitoring, usage statistics, and service optimization.

```
analytics: true
```

**personalization** boolean required

info

Indicates the user’s explicit consent regarding the collection and processing of data for personalization purposes, enabling tailored experiences and content customization.

```
personalization: true
```

**marketing** boolean required

info

Indicates the user’s explicit consent regarding the collection and processing of data for marketing purposes, such as targeted advertising, remarketing, and campaign measurement.

```
marketing: true
```

**id** string

info

Optional consent-record identifier. When present, DATA Reshape can persist or relay the consent decision under this ID — useful when you want each stored decision to be tied to a verifiable reference from your Consent Management Platform (CMP consent ID, IAB TC string hash, internal record ID, etc.). Required when the optional audit-trail persistence feature is enabled on the account.

```
id: "consent_record_abc123"
```

## Examples[​](#Examples "Direct link to Examples")

The examples below show how to push `order_canceled` for a **Full Cancellation** (the whole order is reversed) and a **Partial Refund** (only some items are returned), plus a **Minimal** tab with only the required fields. DATA Reshape transforms any of these payloads into a GA4 `refund` plus equivalents in other connected destinations — you do not need to write platform-specific code.

* Full Cancellation
* Partial Refund
* Minimal

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "order_canceled",
    "value": 134.97,
    "currency": "USD",
    "exchange_rate": 1,
    "id": "ord_abc123",
    "reason": "customer_request"
  },
  "context": {
    "url": "https://example.com/account/orders/ord_abc123",
    "page_type": "account",
    "environment": "prod"
  },
  "products": [
    {
      "id": "prod_tshirt_navy_m",
      "parent_id": "prod_tshirt_model",
      "name": "Example Cotton T-Shirt - Navy / M",
      "parent_name": "Example Cotton T-Shirt",
      "price_base": 59.99,
      "price": 49.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 2,
      "category": "Apparel",
      "sku": "sku_tshirt_navy_m",
      "brand": "Example Brand",
      "type": "variable",
      "currency": "USD",
      "properties": {
        "variant": "Navy / M",
        "color": "navy",
        "size": "M"
      }
    },
    {
      "id": "prod_jeans_blue_32",
      "parent_id": "prod_jeans_model",
      "name": "Example Slim Jeans - Indigo / 32",
      "parent_name": "Example Slim Jeans",
      "price_base": 89.99,
      "price": 79.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Apparel",
      "sku": "sku_jeans_blue_32",
      "brand": "Example Brand",
      "type": "variable"
    }
  ],
  "shipping": [
    {
      "name": "Example Standard Shipping",
      "value": 9.99,
      "tax_included": true,
      "tax_percent": 19,
      "id": "shp_abc123",
      "type": "standard",
      "currency": "USD"
    }
  ],
  "user": {
    "id": "cust_abc123",
    "email": "example.customer@example.com",
    "phone": "+10000000000",
    "country": "US",
    "orders_total_number": 3,
    "orders_canceled_number": 1
  },
  "consent": {
    "analytics": true,
    "personalization": true,
    "marketing": true
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "order_canceled",
    "value": 34.99,
    "currency": "USD",
    "exchange_rate": 1,
    "id": "ord_abc123",
    "reason": "defective"
  },
  "context": {
    "url": "https://example.com/account/orders/ord_abc123",
    "page_type": "account",
    "environment": "prod"
  },
  "products": [
    {
      "id": "prod_foundation_shade04",
      "parent_id": "prod_foundation_model",
      "name": "Example Liquid Foundation - Shade 04 / 30ml",
      "parent_name": "Example Liquid Foundation",
      "price_base": 39.99,
      "price": 34.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Beauty",
      "sku": "sku_foundation_shade04_30ml",
      "brand": "Example Brand",
      "type": "variable",
      "currency": "USD",
      "properties": {
        "variant": "Shade 04 / 30ml",
        "shade": "shade_04_warm_beige"
      }
    }
  ],
  "user": {
    "id": "cust_abc123",
    "email": "example.customer@example.com"
  },
  "consent": {
    "analytics": true,
    "personalization": true,
    "marketing": true
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "order_canceled",
    "value": 299.99,
    "currency": "USD",
    "id": "ord_abc123",
    "reason": "customer_request"
  },
  "products": [
    {
      "id": "prod_abc123",
      "name": "Example Product Name",
      "brand": "Example Brand",
      "price_base": 299.99,
      "price": 249.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Example Category"
    }
  ],
  "user": {
    "email": "example.customer@example.com"
  }
});
```

Custom properties

Custom properties (`event.properties`, `user.properties`, `products[*].properties`) are **fully processed server-side**. On **browser-side** pixels and tags, only a subset may be available. Server-side processing can also enrich the outgoing payload with additional parameters derived from context and data quality.

## Best Practices[​](#Best-Practices "Direct link to Best Practices")

* **Reuse the original `event.id`** — always send the same order/transaction ID as the original `checkout_completed`. This is what lets DATA Reshape match the cancellation to the purchase and deduplicate across destinations.
* **Set `event.value` to the reversed amount** — only the value of the canceled/refunded products, tax included, without shipping or other costs: all products for a full cancellation, the refunded subset for a partial refund. This is what destinations subtract from reported revenue.
* **Include only the canceled items in `products[]`** — all line items for a full cancellation, only the returned ones for a partial refund. GA4 `refund` uses this to reverse the correct line items.
* **Always set `reason`** — a consistent, short cancellation reason (`customer_request`, `out_of_stock`, `payment_declined`, `fraud`, `duplicate`, ...) makes cancellations groupable for reporting across destinations.
* **No `payments` array** — payment instruments are irrelevant to a cancellation; unlike `checkout_completed`, `order_canceled` does not use `payments`.
* **Fire client-side OR server-side** — a browser push (e.g. from the account/order page) captures browser context; a server-side push from your order-management webhook guarantees the reversal is recorded even if no browser is involved. DATA Reshape deduplicates via `event.id`.


---

# Payment Method Selected

Fire the **`payment_method_selected`** event when a visitor selects or confirms a payment method during checkout — picking a card, choosing PayPal/Apple Pay, selecting cash-on-delivery, etc. This is a high-intent checkout-step signal: users who reach payment selection are statistically the closest to converting, which makes them a critical audience for late-funnel optimization.

Fire the event once when the payment method is confirmed (not on every dropdown change). If the user changes payment method afterward, fire again — each confirmed selection is a distinct signal.

This event is the DATA Reshape equivalent of the standard payment-info event in every major advertising and analytics platform — push it once and Reshape fans it out to every connected destination with the correct platform-specific name and field mapping, so you do not need to fire `gtag`, `fbq`, `ttq` or other tracking function calls in parallel.

* **Google Analytics 4** — `add_payment_info` (with `items`, `value`, `currency`, `payment_type`, `coupon`).
* **Meta Pixel / Meta Conversions API** — `AddPaymentInfo` (with `content_ids`, `value`, `currency`).
* **TikTok Pixel / TikTok Events API** — `AddPaymentInfo` (with `content_id`, `value`, `currency`).
* **Other connected destinations** — mapped automatically based on each destination's native schema.

One push, many native events

A single Reshape event can produce **one or more native events per destination**, with different characteristics depending on each website's destination configuration (active pixels, server endpoints, event-mapping rules).

## Complete Reference[​](#Complete-Reference "Direct link to Complete Reference")

The `payment_method_selected` event accepts the following objects and fields. Required fields must always be present in the payload — everything else is optional but strongly recommended. The `products[]` array reflects the current cart and the `payments[]` array reflects the selected method.

**event** object required

**name** string required

info

Use only static value **payment\_method\_selected** for `event.name`. DATA Reshape maps this to `add_payment_info` (GA4) and `AddPaymentInfo` (Meta, TikTok) automatically.

```
name: "payment_method_selected"
```

**value** number required

info

Current order total at this checkout step.

```
value: 249.99
```

**currency** string required

info

Currency code, ISO 4217 three-letter format.

```
currency: "USD"
```

**exchange\_rate** number

info

Default is 1.

```
exchange_rate: 1
```

**id** string

info

Optional event identifier.

```
id: "evt_payment_abc123"
```

**context** object

info

[**View complete Context Object documentation**](/objects/context-web.md)

**url** string required-if-applicable

info

Collected automatically for standard websites. Required only for SPA applications where URL changes don't trigger automatic page context updates.

```
url:"https://example.com/products/prod_abc123?utm_source=example"
```

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

Array containing every product currently in the cart. [**View complete Product Object documentation**](/objects/product.md)

**products\[0]** object required

**id** string required

info

Unique product identifier in your system.

```
id: "prod_abc123"
```

**parent\_id** string recommended

info

Parent product ID for variants or child products. Defaults to `id` if not provided.

```
parent_id: "prod_parent_xyz789"
```

**name** string required

info

Product name or title displayed to users.

```
name: "Example Product Name"
```

**parent\_name** string

info

Parent product name for variants or child products. Defaults to `name` if not provided.

```
parent_name: "Example Parent Product Name"
```

**price\_base** number required

info

Original or base price before discounts. Always equal to or greater than `price`.

```
price_base: 299.99
```

**price** number required

info

Current selling price after discounts. Always equal to or less than `price_base`.

```
price: 249.99
```

**tax\_included** boolean required

info

Whether the price includes taxes. Defaults to `true` if not provided.

```
tax_included: true
```

**tax\_percent** number required

info

Tax percentage applied to the product (0-50). If not provided, the site default tax rate will be used (generally the standard rate of the country).

```
tax_percent: 19
```

**quantity** number required

info

Quantity of this product in the context of the event. Defaults to 1 if not provided.

```
quantity: 2
```

**category** string recommended

info

Main product category name

```
category: "Example Category"
```

**sku** string

info

Product SKU (Stock Keeping Unit) for inventory tracking

```
sku: "sku_abc123"
```

**parent\_sku** string

info

Parent product SKU for variants or child products. Defaults to `sku` if not provided.

```
parent_sku: "sku_parent_xyz789"
```

**gtin** string

info

Global Trade Item Number for product identification

```
gtin: "1234567890123"
```

**mpn** string

info

Manufacturer Part Number assigned by the manufacturer

```
mpn: "MPN-EXAMPLE-001"
```

**ean** string

info

European Article Number for product barcoding

```
ean: "1234567890123"
```

**brand** string

info

Product brand or manufacturer name

```
brand: "Example Brand"
```

**type** string

info

Product type. Free-form string (e.g. "simple", "variable", "bundle", "subscription").

```
type: "simple"
```

**stock\_status** boolean | number | string recommended

info

Product availability, accepted in any of these forms:

* **boolean** — `true` (in stock) / `false` (out of stock)
* **number** — `> 0` = in stock, `0` or negative = out of stock
* **string** — the following (case-insensitive) are treated as **out of stock**: `0`, `no`, `nu`, `false`, `out of stock`, `sold out`, `unavailable`, `indisponibil`, `fara stoc`, `stoc epuizat`.

Any other value is treated as **in stock**. Defaults to `true` (in stock) if not provided.

```
stock_status: true
```

**stock\_location** string

info

Physical location or warehouse where product is stored

```
stock_location: "Example Warehouse"
```

**created\_at** number

info

Timestamp when product was added to inventory (milliseconds)

```
created_at: 1748505040077
```

**url** string

info

Direct URL to the product page

```
url: "https://example.com/products/prod_abc123"
```

**parent\_url** string

info

URL to the parent product page (for variants)

```
parent_url: "https://example.com/products/prod_parent_xyz789"
```

**image** string

info

Main product image URL

```
image: "https://example.com/cdn/prod_abc123-main.jpg"
```

**images** array

info

Array of additional product image URLs

```
images: [
  "https://example.com/cdn/prod_abc123-1.jpg",
  "https://example.com/cdn/prod_abc123-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: "Example Category", id: "cat_abc123" },
  { name: "Example Subcategory", id: "cat_xyz789" }
]
```

**coupons** array

info

Array of product-level coupons applied to this product. [**View complete Coupon Object documentation**](/objects/coupon.md)

**coupons\[0]** (object) - `required`

**name** string required

info

Coupon name or code.

```
name: "EXAMPLE_COUPON"
```

**value** number recommended

info

Coupon discount value.

```
value: 123.99
```

**tax\_included** boolean recommended

info

Whether coupon value includes taxes

```
tax_included: true
```

**tax\_percent** number recommended

info

Tax percentage for the coupon

```
tax_percent: 21
```

**id** string

info

Coupon internal identifier.

```
id: "cpn_abc123"
```

**type** string

info

Coupon type. Free-form string, use consistent naming (e.g. "LOYALTY", "SEASONAL", "FIRST\_ORDER", "SHIPPING").

```
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. Free-form key-value object. Use properties that match your product catalog and business needs.

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.

* IT & C
* Fashion
* Deco

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

```
properties: {
  color: ["black", "white"],
  size: "M",
  material: "cotton",
  fit: "regular", 
  season: "summer",
  collection: "2024_spring",
  care_instructions: "machine_wash"
}
```

```
properties: {
  color: ["natural", "oak"],
  dimensions: "120x80x75cm",
  material: ["wood", "metal"],
  style: "modern",
  room_type: ["living_room", "office"],
  assembly_required: "true"
}
```

**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
```

**shipping** array recommended

info

Array of shipping methods selected so far. [**View complete Shipping Object documentation**](/objects/shipping.md)

**shipping\[0]** object

**name** string required

info

Shipping method name

```
name: "Example Shipping Method"
```

**value** number required

info

Shipping cost value

```
value: 12.99
```

**tax\_included** boolean recommended

info

Whether shipping cost includes taxes

```
tax_included: true
```

**tax\_percent** number recommended

info

Tax percentage for shipping (0-50)

```
tax_percent: 19
```

**id** string

info

Shipping method identifier.

```
id: "shp_abc123"
```

**type** string

info

Shipping type. Free-form string, use consistent naming (e.g. "standard", "express", "next\_day", "pickup", "free").

```
type: "standard"
```

**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
```

**payments** array required

info

Array containing the selected payment method(s). Drives the `payment_type` parameter in GA4 and equivalent fields in other destinations. [**View complete Payment Object documentation**](/objects/payment.md)

**payments\[0]** object required

**name** string required

info

Payment method name.

```
name: "Example Payment Method"
```

**value** number required

info

Amount paid with this payment method

```
value: 12.99
```

**id** string

info

Payment method internal identifier

```
id: "pay_abc123"
```

**type** string

info

Payment type. Free-form string, use consistent naming (e.g. "card", "paypal", "bank\_transfer", "gift\_card", "cash\_on\_delivery").

```
type: "card"
```

**user** object recommended

info

[**View complete User Object documentation**](/objects/user.md)

**id** string recommended

info

Unique customer identifier in your system.

```
id: "cust_abc123"
```

**email** string recommended

info

Customer email address in plaintext. Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.

```
email: "example.customer@example.com"
```

**phone** string recommended

info

Customer phone number in E.164 format (plaintext). Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.

```
phone: "+10000000000"
```

**first\_name** string recommended

info

Customer first name

```
first_name: "Example First Name"
```

**last\_name** string recommended

info

Customer last name

```
last_name: "Example Last Name"
```

**country** string

info

Country name or ISO country code

```
country: "US"
```

**region** string recommended

info

State, province, or region name

```
region: "Example Region"
```

**city** string recommended

info

City or locality name

```
city: "Example City"
```

**street** string

info

Street address including number

```
street: "123 Sample Street"
```

**postal\_code** string

info

Postal code or ZIP code

```
postal_code: "00000"
```

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

* E-commerce Customer
* B2B Lead/Customer
* Subscription Service
* Content Platform

```
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"
}
```

```
properties: {
  company_size: "enterprise",
  industry: "fintech",
  job_title: "marketing_director",
  decision_maker: "true",
  budget_range: "50000-100000",
  lead_source: ["linkedin", "webinar"],
  qualification_status: "qualified",
  sales_stage: "proposal"
}
```

```
properties: {
  subscription_tier: "premium",
  billing_cycle: "annual",
  feature_usage: ["analytics", "reporting", "api"],
  trial_user: "false",
  renewal_date: "2025-06-30",
  support_level: "priority",
  usage_frequency: "daily"
}
```

```
properties: {
  content_preferences: ["technology", "business"],
  engagement_level: "high",
  newsletter_subscriber: "true",
  social_media_follower: "true",
  content_consumption: "premium",
  device_preference: ["mobile", "desktop"],
  timezone: "Example/Timezone"
}
```

## Examples[​](#Examples "Direct link to Examples")

The examples below show how to push `payment_method_selected` for four common e-commerce niches — **Fashion**, **Electronics**, **Beauty** and **Home & Deco** — each with representative product attributes, plus an additional **Minimal** tab with only the required fields.

* Fashion
* Electronics
* Beauty
* Home & Deco
* Minimal

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "payment_method_selected",
    "value": 129.98,
    "currency": "USD",
    "exchange_rate": 1
  },
  "context": {
    "url": "https://example.com/checkout/payment",
    "page_type": "checkout",
    "environment": "prod"
  },
  "products": [
    {
      "id": "prod_tshirt_navy_m",
      "parent_id": "prod_tshirt_model",
      "name": "Example Cotton T-Shirt - Navy / M",
      "parent_name": "Example Cotton T-Shirt",
      "price_base": 59.99,
      "price": 49.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Apparel",
      "sku": "sku_tshirt_navy_m",
      "brand": "Example Brand",
      "type": "variable",
      "properties": { "variant": "Navy / M", "color": "navy", "size": "M" }
    },
    {
      "id": "prod_jeans_blue_32",
      "parent_id": "prod_jeans_model",
      "name": "Example Slim Jeans - Indigo / 32",
      "parent_name": "Example Slim Jeans",
      "price_base": 89.99,
      "price": 79.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Apparel",
      "sku": "sku_jeans_blue_32",
      "brand": "Example Brand",
      "type": "variable",
      "properties": { "variant": "Indigo / 32", "color": "indigo", "size": "32" }
    }
  ],
  "shipping": [
    {
      "name": "Example Standard Shipping",
      "value": 9.99,
      "type": "standard"
    }
  ],
  "payments": [
    {
      "name": "Example Card Payment",
      "value": 129.98,
      "id": "pay_abc123",
      "type": "card"
    }
  ],
  "user": {
    "email": "example.customer@example.com",
    "country": "US"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "payment_method_selected",
    "value": 1349.98,
    "currency": "USD",
    "exchange_rate": 1
  },
  "context": {
    "url": "https://example.com/checkout/payment",
    "page_type": "checkout",
    "environment": "prod"
  },
  "products": [
    {
      "id": "prod_headphones_black",
      "parent_id": "prod_headphones_model",
      "name": "Example Wireless Headphones - Black",
      "parent_name": "Example Wireless Headphones",
      "price_base": 299.99,
      "price": 249.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Electronics",
      "sku": "sku_headphones_black",
      "brand": "Example Brand",
      "type": "variable",
      "properties": { "variant": "Black", "color": "black" }
    },
    {
      "id": "prod_laptop_15_512",
      "parent_id": "prod_laptop_model",
      "name": "Example Laptop 15 - 512GB / Silver",
      "parent_name": "Example Laptop 15",
      "price_base": 1299.99,
      "price": 1099.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Electronics",
      "sku": "sku_laptop_15_512",
      "brand": "Example Brand",
      "type": "variable",
      "properties": { "variant": "512GB / Silver", "storage_gb": 512, "memory_gb": 16 }
    }
  ],
  "shipping": [
    {
      "name": "Example Express Shipping",
      "value": 24.99,
      "type": "express"
    }
  ],
  "payments": [
    {
      "name": "Example Card Payment",
      "value": 1349.98,
      "id": "pay_abc123",
      "type": "card"
    }
  ],
  "user": {
    "email": "example.customer@example.com",
    "country": "US"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "payment_method_selected",
    "value": 74.97,
    "currency": "USD",
    "exchange_rate": 1
  },
  "context": {
    "url": "https://example.com/checkout/payment",
    "page_type": "checkout",
    "environment": "prod"
  },
  "products": [
    {
      "id": "prod_foundation_shade04",
      "parent_id": "prod_foundation_model",
      "name": "Example Liquid Foundation - Shade 04 / 30ml",
      "parent_name": "Example Liquid Foundation",
      "price_base": 39.99,
      "price": 34.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Beauty",
      "sku": "sku_foundation_shade04_30ml",
      "brand": "Example Brand",
      "type": "variable",
      "properties": { "variant": "Shade 04 / 30ml", "shade": "shade_04_warm_beige" }
    },
    {
      "id": "prod_lipstick_rose",
      "parent_id": "prod_lipstick_model",
      "name": "Example Matte Lipstick - Rose Petal",
      "parent_name": "Example Matte Lipstick",
      "price_base": 24.99,
      "price": 19.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 2,
      "category": "Beauty",
      "sku": "sku_lipstick_rose",
      "brand": "Example Brand",
      "type": "variable",
      "properties": { "variant": "Rose Petal", "shade": "rose_petal" }
    }
  ],
  "shipping": [
    {
      "name": "Example Standard Shipping",
      "value": 9.99,
      "type": "standard"
    }
  ],
  "payments": [
    {
      "name": "Example Wallet Payment",
      "value": 74.97,
      "id": "pay_abc123",
      "type": "wallet"
    }
  ],
  "user": {
    "email": "example.customer@example.com",
    "country": "US"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "payment_method_selected",
    "value": 389.98,
    "currency": "USD",
    "exchange_rate": 1
  },
  "context": {
    "url": "https://example.com/checkout/payment",
    "page_type": "checkout",
    "environment": "prod"
  },
  "products": [
    {
      "id": "prod_lamp_brass",
      "parent_id": "prod_lamp_model",
      "name": "Example Floor Lamp - Brass",
      "parent_name": "Example Floor Lamp",
      "price_base": 229.99,
      "price": 189.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Home & Living",
      "sku": "sku_lamp_brass",
      "brand": "Example Brand",
      "type": "variable",
      "properties": { "variant": "Brass", "color": "brass" }
    },
    {
      "id": "prod_rug_natural_160",
      "parent_id": "prod_rug_model",
      "name": "Example Wool Rug - Natural / 160x230",
      "parent_name": "Example Wool Rug",
      "price_base": 249.99,
      "price": 199.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Home & Living",
      "sku": "sku_rug_natural_160",
      "brand": "Example Brand",
      "type": "variable",
      "properties": { "variant": "Natural / 160x230", "material": "wool" }
    }
  ],
  "shipping": [
    {
      "name": "Example Standard Shipping",
      "value": 29.99,
      "type": "standard"
    }
  ],
  "payments": [
    {
      "name": "Example Bank Transfer",
      "value": 389.98,
      "id": "pay_abc123",
      "type": "bank_transfer"
    }
  ],
  "user": {
    "email": "example.customer@example.com",
    "country": "US"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "payment_method_selected",
    "value": 249.99,
    "currency": "USD"
  },
  "products": [
    {
      "id": "prod_abc123",
      "name": "Example Product Name",
      "brand": "Example Brand",
      "price_base": 299.99,
      "price": 249.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Example Category"
    }
  ],
  "payments": [
    {
      "name": "Example Card Payment",
      "value": 249.99,
      "type": "card"
    }
  ]
});
```

Custom properties

Custom properties (`event.properties`, `user.properties`, `products[*].properties`) are **fully processed server-side**. On **browser-side** pixels and tags, only a subset may be available. Server-side processing can also enrich the outgoing payload with additional parameters derived from context and data quality.

## Best Practices[​](#Best-Practices "Direct link to Best Practices")

* **Fire once per confirmed selection** — not on every dropdown change. If the user changes payment method, fire again — each confirmed selection is a distinct signal.
* **Always include `payments[0]`** — at least with `name`, `value` and `type` so destinations can report payment-method breakdowns.
* **Keep cart consistency** — `products[]` must reflect the current cart at this checkout step, same IDs as in `checkout_started`.
* **Use stable `payments[*].type` values** — `"card"`, `"paypal"`, `"bank_transfer"`, `"gift_card"`, `"cash_on_delivery"`, `"wallet"` etc. Consistent typing produces clean reports across destinations.


---

# Product Added to Cart

Fire the **`product_added_to_cart`** event when a visitor adds one or more products to their shopping cart — via the "Add to Cart" button, a quick-add action on a product card, an upsell modal, or when they increase the quantity of an existing cart line item. This event is the foundation for cart-abandonment audiences and remarketing campaigns across every advertising platform.

Trigger the event only after the cart addition is confirmed successful (cart state updated, inventory reserved). Do not fire it on button click alone, because validation errors (out of stock, variant unavailable, server timeout) would inflate add-to-cart counts without a matching cart change. Fire one event per product addition, with `products[0].quantity` set to the number of units added in this specific action — not the resulting cart total for that product.

This event is the DATA Reshape equivalent of the standard add-to-cart event in every major advertising and analytics platform — push it once and Reshape fans it out to every connected destination with the correct platform-specific name and field mapping, so you do not need to fire `gtag`, `fbq`, `ttq` or other tracking function calls in parallel.

* **Google Analytics 4** — `add_to_cart` (with `items` array, `value`, `currency`).
* **Google Ads** — dynamic remarketing add-to-cart signal, used for cart-abandonment audiences.
* **Meta Pixel / Meta Conversions API** — `AddToCart` (with `content_ids`, `content_type`, `value`, `currency`, `contents`).
* **TikTok Pixel / TikTok Events API** — `AddToCart` (with `content_id`, `content_type`, `value`, `currency`, `contents`).
* **Other connected destinations** — mapped automatically based on each destination's native schema.

One push, many native events

A single Reshape event can produce **one or more native events per destination**, with different characteristics depending on each website's destination configuration (active pixels, server endpoints, event-mapping rules).

## Complete Reference[​](#Complete-Reference "Direct link to Complete Reference")

The `product_added_to_cart` event accepts the following objects and fields. Required fields must always be present in the payload — everything else is optional but strongly recommended, because richer payloads produce better cart-abandonment audiences and more accurate dynamic-remarketing creatives in GA4 (`add_to_cart`), Meta (`AddToCart`), TikTok (`AddToCart`) and the other connected destinations. The `products` array must contain exactly the product being added (with the actual quantity added in this action, not the cart total).

**event** object required

**name** string required

info

Use only static value **product\_added\_to\_cart** for `event.name`. DATA Reshape maps this to `add_to_cart` (GA4) and `AddToCart` (Meta, TikTok) automatically.

```
name: "product_added_to_cart"
```

**value** number required

info

Total value of the products being added (price × quantity). Used as the monetary value of the event in GA4 (`value`), Meta (`value`), TikTok (`value`) and other destinations.

```
value: 249.99
```

**currency** string required

info

Currency code for all monetary values in this event, ISO 4217 three-letter format. Can be overridden in nested objects.

```
currency: "USD"
```

**exchange\_rate** number

info

Custom exchange rate for multi-currency. Default is 1.

```
exchange_rate: 1
```

**id** string

info

Optional event identifier. Useful for deduplication when the same add-to-cart action may be reported by multiple sources.

```
id: "evt_atc_abc123"
```

**context** object

info

[**View complete Context Object documentation**](/objects/context-web.md)

**url** string required-if-applicable

info

Collected automatically for standard websites. Required only for SPA applications where URL changes don't trigger automatic page context updates.

```
url:"https://example.com/products/prod_abc123?utm_source=example"
```

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

Array containing the product(s) being added to cart in this specific action. `products[0].quantity` is the number of units added now, not the resulting cart total for this SKU. Use the same `id` as in `product_viewed` so destinations can build consistent funnels. [**View complete Product Object documentation**](/objects/product.md)

**products\[0]** object required

**id** string required

info

Unique product identifier in your system.

```
id: "prod_abc123"
```

**parent\_id** string recommended

info

Parent product ID for variants or child products. Defaults to `id` if not provided.

```
parent_id: "prod_parent_xyz789"
```

**name** string required

info

Product name or title displayed to users.

```
name: "Example Product Name"
```

**parent\_name** string

info

Parent product name for variants or child products. Defaults to `name` if not provided.

```
parent_name: "Example Parent Product Name"
```

**price\_base** number required

info

Original or base price before discounts. Always equal to or greater than `price`.

```
price_base: 299.99
```

**price** number required

info

Current selling price after discounts. Always equal to or less than `price_base`.

```
price: 249.99
```

**tax\_included** boolean required

info

Whether the price includes taxes. Defaults to `true` if not provided.

```
tax_included: true
```

**tax\_percent** number required

info

Tax percentage applied to the product (0-50). If not provided, the site default tax rate will be used (generally the standard rate of the country).

```
tax_percent: 19
```

**quantity** number required

info

Quantity of this product in the context of the event. Defaults to 1 if not provided.

```
quantity: 2
```

**category** string recommended

info

Main product category name

```
category: "Example Category"
```

**sku** string

info

Product SKU (Stock Keeping Unit) for inventory tracking

```
sku: "sku_abc123"
```

**parent\_sku** string

info

Parent product SKU for variants or child products. Defaults to `sku` if not provided.

```
parent_sku: "sku_parent_xyz789"
```

**gtin** string

info

Global Trade Item Number for product identification

```
gtin: "1234567890123"
```

**mpn** string

info

Manufacturer Part Number assigned by the manufacturer

```
mpn: "MPN-EXAMPLE-001"
```

**ean** string

info

European Article Number for product barcoding

```
ean: "1234567890123"
```

**brand** string

info

Product brand or manufacturer name

```
brand: "Example Brand"
```

**type** string

info

Product type. Free-form string (e.g. "simple", "variable", "bundle", "subscription").

```
type: "simple"
```

**stock\_status** boolean | number | string recommended

info

Product availability, accepted in any of these forms:

* **boolean** — `true` (in stock) / `false` (out of stock)
* **number** — `> 0` = in stock, `0` or negative = out of stock
* **string** — the following (case-insensitive) are treated as **out of stock**: `0`, `no`, `nu`, `false`, `out of stock`, `sold out`, `unavailable`, `indisponibil`, `fara stoc`, `stoc epuizat`.

Any other value is treated as **in stock**. Defaults to `true` (in stock) if not provided.

```
stock_status: true
```

**stock\_location** string

info

Physical location or warehouse where product is stored

```
stock_location: "Example Warehouse"
```

**created\_at** number

info

Timestamp when product was added to inventory (milliseconds)

```
created_at: 1748505040077
```

**url** string

info

Direct URL to the product page

```
url: "https://example.com/products/prod_abc123"
```

**parent\_url** string

info

URL to the parent product page (for variants)

```
parent_url: "https://example.com/products/prod_parent_xyz789"
```

**image** string

info

Main product image URL

```
image: "https://example.com/cdn/prod_abc123-main.jpg"
```

**images** array

info

Array of additional product image URLs

```
images: [
  "https://example.com/cdn/prod_abc123-1.jpg",
  "https://example.com/cdn/prod_abc123-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: "Example Category", id: "cat_abc123" },
  { name: "Example Subcategory", id: "cat_xyz789" }
]
```

**coupons** array

info

Array of product-level coupons applied to this product. [**View complete Coupon Object documentation**](/objects/coupon.md)

**coupons\[0]** (object) - `required`

**name** string required

info

Coupon name or code.

```
name: "EXAMPLE_COUPON"
```

**value** number recommended

info

Coupon discount value.

```
value: 123.99
```

**tax\_included** boolean recommended

info

Whether coupon value includes taxes

```
tax_included: true
```

**tax\_percent** number recommended

info

Tax percentage for the coupon

```
tax_percent: 21
```

**id** string

info

Coupon internal identifier.

```
id: "cpn_abc123"
```

**type** string

info

Coupon type. Free-form string, use consistent naming (e.g. "LOYALTY", "SEASONAL", "FIRST\_ORDER", "SHIPPING").

```
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. Free-form key-value object. Use properties that match your product catalog and business needs.

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.

* IT & C
* Fashion
* Deco

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

```
properties: {
  color: ["black", "white"],
  size: "M",
  material: "cotton",
  fit: "regular", 
  season: "summer",
  collection: "2024_spring",
  care_instructions: "machine_wash"
}
```

```
properties: {
  color: ["natural", "oak"],
  dimensions: "120x80x75cm",
  material: ["wood", "metal"],
  style: "modern",
  room_type: ["living_room", "office"],
  assembly_required: "true"
}
```

**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

Include user identifiers whenever they are available — even a single email or phone number dramatically improves match rates for **Meta Advanced Matching**, **Google Enhanced Conversions** and **TikTok Advanced Matching**. [**View complete User Object documentation**](/objects/user.md)

**id** string recommended

info

Unique customer identifier in your system.

```
id: "cust_abc123"
```

**email** string recommended

info

Customer email address in plaintext. Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.

```
email: "example.customer@example.com"
```

**phone** string recommended

info

Customer phone number in E.164 format (plaintext). Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.

```
phone: "+10000000000"
```

**first\_name** string recommended

info

Customer first name

```
first_name: "Example First Name"
```

**last\_name** string recommended

info

Customer last name

```
last_name: "Example Last Name"
```

**country** string

info

Country name or ISO country code

```
country: "US"
```

**region** string recommended

info

State, province, or region name

```
region: "Example Region"
```

**city** string recommended

info

City or locality name

```
city: "Example City"
```

**street** string

info

Street address including number

```
street: "123 Sample Street"
```

**postal\_code** string

info

Postal code or ZIP code

```
postal_code: "00000"
```

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

* E-commerce Customer
* B2B Lead/Customer
* Subscription Service
* Content Platform

```
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"
}
```

```
properties: {
  company_size: "enterprise",
  industry: "fintech",
  job_title: "marketing_director",
  decision_maker: "true",
  budget_range: "50000-100000",
  lead_source: ["linkedin", "webinar"],
  qualification_status: "qualified",
  sales_stage: "proposal"
}
```

```
properties: {
  subscription_tier: "premium",
  billing_cycle: "annual",
  feature_usage: ["analytics", "reporting", "api"],
  trial_user: "false",
  renewal_date: "2025-06-30",
  support_level: "priority",
  usage_frequency: "daily"
}
```

```
properties: {
  content_preferences: ["technology", "business"],
  engagement_level: "high",
  newsletter_subscriber: "true",
  social_media_follower: "true",
  content_consumption: "premium",
  device_preference: ["mobile", "desktop"],
  timezone: "Example/Timezone"
}
```

## Examples[​](#Examples "Direct link to Examples")

The examples below show how to push `product_added_to_cart` for four common e-commerce niches — **Fashion**, **Electronics**, **Beauty** and **Home & Deco** — each with representative product attributes for that niche, including the `variant` property for product variants, plus an additional **Minimal** tab with only the required fields. DATA Reshape transforms any of these payloads into the correct shape for every connected destination: a GA4 `add_to_cart`, a Meta `AddToCart` (Pixel + Conversions API), a TikTok `AddToCart` (Pixel + Events API), plus equivalents in other connected destinations. You do not need to write platform-specific code.

* Fashion
* Electronics
* Beauty
* Home & Deco
* Minimal

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "product_added_to_cart",
    "value": 49.99,
    "currency": "USD",
    "exchange_rate": 1
  },
  "context": {
    "url": "https://example.com/products/cotton-tshirt-navy-m",
    "page_type": "product",
    "environment": "prod"
  },
  "products": [
    {
      "id": "prod_tshirt_navy_m",
      "parent_id": "prod_tshirt_model",
      "name": "Example Cotton T-Shirt - Navy / M",
      "parent_name": "Example Cotton T-Shirt",
      "price_base": 59.99,
      "price": 49.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Apparel",
      "sku": "sku_tshirt_navy_m",
      "parent_sku": "sku_tshirt_model",
      "gtin": "1234567890123",
      "mpn": "MPN-TSHIRT-001",
      "ean": "1234567890123",
      "brand": "Example Brand",
      "type": "variable",
      "stock_status": true,
      "stock_location": "Example Warehouse",
      "created_at": 1748505040077,
      "url": "https://example.com/products/cotton-tshirt-navy-m",
      "parent_url": "https://example.com/products/cotton-tshirt",
      "image": "https://example.com/cdn/tshirt-navy-main.jpg",
      "images": [
        "https://example.com/cdn/tshirt-navy-front.jpg",
        "https://example.com/cdn/tshirt-navy-back.jpg"
      ],
      "categories": [
        { "name": "Apparel", "id": "cat_apparel" },
        { "name": "T-Shirts", "id": "cat_tshirts" },
        { "name": "Men", "id": "cat_men" }
      ],
      "currency": "USD",
      "exchange_rate": 1,
      "coupons": [
        {
          "name": "EXAMPLE_SEASONAL",
          "value": 10.00,
          "tax_included": true,
          "tax_percent": 19,
          "type": "SEASONAL"
        }
      ],
      "properties": {
        "variant": "Navy / M",
        "color": "navy",
        "size": "M",
        "material": "100% cotton",
        "gender": "unisex",
        "fit": "regular",
        "season": "summer",
        "collection_drop": "essentials_2025",
        "sleeve_length": "short",
        "neckline": "crew",
        "care_instructions": "machine_wash_cold"
      }
    }
  ],
  "user": {
    "id": "cust_abc123",
    "email": "example.customer@example.com",
    "phone": "+10000000000",
    "first_name": "Example First Name",
    "last_name": "Example Last Name",
    "country": "US",
    "region": "Example Region",
    "city": "Example City",
    "street": "123 Sample Street",
    "postal_code": "00000",
    "orders_total_number": 3,
    "orders_canceled_number": 0,
    "orders_total_value": 215.50,
    "orders_refunded_value": 0,
    "predicted_value": 800.00,
    "created_at": 1640995200000,
    "properties": {
      "customer_segment": "returning",
      "acquisition_channel": "organic_search",
      "loyalty_tier": "silver",
      "preferred_categories": ["apparel", "accessories"]
    }
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "product_added_to_cart",
    "value": 249.99,
    "currency": "USD",
    "exchange_rate": 1
  },
  "context": {
    "url": "https://example.com/products/wireless-headphones-black",
    "page_type": "product",
    "environment": "prod"
  },
  "products": [
    {
      "id": "prod_headphones_black",
      "parent_id": "prod_headphones_model",
      "name": "Example Wireless Headphones - Black",
      "parent_name": "Example Wireless Headphones",
      "price_base": 299.99,
      "price": 249.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Electronics",
      "sku": "sku_headphones_black",
      "parent_sku": "sku_headphones_model",
      "gtin": "1234567890123",
      "mpn": "MPN-HEADPHONES-001",
      "ean": "1234567890123",
      "brand": "Example Brand",
      "type": "variable",
      "stock_status": true,
      "stock_location": "Example Warehouse",
      "created_at": 1748505040077,
      "url": "https://example.com/products/wireless-headphones-black",
      "parent_url": "https://example.com/products/wireless-headphones",
      "image": "https://example.com/cdn/headphones-black-main.jpg",
      "images": [
        "https://example.com/cdn/headphones-black-front.jpg",
        "https://example.com/cdn/headphones-black-side.jpg"
      ],
      "categories": [
        { "name": "Electronics", "id": "cat_electronics" },
        { "name": "Audio", "id": "cat_audio" },
        { "name": "Headphones", "id": "cat_headphones" }
      ],
      "currency": "USD",
      "exchange_rate": 1,
      "properties": {
        "variant": "Black",
        "color": "black",
        "connectivity": ["bluetooth", "wired"],
        "noise_cancellation": "active",
        "battery_life_hours": 30,
        "warranty_years": 2,
        "model_year": 2025,
        "energy_rating": "A+",
        "wireless_range_meters": 10,
        "weight_grams": 250
      }
    }
  ],
  "user": {
    "id": "cust_abc123",
    "email": "example.customer@example.com",
    "phone": "+10000000000",
    "first_name": "Example First Name",
    "last_name": "Example Last Name",
    "country": "US",
    "region": "Example Region",
    "city": "Example City",
    "street": "123 Sample Street",
    "postal_code": "00000",
    "orders_total_number": 5,
    "orders_canceled_number": 0,
    "orders_total_value": 1240.00,
    "orders_refunded_value": 0,
    "predicted_value": 2500.00,
    "created_at": 1640995200000,
    "properties": {
      "customer_segment": "tech_enthusiast",
      "acquisition_channel": "paid_search",
      "loyalty_tier": "gold",
      "preferred_categories": ["electronics", "audio"]
    }
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "product_added_to_cart",
    "value": 34.99,
    "currency": "USD",
    "exchange_rate": 1
  },
  "context": {
    "url": "https://example.com/products/liquid-foundation-shade-04",
    "page_type": "product",
    "environment": "prod"
  },
  "products": [
    {
      "id": "prod_foundation_shade04",
      "parent_id": "prod_foundation_model",
      "name": "Example Liquid Foundation - Shade 04 / 30ml",
      "parent_name": "Example Liquid Foundation",
      "price_base": 39.99,
      "price": 34.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Beauty",
      "sku": "sku_foundation_shade04_30ml",
      "parent_sku": "sku_foundation_model",
      "gtin": "1234567890123",
      "mpn": "MPN-FOUNDATION-001",
      "ean": "1234567890123",
      "brand": "Example Brand",
      "type": "variable",
      "stock_status": true,
      "stock_location": "Example Warehouse",
      "created_at": 1748505040077,
      "url": "https://example.com/products/liquid-foundation-shade-04",
      "parent_url": "https://example.com/products/liquid-foundation",
      "image": "https://example.com/cdn/foundation-shade04-main.jpg",
      "images": [
        "https://example.com/cdn/foundation-shade04-bottle.jpg",
        "https://example.com/cdn/foundation-shade04-swatch.jpg"
      ],
      "categories": [
        { "name": "Beauty", "id": "cat_beauty" },
        { "name": "Makeup", "id": "cat_makeup" },
        { "name": "Foundation", "id": "cat_foundation" }
      ],
      "currency": "USD",
      "exchange_rate": 1,
      "properties": {
        "variant": "Shade 04 / 30ml",
        "shade": "shade_04_warm_beige",
        "volume_ml": 30,
        "skin_type": ["normal", "combination"],
        "finish": "matte",
        "coverage": "medium_to_full",
        "spf": 15,
        "formulation": "vegan",
        "fragrance_free": true,
        "cruelty_free": true,
        "ingredients_highlight": ["hyaluronic_acid", "niacinamide"]
      }
    }
  ],
  "user": {
    "id": "cust_abc123",
    "email": "example.customer@example.com",
    "phone": "+10000000000",
    "first_name": "Example First Name",
    "last_name": "Example Last Name",
    "country": "US",
    "region": "Example Region",
    "city": "Example City",
    "street": "123 Sample Street",
    "postal_code": "00000",
    "orders_total_number": 8,
    "orders_canceled_number": 1,
    "orders_total_value": 412.30,
    "orders_refunded_value": 39.99,
    "predicted_value": 1200.00,
    "created_at": 1640995200000,
    "properties": {
      "customer_segment": "beauty_enthusiast",
      "acquisition_channel": "social_paid",
      "loyalty_tier": "gold",
      "preferred_categories": ["beauty", "skincare"]
    }
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "product_added_to_cart",
    "value": 189.99,
    "currency": "USD",
    "exchange_rate": 1
  },
  "context": {
    "url": "https://example.com/products/floor-lamp-brass",
    "page_type": "product",
    "environment": "prod"
  },
  "products": [
    {
      "id": "prod_lamp_brass",
      "parent_id": "prod_lamp_model",
      "name": "Example Floor Lamp - Brass",
      "parent_name": "Example Floor Lamp",
      "price_base": 229.99,
      "price": 189.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Home & Living",
      "sku": "sku_lamp_brass",
      "parent_sku": "sku_lamp_model",
      "gtin": "1234567890123",
      "mpn": "MPN-LAMP-001",
      "ean": "1234567890123",
      "brand": "Example Brand",
      "type": "variable",
      "stock_status": true,
      "stock_location": "Example Warehouse",
      "created_at": 1748505040077,
      "url": "https://example.com/products/floor-lamp-brass",
      "parent_url": "https://example.com/products/floor-lamp",
      "image": "https://example.com/cdn/lamp-brass-main.jpg",
      "images": [
        "https://example.com/cdn/lamp-brass-living-room.jpg",
        "https://example.com/cdn/lamp-brass-detail.jpg"
      ],
      "categories": [
        { "name": "Home & Living", "id": "cat_home" },
        { "name": "Lighting", "id": "cat_lighting" },
        { "name": "Floor Lamps", "id": "cat_floor_lamps" }
      ],
      "currency": "USD",
      "exchange_rate": 1,
      "properties": {
        "variant": "Brass",
        "color": "brass",
        "material": ["metal", "fabric"],
        "dimensions_cm": "30x30x150",
        "weight_kg": 4.5,
        "style": "mid_century",
        "room_type": ["living_room", "bedroom"],
        "finish": "brushed",
        "assembly_required": true,
        "bulb_included": false,
        "wattage_max": 60,
        "cord_length_cm": 200
      }
    }
  ],
  "user": {
    "id": "cust_abc123",
    "email": "example.customer@example.com",
    "phone": "+10000000000",
    "first_name": "Example First Name",
    "last_name": "Example Last Name",
    "country": "US",
    "region": "Example Region",
    "city": "Example City",
    "street": "123 Sample Street",
    "postal_code": "00000",
    "orders_total_number": 2,
    "orders_canceled_number": 0,
    "orders_total_value": 540.00,
    "orders_refunded_value": 0,
    "predicted_value": 1500.00,
    "created_at": 1640995200000,
    "properties": {
      "customer_segment": "home_decorator",
      "acquisition_channel": "pinterest_organic",
      "loyalty_tier": "silver",
      "preferred_categories": ["home", "lighting"]
    }
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "product_added_to_cart",
    "value": 249.99,
    "currency": "USD"
  },
  "products": [
    {
      "id": "prod_abc123",
      "name": "Example Product Name",
      "brand": "Example Brand",
      "price_base": 299.99,
      "price": 249.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Example Category"
    }
  ]
});
```

Custom properties

Custom properties (`event.properties`, `user.properties`, `products[*].properties`) are **fully processed server-side**. On **browser-side** pixels and tags, only a subset may be available. Server-side processing can also enrich the outgoing payload with additional parameters derived from context and data quality.

## Best Practices[​](#Best-Practices "Direct link to Best Practices")

* **Fire only on confirmed addition** — never fire on button click before the cart state is updated. A failed addition (out of stock, validation error, server timeout) would inflate add-to-cart counts and pollute cart-abandonment audiences.
* **One event per addition action** — fire once per distinct "add to cart" action with `quantity` set to the number of units added now, not the cumulative cart total for that SKU.
* **Use the same `id` as in `product_viewed`** — consistent product IDs across the funnel are what enables GA4, Meta and TikTok to compute view-to-cart conversion rates and build product-affinity audiences.
* **`event.value` = price × quantity** — Meta `AddToCart`, GA4 `add_to_cart` and TikTok `AddToCart` use this for cart-value optimization and value-based lookalikes.
* **Include the `user` object** — even a single email dramatically improves match rates for Meta Advanced Matching, Google Enhanced Conversions and TikTok Advanced Matching, and enables similar audience-based flows in other connected destinations.
* **Currency consistency** — keep `event.currency` aligned with your store's display currency; override `currency` on `products[0]` only when an individual product is priced in a different currency.


---

# Product Added to Wishlist

Fire the **`product_added_to_wishlist`** event when a visitor saves a product for later — typically by clicking a "heart", "save", "favorite", or "add to wishlist" button on a product card or product detail page. This signals strong purchase intent without immediate buying, which makes it valuable for retargeting and price-drop notification flows.

Fire the event once per save action, after the wishlist state is confirmed updated. Do not fire it on button click alone, because validation errors (login required, server timeout) would inflate the count. Fire one event per product saved, with `products[0].quantity` set to 1 (wishlist additions are per-item, not quantity-based).

This event is the DATA Reshape equivalent of the standard add-to-wishlist event in every major advertising and analytics platform — push it once and Reshape fans it out to every connected destination with the correct platform-specific name and field mapping, so you do not need to fire `gtag`, `fbq`, `ttq` or other tracking function calls in parallel.

* **Google Analytics 4** — `add_to_wishlist` (with `items`, `value`, `currency`).
* **Meta Pixel / Meta Conversions API** — `AddToWishlist` (with `content_ids`, `content_type`, `value`, `currency`).
* **TikTok Pixel / TikTok Events API** — `AddToWishlist` (with `content_id`, `value`, `currency`).
* **Other connected destinations** — mapped automatically based on each destination's native schema.

One push, many native events

A single Reshape event can produce **one or more native events per destination**, with different characteristics depending on each website's destination configuration (active pixels, server endpoints, event-mapping rules).

## Complete Reference[​](#Complete-Reference "Direct link to Complete Reference")

The `product_added_to_wishlist` event accepts the following objects and fields. Required fields must always be present in the payload — everything else is optional but strongly recommended.

**event** object required

**name** string required

info

Use only static value **product\_added\_to\_wishlist** for `event.name`. DATA Reshape maps this to `add_to_wishlist` (GA4) and `AddToWishlist` (Meta, TikTok) automatically.

```
name: "product_added_to_wishlist"
```

**value** number required

info

Current price of the saved product.

```
value: 49.99
```

**currency** string required

info

Currency code for all monetary values in this event, ISO 4217 three-letter format.

```
currency: "USD"
```

**exchange\_rate** number

info

Custom exchange rate for multi-currency. Default is 1.

```
exchange_rate: 1
```

**id** string

info

Optional event identifier.

```
id: "evt_wishlist_abc123"
```

**context** object

info

[**View complete Context Object documentation**](/objects/context-web.md)

**url** string required-if-applicable

info

Collected automatically for standard websites. Required only for SPA applications where URL changes don't trigger automatic page context updates.

```
url:"https://example.com/products/prod_abc123?utm_source=example"
```

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

Array containing the product being saved (one item per event). Use the same `id` as in `product_viewed` and `product_added_to_cart` so destinations can correlate intent signals. [**View complete Product Object documentation**](/objects/product.md)

**products\[0]** object required

**id** string required

info

Unique product identifier in your system.

```
id: "prod_abc123"
```

**parent\_id** string recommended

info

Parent product ID for variants or child products. Defaults to `id` if not provided.

```
parent_id: "prod_parent_xyz789"
```

**name** string required

info

Product name or title displayed to users.

```
name: "Example Product Name"
```

**parent\_name** string

info

Parent product name for variants or child products. Defaults to `name` if not provided.

```
parent_name: "Example Parent Product Name"
```

**price\_base** number required

info

Original or base price before discounts. Always equal to or greater than `price`.

```
price_base: 299.99
```

**price** number required

info

Current selling price after discounts. Always equal to or less than `price_base`.

```
price: 249.99
```

**tax\_included** boolean required

info

Whether the price includes taxes. Defaults to `true` if not provided.

```
tax_included: true
```

**tax\_percent** number required

info

Tax percentage applied to the product (0-50). If not provided, the site default tax rate will be used (generally the standard rate of the country).

```
tax_percent: 19
```

**quantity** number required

info

Quantity of this product in the context of the event. Defaults to 1 if not provided.

```
quantity: 2
```

**category** string recommended

info

Main product category name

```
category: "Example Category"
```

**sku** string

info

Product SKU (Stock Keeping Unit) for inventory tracking

```
sku: "sku_abc123"
```

**parent\_sku** string

info

Parent product SKU for variants or child products. Defaults to `sku` if not provided.

```
parent_sku: "sku_parent_xyz789"
```

**gtin** string

info

Global Trade Item Number for product identification

```
gtin: "1234567890123"
```

**mpn** string

info

Manufacturer Part Number assigned by the manufacturer

```
mpn: "MPN-EXAMPLE-001"
```

**ean** string

info

European Article Number for product barcoding

```
ean: "1234567890123"
```

**brand** string

info

Product brand or manufacturer name

```
brand: "Example Brand"
```

**type** string

info

Product type. Free-form string (e.g. "simple", "variable", "bundle", "subscription").

```
type: "simple"
```

**stock\_status** boolean | number | string recommended

info

Product availability, accepted in any of these forms:

* **boolean** — `true` (in stock) / `false` (out of stock)
* **number** — `> 0` = in stock, `0` or negative = out of stock
* **string** — the following (case-insensitive) are treated as **out of stock**: `0`, `no`, `nu`, `false`, `out of stock`, `sold out`, `unavailable`, `indisponibil`, `fara stoc`, `stoc epuizat`.

Any other value is treated as **in stock**. Defaults to `true` (in stock) if not provided.

```
stock_status: true
```

**stock\_location** string

info

Physical location or warehouse where product is stored

```
stock_location: "Example Warehouse"
```

**created\_at** number

info

Timestamp when product was added to inventory (milliseconds)

```
created_at: 1748505040077
```

**url** string

info

Direct URL to the product page

```
url: "https://example.com/products/prod_abc123"
```

**parent\_url** string

info

URL to the parent product page (for variants)

```
parent_url: "https://example.com/products/prod_parent_xyz789"
```

**image** string

info

Main product image URL

```
image: "https://example.com/cdn/prod_abc123-main.jpg"
```

**images** array

info

Array of additional product image URLs

```
images: [
  "https://example.com/cdn/prod_abc123-1.jpg",
  "https://example.com/cdn/prod_abc123-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: "Example Category", id: "cat_abc123" },
  { name: "Example Subcategory", id: "cat_xyz789" }
]
```

**coupons** array

info

Array of product-level coupons applied to this product. [**View complete Coupon Object documentation**](/objects/coupon.md)

**coupons\[0]** (object) - `required`

**name** string required

info

Coupon name or code.

```
name: "EXAMPLE_COUPON"
```

**value** number recommended

info

Coupon discount value.

```
value: 123.99
```

**tax\_included** boolean recommended

info

Whether coupon value includes taxes

```
tax_included: true
```

**tax\_percent** number recommended

info

Tax percentage for the coupon

```
tax_percent: 21
```

**id** string

info

Coupon internal identifier.

```
id: "cpn_abc123"
```

**type** string

info

Coupon type. Free-form string, use consistent naming (e.g. "LOYALTY", "SEASONAL", "FIRST\_ORDER", "SHIPPING").

```
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. Free-form key-value object. Use properties that match your product catalog and business needs.

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.

* IT & C
* Fashion
* Deco

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

```
properties: {
  color: ["black", "white"],
  size: "M",
  material: "cotton",
  fit: "regular", 
  season: "summer",
  collection: "2024_spring",
  care_instructions: "machine_wash"
}
```

```
properties: {
  color: ["natural", "oak"],
  dimensions: "120x80x75cm",
  material: ["wood", "metal"],
  style: "modern",
  room_type: ["living_room", "office"],
  assembly_required: "true"
}
```

**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**](/objects/user.md)

**id** string recommended

info

Unique customer identifier in your system.

```
id: "cust_abc123"
```

**email** string recommended

info

Customer email address in plaintext. Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.

```
email: "example.customer@example.com"
```

**phone** string recommended

info

Customer phone number in E.164 format (plaintext). Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.

```
phone: "+10000000000"
```

**first\_name** string recommended

info

Customer first name

```
first_name: "Example First Name"
```

**last\_name** string recommended

info

Customer last name

```
last_name: "Example Last Name"
```

**country** string

info

Country name or ISO country code

```
country: "US"
```

**region** string recommended

info

State, province, or region name

```
region: "Example Region"
```

**city** string recommended

info

City or locality name

```
city: "Example City"
```

**street** string

info

Street address including number

```
street: "123 Sample Street"
```

**postal\_code** string

info

Postal code or ZIP code

```
postal_code: "00000"
```

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

* E-commerce Customer
* B2B Lead/Customer
* Subscription Service
* Content Platform

```
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"
}
```

```
properties: {
  company_size: "enterprise",
  industry: "fintech",
  job_title: "marketing_director",
  decision_maker: "true",
  budget_range: "50000-100000",
  lead_source: ["linkedin", "webinar"],
  qualification_status: "qualified",
  sales_stage: "proposal"
}
```

```
properties: {
  subscription_tier: "premium",
  billing_cycle: "annual",
  feature_usage: ["analytics", "reporting", "api"],
  trial_user: "false",
  renewal_date: "2025-06-30",
  support_level: "priority",
  usage_frequency: "daily"
}
```

```
properties: {
  content_preferences: ["technology", "business"],
  engagement_level: "high",
  newsletter_subscriber: "true",
  social_media_follower: "true",
  content_consumption: "premium",
  device_preference: ["mobile", "desktop"],
  timezone: "Example/Timezone"
}
```

## Examples[​](#Examples "Direct link to Examples")

The examples below show how to push `product_added_to_wishlist` for four common e-commerce niches — **Fashion**, **Electronics**, **Beauty** and **Home & Deco** — each with representative product attributes for that niche, plus an additional **Minimal** tab with only the required fields.

* Fashion
* Electronics
* Beauty
* Home & Deco
* Minimal

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "product_added_to_wishlist",
    "value": 49.99,
    "currency": "USD",
    "exchange_rate": 1
  },
  "context": {
    "url": "https://example.com/products/cotton-tshirt-navy-m",
    "page_type": "product",
    "environment": "prod"
  },
  "products": [
    {
      "id": "prod_tshirt_navy_m",
      "parent_id": "prod_tshirt_model",
      "name": "Example Cotton T-Shirt - Navy / M",
      "parent_name": "Example Cotton T-Shirt",
      "price_base": 59.99,
      "price": 49.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Apparel",
      "sku": "sku_tshirt_navy_m",
      "parent_sku": "sku_tshirt_model",
      "brand": "Example Brand",
      "type": "variable",
      "stock_status": true,
      "url": "https://example.com/products/cotton-tshirt-navy-m",
      "image": "https://example.com/cdn/tshirt-navy-main.jpg",
      "properties": {
        "variant": "Navy / M",
        "color": "navy",
        "size": "M",
        "material": "100% cotton",
        "fit": "regular",
        "season": "summer"
      }
    }
  ],
  "user": {
    "email": "example.customer@example.com",
    "country": "US"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "product_added_to_wishlist",
    "value": 249.99,
    "currency": "USD",
    "exchange_rate": 1
  },
  "context": {
    "url": "https://example.com/products/wireless-headphones-black",
    "page_type": "product",
    "environment": "prod"
  },
  "products": [
    {
      "id": "prod_headphones_black",
      "parent_id": "prod_headphones_model",
      "name": "Example Wireless Headphones - Black",
      "parent_name": "Example Wireless Headphones",
      "price_base": 299.99,
      "price": 249.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Electronics",
      "sku": "sku_headphones_black",
      "parent_sku": "sku_headphones_model",
      "brand": "Example Brand",
      "type": "variable",
      "stock_status": true,
      "url": "https://example.com/products/wireless-headphones-black",
      "image": "https://example.com/cdn/headphones-black-main.jpg",
      "properties": {
        "variant": "Black",
        "color": "black",
        "connectivity": ["bluetooth", "wired"],
        "battery_life_hours": 30
      }
    }
  ],
  "user": {
    "email": "example.customer@example.com",
    "country": "US"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "product_added_to_wishlist",
    "value": 34.99,
    "currency": "USD",
    "exchange_rate": 1
  },
  "context": {
    "url": "https://example.com/products/liquid-foundation-shade-04",
    "page_type": "product",
    "environment": "prod"
  },
  "products": [
    {
      "id": "prod_foundation_shade04",
      "parent_id": "prod_foundation_model",
      "name": "Example Liquid Foundation - Shade 04 / 30ml",
      "parent_name": "Example Liquid Foundation",
      "price_base": 39.99,
      "price": 34.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Beauty",
      "sku": "sku_foundation_shade04_30ml",
      "parent_sku": "sku_foundation_model",
      "brand": "Example Brand",
      "type": "variable",
      "stock_status": true,
      "url": "https://example.com/products/liquid-foundation-shade-04",
      "image": "https://example.com/cdn/foundation-shade04-main.jpg",
      "properties": {
        "variant": "Shade 04 / 30ml",
        "shade": "shade_04_warm_beige",
        "volume_ml": 30,
        "finish": "matte",
        "spf": 15
      }
    }
  ],
  "user": {
    "email": "example.customer@example.com",
    "country": "US"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "product_added_to_wishlist",
    "value": 189.99,
    "currency": "USD",
    "exchange_rate": 1
  },
  "context": {
    "url": "https://example.com/products/floor-lamp-brass",
    "page_type": "product",
    "environment": "prod"
  },
  "products": [
    {
      "id": "prod_lamp_brass",
      "parent_id": "prod_lamp_model",
      "name": "Example Floor Lamp - Brass",
      "parent_name": "Example Floor Lamp",
      "price_base": 229.99,
      "price": 189.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Home & Living",
      "sku": "sku_lamp_brass",
      "parent_sku": "sku_lamp_model",
      "brand": "Example Brand",
      "type": "variable",
      "stock_status": true,
      "url": "https://example.com/products/floor-lamp-brass",
      "image": "https://example.com/cdn/lamp-brass-main.jpg",
      "properties": {
        "variant": "Brass",
        "color": "brass",
        "material": ["metal", "fabric"],
        "style": "mid_century",
        "room_type": ["living_room", "bedroom"]
      }
    }
  ],
  "user": {
    "email": "example.customer@example.com",
    "country": "US"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "product_added_to_wishlist",
    "value": 49.99,
    "currency": "USD"
  },
  "products": [
    {
      "id": "prod_abc123",
      "name": "Example Product Name",
      "brand": "Example Brand",
      "price_base": 59.99,
      "price": 49.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Example Category"
    }
  ]
});
```

Custom properties

Custom properties (`event.properties`, `user.properties`, `products[*].properties`) are **fully processed server-side**. On **browser-side** pixels and tags, only a subset may be available. Server-side processing can also enrich the outgoing payload with additional parameters derived from context and data quality.

## Best Practices[​](#Best-Practices "Direct link to Best Practices")

* **Fire only on confirmed save** — never fire on button click before the wishlist state is updated.
* **One event per save action** — fire once per distinct save with `quantity: 1`.
* **Use consistent product IDs** — same `products[*].id` as in `product_viewed` and `product_added_to_cart`.
* **Include the `user` object** — wishlist signals are most valuable when tied to a known identity (email), enabling back-in-stock and price-drop flows in connected destinations.


---

# Product Removed from Cart

Fire the **`product_removed_from_cart`** event when a visitor removes a product from their shopping cart — via a "remove" button, quantity decrease to zero, or cart cleanup action. This event is the inverse of `product_added_to_cart` and helps identify products that experience high cart-removal rates (a signal of pricing, shipping or trust issues).

Fire the event once per removal action, after the cart state is confirmed updated. Fire one event per product removed, with `products[0].quantity` set to the number of units removed in this specific action.

This event is the DATA Reshape equivalent of the standard remove-from-cart event in every major advertising and analytics platform — push it once and Reshape fans it out to every connected destination with the correct platform-specific name and field mapping, so you do not need to fire `gtag`, `fbq`, `ttq` or other tracking function calls in parallel.

* **Google Analytics 4** — `remove_from_cart` (with `items`, `value`, `currency`).
* **Meta, TikTok** — no dedicated standard event; Reshape can send a custom CamelCase event when connected.
* **Other connected destinations** — mapped automatically based on each destination's native schema.

One push, many native events

A single Reshape event can produce **one or more native events per destination**, with different characteristics depending on each website's destination configuration (active pixels, server endpoints, event-mapping rules).

## Complete Reference[​](#Complete-Reference "Direct link to Complete Reference")

The `product_removed_from_cart` event accepts the following objects and fields. Required fields must always be present in the payload — everything else is optional but strongly recommended.

**event** object required

**name** string required

info

Use only static value **product\_removed\_from\_cart** for `event.name`. DATA Reshape maps this to `remove_from_cart` (GA4) automatically; Meta and TikTok receive a custom CamelCase event `RemoveFromCart` when connected.

```
name: "product_removed_from_cart"
```

**value** number required

info

Total value removed (price × quantity).

```
value: 49.99
```

**currency** string required

info

Currency code, ISO 4217 three-letter format.

```
currency: "USD"
```

**exchange\_rate** number

info

Default is 1.

```
exchange_rate: 1
```

**id** string

info

Optional event identifier.

```
id: "evt_remove_abc123"
```

**context** object

info

[**View complete Context Object documentation**](/objects/context-web.md)

**url** string required-if-applicable

info

Collected automatically for standard websites. Required only for SPA applications where URL changes don't trigger automatic page context updates.

```
url:"https://example.com/products/prod_abc123?utm_source=example"
```

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

Array containing the product being removed, with `quantity` set to the number of units removed in this action. [**View complete Product Object documentation**](/objects/product.md)

**products\[0]** object required

**id** string required

info

Unique product identifier in your system.

```
id: "prod_abc123"
```

**parent\_id** string recommended

info

Parent product ID for variants or child products. Defaults to `id` if not provided.

```
parent_id: "prod_parent_xyz789"
```

**name** string required

info

Product name or title displayed to users.

```
name: "Example Product Name"
```

**parent\_name** string

info

Parent product name for variants or child products. Defaults to `name` if not provided.

```
parent_name: "Example Parent Product Name"
```

**price\_base** number required

info

Original or base price before discounts. Always equal to or greater than `price`.

```
price_base: 299.99
```

**price** number required

info

Current selling price after discounts. Always equal to or less than `price_base`.

```
price: 249.99
```

**tax\_included** boolean required

info

Whether the price includes taxes. Defaults to `true` if not provided.

```
tax_included: true
```

**tax\_percent** number required

info

Tax percentage applied to the product (0-50). If not provided, the site default tax rate will be used (generally the standard rate of the country).

```
tax_percent: 19
```

**quantity** number required

info

Quantity of this product in the context of the event. Defaults to 1 if not provided.

```
quantity: 2
```

**category** string recommended

info

Main product category name

```
category: "Example Category"
```

**sku** string

info

Product SKU (Stock Keeping Unit) for inventory tracking

```
sku: "sku_abc123"
```

**parent\_sku** string

info

Parent product SKU for variants or child products. Defaults to `sku` if not provided.

```
parent_sku: "sku_parent_xyz789"
```

**gtin** string

info

Global Trade Item Number for product identification

```
gtin: "1234567890123"
```

**mpn** string

info

Manufacturer Part Number assigned by the manufacturer

```
mpn: "MPN-EXAMPLE-001"
```

**ean** string

info

European Article Number for product barcoding

```
ean: "1234567890123"
```

**brand** string

info

Product brand or manufacturer name

```
brand: "Example Brand"
```

**type** string

info

Product type. Free-form string (e.g. "simple", "variable", "bundle", "subscription").

```
type: "simple"
```

**stock\_status** boolean | number | string recommended

info

Product availability, accepted in any of these forms:

* **boolean** — `true` (in stock) / `false` (out of stock)
* **number** — `> 0` = in stock, `0` or negative = out of stock
* **string** — the following (case-insensitive) are treated as **out of stock**: `0`, `no`, `nu`, `false`, `out of stock`, `sold out`, `unavailable`, `indisponibil`, `fara stoc`, `stoc epuizat`.

Any other value is treated as **in stock**. Defaults to `true` (in stock) if not provided.

```
stock_status: true
```

**stock\_location** string

info

Physical location or warehouse where product is stored

```
stock_location: "Example Warehouse"
```

**created\_at** number

info

Timestamp when product was added to inventory (milliseconds)

```
created_at: 1748505040077
```

**url** string

info

Direct URL to the product page

```
url: "https://example.com/products/prod_abc123"
```

**parent\_url** string

info

URL to the parent product page (for variants)

```
parent_url: "https://example.com/products/prod_parent_xyz789"
```

**image** string

info

Main product image URL

```
image: "https://example.com/cdn/prod_abc123-main.jpg"
```

**images** array

info

Array of additional product image URLs

```
images: [
  "https://example.com/cdn/prod_abc123-1.jpg",
  "https://example.com/cdn/prod_abc123-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: "Example Category", id: "cat_abc123" },
  { name: "Example Subcategory", id: "cat_xyz789" }
]
```

**coupons** array

info

Array of product-level coupons applied to this product. [**View complete Coupon Object documentation**](/objects/coupon.md)

**coupons\[0]** (object) - `required`

**name** string required

info

Coupon name or code.

```
name: "EXAMPLE_COUPON"
```

**value** number recommended

info

Coupon discount value.

```
value: 123.99
```

**tax\_included** boolean recommended

info

Whether coupon value includes taxes

```
tax_included: true
```

**tax\_percent** number recommended

info

Tax percentage for the coupon

```
tax_percent: 21
```

**id** string

info

Coupon internal identifier.

```
id: "cpn_abc123"
```

**type** string

info

Coupon type. Free-form string, use consistent naming (e.g. "LOYALTY", "SEASONAL", "FIRST\_ORDER", "SHIPPING").

```
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. Free-form key-value object. Use properties that match your product catalog and business needs.

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.

* IT & C
* Fashion
* Deco

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

```
properties: {
  color: ["black", "white"],
  size: "M",
  material: "cotton",
  fit: "regular", 
  season: "summer",
  collection: "2024_spring",
  care_instructions: "machine_wash"
}
```

```
properties: {
  color: ["natural", "oak"],
  dimensions: "120x80x75cm",
  material: ["wood", "metal"],
  style: "modern",
  room_type: ["living_room", "office"],
  assembly_required: "true"
}
```

**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**](/objects/user.md)

**id** string recommended

info

Unique customer identifier in your system.

```
id: "cust_abc123"
```

**email** string recommended

info

Customer email address in plaintext. Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.

```
email: "example.customer@example.com"
```

**phone** string recommended

info

Customer phone number in E.164 format (plaintext). Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.

```
phone: "+10000000000"
```

**first\_name** string recommended

info

Customer first name

```
first_name: "Example First Name"
```

**last\_name** string recommended

info

Customer last name

```
last_name: "Example Last Name"
```

**country** string

info

Country name or ISO country code

```
country: "US"
```

**region** string recommended

info

State, province, or region name

```
region: "Example Region"
```

**city** string recommended

info

City or locality name

```
city: "Example City"
```

**street** string

info

Street address including number

```
street: "123 Sample Street"
```

**postal\_code** string

info

Postal code or ZIP code

```
postal_code: "00000"
```

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

* E-commerce Customer
* B2B Lead/Customer
* Subscription Service
* Content Platform

```
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"
}
```

```
properties: {
  company_size: "enterprise",
  industry: "fintech",
  job_title: "marketing_director",
  decision_maker: "true",
  budget_range: "50000-100000",
  lead_source: ["linkedin", "webinar"],
  qualification_status: "qualified",
  sales_stage: "proposal"
}
```

```
properties: {
  subscription_tier: "premium",
  billing_cycle: "annual",
  feature_usage: ["analytics", "reporting", "api"],
  trial_user: "false",
  renewal_date: "2025-06-30",
  support_level: "priority",
  usage_frequency: "daily"
}
```

```
properties: {
  content_preferences: ["technology", "business"],
  engagement_level: "high",
  newsletter_subscriber: "true",
  social_media_follower: "true",
  content_consumption: "premium",
  device_preference: ["mobile", "desktop"],
  timezone: "Example/Timezone"
}
```

## Examples[​](#Examples "Direct link to Examples")

The examples below show how to push `product_removed_from_cart` for four common e-commerce niches — **Fashion**, **Electronics**, **Beauty** and **Home & Deco** — each with representative product attributes, plus an additional **Minimal** tab with only the required fields.

* Fashion
* Electronics
* Beauty
* Home & Deco
* Minimal

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "product_removed_from_cart",
    "value": 49.99,
    "currency": "USD",
    "exchange_rate": 1
  },
  "context": {
    "url": "https://example.com/cart",
    "page_type": "cart",
    "environment": "prod"
  },
  "products": [
    {
      "id": "prod_tshirt_navy_m",
      "parent_id": "prod_tshirt_model",
      "name": "Example Cotton T-Shirt - Navy / M",
      "parent_name": "Example Cotton T-Shirt",
      "price_base": 59.99,
      "price": 49.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Apparel",
      "sku": "sku_tshirt_navy_m",
      "parent_sku": "sku_tshirt_model",
      "brand": "Example Brand",
      "type": "variable",
      "url": "https://example.com/products/cotton-tshirt-navy-m",
      "image": "https://example.com/cdn/tshirt-navy-main.jpg",
      "properties": {
        "variant": "Navy / M",
        "color": "navy",
        "size": "M",
        "material": "100% cotton"
      }
    }
  ],
  "user": {
    "email": "example.customer@example.com",
    "country": "US"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "product_removed_from_cart",
    "value": 249.99,
    "currency": "USD",
    "exchange_rate": 1
  },
  "context": {
    "url": "https://example.com/cart",
    "page_type": "cart",
    "environment": "prod"
  },
  "products": [
    {
      "id": "prod_headphones_black",
      "parent_id": "prod_headphones_model",
      "name": "Example Wireless Headphones - Black",
      "parent_name": "Example Wireless Headphones",
      "price_base": 299.99,
      "price": 249.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Electronics",
      "sku": "sku_headphones_black",
      "parent_sku": "sku_headphones_model",
      "brand": "Example Brand",
      "type": "variable",
      "url": "https://example.com/products/wireless-headphones-black",
      "image": "https://example.com/cdn/headphones-black-main.jpg",
      "properties": {
        "variant": "Black",
        "color": "black",
        "connectivity": ["bluetooth", "wired"]
      }
    }
  ],
  "user": {
    "email": "example.customer@example.com",
    "country": "US"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "product_removed_from_cart",
    "value": 34.99,
    "currency": "USD",
    "exchange_rate": 1
  },
  "context": {
    "url": "https://example.com/cart",
    "page_type": "cart",
    "environment": "prod"
  },
  "products": [
    {
      "id": "prod_foundation_shade04",
      "parent_id": "prod_foundation_model",
      "name": "Example Liquid Foundation - Shade 04 / 30ml",
      "parent_name": "Example Liquid Foundation",
      "price_base": 39.99,
      "price": 34.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Beauty",
      "sku": "sku_foundation_shade04_30ml",
      "parent_sku": "sku_foundation_model",
      "brand": "Example Brand",
      "type": "variable",
      "url": "https://example.com/products/liquid-foundation-shade-04",
      "image": "https://example.com/cdn/foundation-shade04-main.jpg",
      "properties": {
        "variant": "Shade 04 / 30ml",
        "shade": "shade_04_warm_beige",
        "volume_ml": 30
      }
    }
  ],
  "user": {
    "email": "example.customer@example.com",
    "country": "US"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "product_removed_from_cart",
    "value": 189.99,
    "currency": "USD",
    "exchange_rate": 1
  },
  "context": {
    "url": "https://example.com/cart",
    "page_type": "cart",
    "environment": "prod"
  },
  "products": [
    {
      "id": "prod_lamp_brass",
      "parent_id": "prod_lamp_model",
      "name": "Example Floor Lamp - Brass",
      "parent_name": "Example Floor Lamp",
      "price_base": 229.99,
      "price": 189.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Home & Living",
      "sku": "sku_lamp_brass",
      "parent_sku": "sku_lamp_model",
      "brand": "Example Brand",
      "type": "variable",
      "url": "https://example.com/products/floor-lamp-brass",
      "image": "https://example.com/cdn/lamp-brass-main.jpg",
      "properties": {
        "variant": "Brass",
        "color": "brass",
        "material": ["metal", "fabric"]
      }
    }
  ],
  "user": {
    "email": "example.customer@example.com",
    "country": "US"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "product_removed_from_cart",
    "value": 49.99,
    "currency": "USD"
  },
  "products": [
    {
      "id": "prod_abc123",
      "name": "Example Product Name",
      "brand": "Example Brand",
      "price_base": 59.99,
      "price": 49.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Example Category"
    }
  ]
});
```

Custom properties

Custom properties (`event.properties`, `user.properties`, `products[*].properties`) are **fully processed server-side**. On **browser-side** pixels and tags, only a subset may be available. Server-side processing can also enrich the outgoing payload with additional parameters derived from context and data quality.

## Best Practices[​](#Best-Practices "Direct link to Best Practices")

* **Fire only on confirmed removal** — never fire on click before the cart state is updated.
* **One event per removal action** — fire once per distinct removal, with `quantity` set to units removed in this action.
* **Use consistent product IDs** — same `products[*].id` as in `product_added_to_cart`.
* **Useful for product diagnostics** — high removal rates on specific SKUs signal pricing, shipping or trust issues worth investigating.


---

# Product Viewed

Fire the **`product_viewed`** event when a visitor focuses on a specific product — for example, when they land on a product detail page, open a quick view modal, click a product in a "recently viewed" carousel, or otherwise make a single product the main focus of attention after a search or a filter action.

Do not fire `product_viewed` for products that appear in passive listings such as category grids, search result pages, or "related products" widgets — those are impressions, not views, and inflating them dilutes the quality of remarketing audiences. Fire it once per session for a given product, unless the user explicitly re-engages with it (for example by re-opening the product page from a different entry point).

This event is the DATA Reshape equivalent of the standard product-view event in every major advertising and analytics platform — push it once and Reshape fans it out to every connected destination with the correct platform-specific name and field mapping, so you do not need to fire `gtag`, `fbq`, `ttq` or other tracking function calls in parallel.

* **Google Analytics 4** — `view_item` (with `items` array and `currency`/`value`).
* **Google Ads** — dynamic remarketing product-view signal, used for personalized ad audiences.
* **Meta Pixel / Meta Conversions API** — `ViewContent` (with `content_ids`, `content_type`, `value`, `currency`).
* **TikTok Pixel / TikTok Events API** — `ViewContent` (with `content_id`, `content_type`, `value`, `currency`).
* **Other connected destinations** — mapped automatically based on each destination's native schema.

One push, many native events

A single Reshape event can produce **one or more native events per destination**, with different characteristics depending on each website's destination configuration (active pixels, server endpoints, event-mapping rules).

## Complete Reference[​](#Complete-Reference "Direct link to Complete Reference")

The `product_viewed` event accepts the following objects and fields. Required fields must always be present in the payload — everything else is optional but strongly recommended, because richer payloads produce better attribution, more accurate audience matching, and better-quality conversions across destinations like GA4 (`view_item`), Meta (`ViewContent`) and TikTok (`ViewContent`). The `products` array must contain exactly the product being viewed; the optional `user` object enables Advanced Matching for Meta and Enhanced Conversions for Google.

**event** object required

**name** string required

info

Use only static value **product\_viewed** for `event.name`. DATA Reshape maps this to `view_item` (GA4) and `ViewContent` (Meta, TikTok) automatically.

```
name: "product_viewed"
```

**value** number required

info

Current price of the viewed product. Used as the monetary value of the event in GA4 (`value`), Meta (`value`) and TikTok (`value`).

```
value: 249.99
```

**currency** string required

info

Currency code for all monetary values in this event, ISO 4217 three-letter format. Can be overridden in nested objects.

```
currency: "USD"
```

**exchange\_rate** number

info

Custom exchange rate for multi-currency. Default is 1.

```
exchange_rate: 1
```

**id** string

info

Optional event identifier. Useful for deduplication when the same view may be reported by multiple sources.

```
id: "evt_view_abc123"
```

**context** object

info

[**View complete Context Object documentation**](/objects/context-web.md)

**url** string required-if-applicable

info

Collected automatically for standard websites. Required only for SPA applications where URL changes don't trigger automatic page context updates.

```
url:"https://example.com/products/prod_abc123?utm_source=example"
```

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

Array containing the viewed product. For `product_viewed` the array should contain exactly one entry — the product the user is currently focused on. This is the same `products` array shape used in `product_added_to_cart`, `checkout_started` and `checkout_completed`, so the `id` must stay consistent across the funnel. [**View complete Product Object documentation**](/objects/product.md)

**products\[0]** object required

**id** string required

info

Unique product identifier in your system.

```
id: "prod_abc123"
```

**parent\_id** string recommended

info

Parent product ID for variants or child products. Defaults to `id` if not provided.

```
parent_id: "prod_parent_xyz789"
```

**name** string required

info

Product name or title displayed to users.

```
name: "Example Product Name"
```

**parent\_name** string

info

Parent product name for variants or child products. Defaults to `name` if not provided.

```
parent_name: "Example Parent Product Name"
```

**price\_base** number required

info

Original or base price before discounts. Always equal to or greater than `price`.

```
price_base: 299.99
```

**price** number required

info

Current selling price after discounts. Always equal to or less than `price_base`.

```
price: 249.99
```

**tax\_included** boolean required

info

Whether the price includes taxes. Defaults to `true` if not provided.

```
tax_included: true
```

**tax\_percent** number required

info

Tax percentage applied to the product (0-50). If not provided, the site default tax rate will be used (generally the standard rate of the country).

```
tax_percent: 19
```

**quantity** number required

info

Quantity of this product in the context of the event. Defaults to 1 if not provided.

```
quantity: 2
```

**category** string recommended

info

Main product category name

```
category: "Example Category"
```

**sku** string

info

Product SKU (Stock Keeping Unit) for inventory tracking

```
sku: "sku_abc123"
```

**parent\_sku** string

info

Parent product SKU for variants or child products. Defaults to `sku` if not provided.

```
parent_sku: "sku_parent_xyz789"
```

**gtin** string

info

Global Trade Item Number for product identification

```
gtin: "1234567890123"
```

**mpn** string

info

Manufacturer Part Number assigned by the manufacturer

```
mpn: "MPN-EXAMPLE-001"
```

**ean** string

info

European Article Number for product barcoding

```
ean: "1234567890123"
```

**brand** string

info

Product brand or manufacturer name

```
brand: "Example Brand"
```

**type** string

info

Product type. Free-form string (e.g. "simple", "variable", "bundle", "subscription").

```
type: "simple"
```

**stock\_status** boolean | number | string recommended

info

Product availability, accepted in any of these forms:

* **boolean** — `true` (in stock) / `false` (out of stock)
* **number** — `> 0` = in stock, `0` or negative = out of stock
* **string** — the following (case-insensitive) are treated as **out of stock**: `0`, `no`, `nu`, `false`, `out of stock`, `sold out`, `unavailable`, `indisponibil`, `fara stoc`, `stoc epuizat`.

Any other value is treated as **in stock**. Defaults to `true` (in stock) if not provided.

```
stock_status: true
```

**stock\_location** string

info

Physical location or warehouse where product is stored

```
stock_location: "Example Warehouse"
```

**created\_at** number

info

Timestamp when product was added to inventory (milliseconds)

```
created_at: 1748505040077
```

**url** string

info

Direct URL to the product page

```
url: "https://example.com/products/prod_abc123"
```

**parent\_url** string

info

URL to the parent product page (for variants)

```
parent_url: "https://example.com/products/prod_parent_xyz789"
```

**image** string

info

Main product image URL

```
image: "https://example.com/cdn/prod_abc123-main.jpg"
```

**images** array

info

Array of additional product image URLs

```
images: [
  "https://example.com/cdn/prod_abc123-1.jpg",
  "https://example.com/cdn/prod_abc123-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: "Example Category", id: "cat_abc123" },
  { name: "Example Subcategory", id: "cat_xyz789" }
]
```

**coupons** array

info

Array of product-level coupons applied to this product. [**View complete Coupon Object documentation**](/objects/coupon.md)

**coupons\[0]** (object) - `required`

**name** string required

info

Coupon name or code.

```
name: "EXAMPLE_COUPON"
```

**value** number recommended

info

Coupon discount value.

```
value: 123.99
```

**tax\_included** boolean recommended

info

Whether coupon value includes taxes

```
tax_included: true
```

**tax\_percent** number recommended

info

Tax percentage for the coupon

```
tax_percent: 21
```

**id** string

info

Coupon internal identifier.

```
id: "cpn_abc123"
```

**type** string

info

Coupon type. Free-form string, use consistent naming (e.g. "LOYALTY", "SEASONAL", "FIRST\_ORDER", "SHIPPING").

```
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. Free-form key-value object. Use properties that match your product catalog and business needs.

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.

* IT & C
* Fashion
* Deco

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

```
properties: {
  color: ["black", "white"],
  size: "M",
  material: "cotton",
  fit: "regular", 
  season: "summer",
  collection: "2024_spring",
  care_instructions: "machine_wash"
}
```

```
properties: {
  color: ["natural", "oak"],
  dimensions: "120x80x75cm",
  material: ["wood", "metal"],
  style: "modern",
  room_type: ["living_room", "office"],
  assembly_required: "true"
}
```

**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

Include user identifiers whenever they are available — even a single email or phone number dramatically improves match rates for **Meta Advanced Matching**, **Google Enhanced Conversions** and **TikTok Advanced Matching**. [**View complete User Object documentation**](/objects/user.md)

**id** string recommended

info

Unique customer identifier in your system.

```
id: "cust_abc123"
```

**email** string recommended

info

Customer email address in plaintext. Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.

```
email: "example.customer@example.com"
```

**phone** string recommended

info

Customer phone number in E.164 format (plaintext). Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.

```
phone: "+10000000000"
```

**first\_name** string recommended

info

Customer first name

```
first_name: "Example First Name"
```

**last\_name** string recommended

info

Customer last name

```
last_name: "Example Last Name"
```

**country** string

info

Country name or ISO country code

```
country: "US"
```

**region** string recommended

info

State, province, or region name

```
region: "Example Region"
```

**city** string recommended

info

City or locality name

```
city: "Example City"
```

**street** string

info

Street address including number

```
street: "123 Sample Street"
```

**postal\_code** string

info

Postal code or ZIP code

```
postal_code: "00000"
```

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

* E-commerce Customer
* B2B Lead/Customer
* Subscription Service
* Content Platform

```
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"
}
```

```
properties: {
  company_size: "enterprise",
  industry: "fintech",
  job_title: "marketing_director",
  decision_maker: "true",
  budget_range: "50000-100000",
  lead_source: ["linkedin", "webinar"],
  qualification_status: "qualified",
  sales_stage: "proposal"
}
```

```
properties: {
  subscription_tier: "premium",
  billing_cycle: "annual",
  feature_usage: ["analytics", "reporting", "api"],
  trial_user: "false",
  renewal_date: "2025-06-30",
  support_level: "priority",
  usage_frequency: "daily"
}
```

```
properties: {
  content_preferences: ["technology", "business"],
  engagement_level: "high",
  newsletter_subscriber: "true",
  social_media_follower: "true",
  content_consumption: "premium",
  device_preference: ["mobile", "desktop"],
  timezone: "Example/Timezone"
}
```

## Examples[​](#Examples "Direct link to Examples")

The examples below show how to push `product_viewed` for four common e-commerce niches — **Fashion**, **Electronics**, **Beauty** and **Home & Deco** — each with representative product attributes for that niche, including the `variant` property for product variants (color, size, shade, finish, etc.), plus an additional **Minimal** tab with only the required fields. DATA Reshape transforms any of these payloads into the correct shape for every connected destination: a GA4 `view_item`, a Meta `ViewContent` (Pixel + Conversions API), a TikTok `ViewContent` (Pixel + Events API), a Google Ads dynamic remarketing hit, plus equivalents in other connected destinations. You do not need to write platform-specific code.

* Fashion
* Electronics
* Beauty
* Home & Deco
* Minimal

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "product_viewed",
    "value": 49.99,
    "currency": "USD",
    "exchange_rate": 1
  },
  "context": {
    "url": "https://example.com/products/cotton-tshirt-navy-m",
    "page_type": "product",
    "environment": "prod"
  },
  "products": [
    {
      "id": "prod_tshirt_navy_m",
      "parent_id": "prod_tshirt_model",
      "name": "Example Cotton T-Shirt - Navy / M",
      "parent_name": "Example Cotton T-Shirt",
      "price_base": 59.99,
      "price": 49.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Apparel",
      "sku": "sku_tshirt_navy_m",
      "parent_sku": "sku_tshirt_model",
      "gtin": "1234567890123",
      "mpn": "MPN-TSHIRT-001",
      "ean": "1234567890123",
      "brand": "Example Brand",
      "type": "variable",
      "stock_status": true,
      "stock_location": "Example Warehouse",
      "created_at": 1748505040077,
      "url": "https://example.com/products/cotton-tshirt-navy-m",
      "parent_url": "https://example.com/products/cotton-tshirt",
      "image": "https://example.com/cdn/tshirt-navy-main.jpg",
      "images": [
        "https://example.com/cdn/tshirt-navy-front.jpg",
        "https://example.com/cdn/tshirt-navy-back.jpg"
      ],
      "categories": [
        { "name": "Apparel", "id": "cat_apparel" },
        { "name": "T-Shirts", "id": "cat_tshirts" },
        { "name": "Men", "id": "cat_men" }
      ],
      "currency": "USD",
      "exchange_rate": 1,
      "coupons": [
        {
          "name": "EXAMPLE_SEASONAL",
          "value": 10.00,
          "tax_included": true,
          "tax_percent": 19,
          "type": "SEASONAL"
        }
      ],
      "properties": {
        "variant": "Navy / M",
        "color": "navy",
        "size": "M",
        "material": "100% cotton",
        "gender": "unisex",
        "fit": "regular",
        "season": "summer",
        "collection_drop": "essentials_2025",
        "sleeve_length": "short",
        "neckline": "crew",
        "care_instructions": "machine_wash_cold"
      }
    }
  ],
  "user": {
    "id": "cust_abc123",
    "email": "example.customer@example.com",
    "phone": "+10000000000",
    "first_name": "Example First Name",
    "last_name": "Example Last Name",
    "country": "US",
    "region": "Example Region",
    "city": "Example City",
    "street": "123 Sample Street",
    "postal_code": "00000",
    "orders_total_number": 3,
    "orders_canceled_number": 0,
    "orders_total_value": 215.50,
    "orders_refunded_value": 0,
    "predicted_value": 800.00,
    "created_at": 1640995200000,
    "properties": {
      "customer_segment": "returning",
      "acquisition_channel": "organic_search",
      "loyalty_tier": "silver",
      "preferred_categories": ["apparel", "accessories"]
    }
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "product_viewed",
    "value": 249.99,
    "currency": "USD",
    "exchange_rate": 1
  },
  "context": {
    "url": "https://example.com/products/wireless-headphones-black",
    "page_type": "product",
    "environment": "prod"
  },
  "products": [
    {
      "id": "prod_headphones_black",
      "parent_id": "prod_headphones_model",
      "name": "Example Wireless Headphones - Black",
      "parent_name": "Example Wireless Headphones",
      "price_base": 299.99,
      "price": 249.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Electronics",
      "sku": "sku_headphones_black",
      "parent_sku": "sku_headphones_model",
      "gtin": "1234567890123",
      "mpn": "MPN-HEADPHONES-001",
      "ean": "1234567890123",
      "brand": "Example Brand",
      "type": "variable",
      "stock_status": true,
      "stock_location": "Example Warehouse",
      "created_at": 1748505040077,
      "url": "https://example.com/products/wireless-headphones-black",
      "parent_url": "https://example.com/products/wireless-headphones",
      "image": "https://example.com/cdn/headphones-black-main.jpg",
      "images": [
        "https://example.com/cdn/headphones-black-front.jpg",
        "https://example.com/cdn/headphones-black-side.jpg"
      ],
      "categories": [
        { "name": "Electronics", "id": "cat_electronics" },
        { "name": "Audio", "id": "cat_audio" },
        { "name": "Headphones", "id": "cat_headphones" }
      ],
      "currency": "USD",
      "exchange_rate": 1,
      "coupons": [
        {
          "name": "EXAMPLE_BUNDLE",
          "value": 50.00,
          "tax_included": true,
          "tax_percent": 19,
          "type": "BUNDLE"
        }
      ],
      "properties": {
        "variant": "Black",
        "color": "black",
        "connectivity": ["bluetooth", "wired"],
        "noise_cancellation": "active",
        "battery_life_hours": 30,
        "warranty_years": 2,
        "model_year": 2025,
        "energy_rating": "A+",
        "wireless_range_meters": 10,
        "weight_grams": 250
      }
    }
  ],
  "user": {
    "id": "cust_abc123",
    "email": "example.customer@example.com",
    "phone": "+10000000000",
    "first_name": "Example First Name",
    "last_name": "Example Last Name",
    "country": "US",
    "region": "Example Region",
    "city": "Example City",
    "street": "123 Sample Street",
    "postal_code": "00000",
    "orders_total_number": 5,
    "orders_canceled_number": 0,
    "orders_total_value": 1240.00,
    "orders_refunded_value": 0,
    "predicted_value": 2500.00,
    "created_at": 1640995200000,
    "properties": {
      "customer_segment": "tech_enthusiast",
      "acquisition_channel": "paid_search",
      "loyalty_tier": "gold",
      "preferred_categories": ["electronics", "audio"]
    }
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "product_viewed",
    "value": 34.99,
    "currency": "USD",
    "exchange_rate": 1
  },
  "context": {
    "url": "https://example.com/products/liquid-foundation-shade-04",
    "page_type": "product",
    "environment": "prod"
  },
  "products": [
    {
      "id": "prod_foundation_shade04",
      "parent_id": "prod_foundation_model",
      "name": "Example Liquid Foundation - Shade 04 / 30ml",
      "parent_name": "Example Liquid Foundation",
      "price_base": 39.99,
      "price": 34.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Beauty",
      "sku": "sku_foundation_shade04_30ml",
      "parent_sku": "sku_foundation_model",
      "gtin": "1234567890123",
      "mpn": "MPN-FOUNDATION-001",
      "ean": "1234567890123",
      "brand": "Example Brand",
      "type": "variable",
      "stock_status": true,
      "stock_location": "Example Warehouse",
      "created_at": 1748505040077,
      "url": "https://example.com/products/liquid-foundation-shade-04",
      "parent_url": "https://example.com/products/liquid-foundation",
      "image": "https://example.com/cdn/foundation-shade04-main.jpg",
      "images": [
        "https://example.com/cdn/foundation-shade04-bottle.jpg",
        "https://example.com/cdn/foundation-shade04-swatch.jpg"
      ],
      "categories": [
        { "name": "Beauty", "id": "cat_beauty" },
        { "name": "Makeup", "id": "cat_makeup" },
        { "name": "Foundation", "id": "cat_foundation" }
      ],
      "currency": "USD",
      "exchange_rate": 1,
      "coupons": [
        {
          "name": "EXAMPLE_FIRSTORDER",
          "value": 5.00,
          "tax_included": true,
          "tax_percent": 19,
          "type": "FIRST_ORDER"
        }
      ],
      "properties": {
        "variant": "Shade 04 / 30ml",
        "shade": "shade_04_warm_beige",
        "volume_ml": 30,
        "skin_type": ["normal", "combination"],
        "finish": "matte",
        "coverage": "medium_to_full",
        "spf": 15,
        "formulation": "vegan",
        "fragrance_free": true,
        "cruelty_free": true,
        "ingredients_highlight": ["hyaluronic_acid", "niacinamide"]
      }
    }
  ],
  "user": {
    "id": "cust_abc123",
    "email": "example.customer@example.com",
    "phone": "+10000000000",
    "first_name": "Example First Name",
    "last_name": "Example Last Name",
    "country": "US",
    "region": "Example Region",
    "city": "Example City",
    "street": "123 Sample Street",
    "postal_code": "00000",
    "orders_total_number": 8,
    "orders_canceled_number": 1,
    "orders_total_value": 412.30,
    "orders_refunded_value": 39.99,
    "predicted_value": 1200.00,
    "created_at": 1640995200000,
    "properties": {
      "customer_segment": "beauty_enthusiast",
      "acquisition_channel": "social_paid",
      "loyalty_tier": "gold",
      "preferred_categories": ["beauty", "skincare"]
    }
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "product_viewed",
    "value": 189.99,
    "currency": "USD",
    "exchange_rate": 1
  },
  "context": {
    "url": "https://example.com/products/floor-lamp-brass",
    "page_type": "product",
    "environment": "prod"
  },
  "products": [
    {
      "id": "prod_lamp_brass",
      "parent_id": "prod_lamp_model",
      "name": "Example Floor Lamp - Brass",
      "parent_name": "Example Floor Lamp",
      "price_base": 229.99,
      "price": 189.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Home & Living",
      "sku": "sku_lamp_brass",
      "parent_sku": "sku_lamp_model",
      "gtin": "1234567890123",
      "mpn": "MPN-LAMP-001",
      "ean": "1234567890123",
      "brand": "Example Brand",
      "type": "variable",
      "stock_status": true,
      "stock_location": "Example Warehouse",
      "created_at": 1748505040077,
      "url": "https://example.com/products/floor-lamp-brass",
      "parent_url": "https://example.com/products/floor-lamp",
      "image": "https://example.com/cdn/lamp-brass-main.jpg",
      "images": [
        "https://example.com/cdn/lamp-brass-living-room.jpg",
        "https://example.com/cdn/lamp-brass-detail.jpg"
      ],
      "categories": [
        { "name": "Home & Living", "id": "cat_home" },
        { "name": "Lighting", "id": "cat_lighting" },
        { "name": "Floor Lamps", "id": "cat_floor_lamps" }
      ],
      "currency": "USD",
      "exchange_rate": 1,
      "coupons": [
        {
          "name": "EXAMPLE_CLEARANCE",
          "value": 40.00,
          "tax_included": true,
          "tax_percent": 19,
          "type": "CLEARANCE"
        }
      ],
      "properties": {
        "variant": "Brass",
        "color": "brass",
        "material": ["metal", "fabric"],
        "dimensions_cm": "30x30x150",
        "weight_kg": 4.5,
        "style": "mid_century",
        "room_type": ["living_room", "bedroom"],
        "finish": "brushed",
        "assembly_required": true,
        "bulb_included": false,
        "wattage_max": 60,
        "cord_length_cm": 200
      }
    }
  ],
  "user": {
    "id": "cust_abc123",
    "email": "example.customer@example.com",
    "phone": "+10000000000",
    "first_name": "Example First Name",
    "last_name": "Example Last Name",
    "country": "US",
    "region": "Example Region",
    "city": "Example City",
    "street": "123 Sample Street",
    "postal_code": "00000",
    "orders_total_number": 2,
    "orders_canceled_number": 0,
    "orders_total_value": 540.00,
    "orders_refunded_value": 0,
    "predicted_value": 1500.00,
    "created_at": 1640995200000,
    "properties": {
      "customer_segment": "home_decorator",
      "acquisition_channel": "pinterest_organic",
      "loyalty_tier": "silver",
      "preferred_categories": ["home", "lighting"]
    }
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "product_viewed",
    "value": 249.99,
    "currency": "USD"
  },
  "products": [
    {
      "id": "prod_abc123",
      "name": "Example Product Name",
      "brand": "Example Brand",
      "price_base": 299.99,
      "price": 249.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Example Category"
    }
  ]
});
```

Custom properties

Custom properties (`event.properties`, `user.properties`, `products[*].properties`) are **fully processed server-side**. On **browser-side** pixels and tags, only a subset may be available. Server-side processing can also enrich the outgoing payload with additional parameters derived from context and data quality.

## Best Practices[​](#Best-Practices "Direct link to Best Practices")

* **One event per product view** — fire `product_viewed` only when the user lands on a product detail page or actively focuses on a single product. Do not fire it for products in passive lists (category grids, search results, "related products"), or your remarketing audiences will be polluted with low-intent users.
* **Always include `products[0]`** — the array must contain at least the viewed product. The `value` on the event should match `products[0].price` so destinations like Meta `ViewContent` and TikTok `ViewContent` report a consistent monetary value.
* **Consistent IDs across the funnel** — use the same `products[*].id` here as in `product_added_to_cart`, `checkout_started` and `checkout_completed`. This is what lets GA4, Meta and TikTok build proper conversion paths and product-affinity audiences.
* **Currency consistency** — keep `event.currency` aligned with your store's display currency. Override `currency` on `products[0]` only when an individual product is priced in a different currency.
* **User identification** — include the `user` object with email and phone whenever available. This dramatically improves match rates for **Meta Advanced Matching**, **Google Enhanced Conversions** and **TikTok Advanced Matching**, which directly translates to better ROAS reporting and more effective remarketing.
* **Page context** — set `context.page_type` to `"product"` so destinations that segment by page type (GA4 audiences, Meta custom audiences) can target product-viewers specifically.


---

# Shipping Detail Added

Fire the **`shipping_detail_added`** event when a visitor selects or confirms a shipping method during checkout — picking standard, express, next-day, store pickup, etc. This is a mid-funnel checkout-step signal that identifies users who have committed to a delivery option but not yet to payment.

Fire the event once when the shipping method is confirmed. If the user changes shipping method, fire again — each confirmed selection is a distinct signal.

This event is the DATA Reshape equivalent of the standard shipping-info event in every major advertising and analytics platform — push it once and Reshape fans it out to every connected destination with the correct platform-specific name and field mapping, so you do not need to fire `gtag`, `fbq`, `ttq` or other tracking function calls in parallel.

* **Google Analytics 4** — `add_shipping_info` (with `items`, `value`, `currency`, `shipping_tier`, `coupon`).
* **TikTok Pixel / TikTok Events API** — `AddShippingInfo` (with `content_id`, `value`, `currency`).
* **Meta** — no dedicated standard event; Reshape can send a custom CamelCase event when connected.
* **Other connected destinations** — mapped automatically based on each destination's native schema.

One push, many native events

A single Reshape event can produce **one or more native events per destination**, with different characteristics depending on each website's destination configuration (active pixels, server endpoints, event-mapping rules).

## Complete Reference[​](#Complete-Reference "Direct link to Complete Reference")

The `shipping_detail_added` event accepts the following objects and fields. Required fields must always be present in the payload — everything else is optional but strongly recommended.

**event** object required

**name** string required

info

Use only static value **shipping\_detail\_added** for `event.name`. DATA Reshape maps this to `add_shipping_info` (GA4) and `AddShippingInfo` (TikTok) automatically; Meta receives a custom CamelCase event `AddShippingInfo` when connected.

```
name: "shipping_detail_added"
```

**value** number required

info

Current cart total at this checkout step.

```
value: 249.99
```

**currency** string required

info

Currency code, ISO 4217 three-letter format.

```
currency: "USD"
```

**exchange\_rate** number

info

Default is 1.

```
exchange_rate: 1
```

**id** string

info

Optional event identifier.

```
id: "evt_shipping_abc123"
```

**context** object

info

[**View complete Context Object documentation**](/objects/context-web.md)

**url** string required-if-applicable

info

Collected automatically for standard websites. Required only for SPA applications where URL changes don't trigger automatic page context updates.

```
url:"https://example.com/products/prod_abc123?utm_source=example"
```

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

Array containing every product currently in the cart. [**View complete Product Object documentation**](/objects/product.md)

**products\[0]** object required

**id** string required

info

Unique product identifier in your system.

```
id: "prod_abc123"
```

**parent\_id** string recommended

info

Parent product ID for variants or child products. Defaults to `id` if not provided.

```
parent_id: "prod_parent_xyz789"
```

**name** string required

info

Product name or title displayed to users.

```
name: "Example Product Name"
```

**parent\_name** string

info

Parent product name for variants or child products. Defaults to `name` if not provided.

```
parent_name: "Example Parent Product Name"
```

**price\_base** number required

info

Original or base price before discounts. Always equal to or greater than `price`.

```
price_base: 299.99
```

**price** number required

info

Current selling price after discounts. Always equal to or less than `price_base`.

```
price: 249.99
```

**tax\_included** boolean required

info

Whether the price includes taxes. Defaults to `true` if not provided.

```
tax_included: true
```

**tax\_percent** number required

info

Tax percentage applied to the product (0-50). If not provided, the site default tax rate will be used (generally the standard rate of the country).

```
tax_percent: 19
```

**quantity** number required

info

Quantity of this product in the context of the event. Defaults to 1 if not provided.

```
quantity: 2
```

**category** string recommended

info

Main product category name

```
category: "Example Category"
```

**sku** string

info

Product SKU (Stock Keeping Unit) for inventory tracking

```
sku: "sku_abc123"
```

**parent\_sku** string

info

Parent product SKU for variants or child products. Defaults to `sku` if not provided.

```
parent_sku: "sku_parent_xyz789"
```

**gtin** string

info

Global Trade Item Number for product identification

```
gtin: "1234567890123"
```

**mpn** string

info

Manufacturer Part Number assigned by the manufacturer

```
mpn: "MPN-EXAMPLE-001"
```

**ean** string

info

European Article Number for product barcoding

```
ean: "1234567890123"
```

**brand** string

info

Product brand or manufacturer name

```
brand: "Example Brand"
```

**type** string

info

Product type. Free-form string (e.g. "simple", "variable", "bundle", "subscription").

```
type: "simple"
```

**stock\_status** boolean | number | string recommended

info

Product availability, accepted in any of these forms:

* **boolean** — `true` (in stock) / `false` (out of stock)
* **number** — `> 0` = in stock, `0` or negative = out of stock
* **string** — the following (case-insensitive) are treated as **out of stock**: `0`, `no`, `nu`, `false`, `out of stock`, `sold out`, `unavailable`, `indisponibil`, `fara stoc`, `stoc epuizat`.

Any other value is treated as **in stock**. Defaults to `true` (in stock) if not provided.

```
stock_status: true
```

**stock\_location** string

info

Physical location or warehouse where product is stored

```
stock_location: "Example Warehouse"
```

**created\_at** number

info

Timestamp when product was added to inventory (milliseconds)

```
created_at: 1748505040077
```

**url** string

info

Direct URL to the product page

```
url: "https://example.com/products/prod_abc123"
```

**parent\_url** string

info

URL to the parent product page (for variants)

```
parent_url: "https://example.com/products/prod_parent_xyz789"
```

**image** string

info

Main product image URL

```
image: "https://example.com/cdn/prod_abc123-main.jpg"
```

**images** array

info

Array of additional product image URLs

```
images: [
  "https://example.com/cdn/prod_abc123-1.jpg",
  "https://example.com/cdn/prod_abc123-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: "Example Category", id: "cat_abc123" },
  { name: "Example Subcategory", id: "cat_xyz789" }
]
```

**coupons** array

info

Array of product-level coupons applied to this product. [**View complete Coupon Object documentation**](/objects/coupon.md)

**coupons\[0]** (object) - `required`

**name** string required

info

Coupon name or code.

```
name: "EXAMPLE_COUPON"
```

**value** number recommended

info

Coupon discount value.

```
value: 123.99
```

**tax\_included** boolean recommended

info

Whether coupon value includes taxes

```
tax_included: true
```

**tax\_percent** number recommended

info

Tax percentage for the coupon

```
tax_percent: 21
```

**id** string

info

Coupon internal identifier.

```
id: "cpn_abc123"
```

**type** string

info

Coupon type. Free-form string, use consistent naming (e.g. "LOYALTY", "SEASONAL", "FIRST\_ORDER", "SHIPPING").

```
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. Free-form key-value object. Use properties that match your product catalog and business needs.

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.

* IT & C
* Fashion
* Deco

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

```
properties: {
  color: ["black", "white"],
  size: "M",
  material: "cotton",
  fit: "regular", 
  season: "summer",
  collection: "2024_spring",
  care_instructions: "machine_wash"
}
```

```
properties: {
  color: ["natural", "oak"],
  dimensions: "120x80x75cm",
  material: ["wood", "metal"],
  style: "modern",
  room_type: ["living_room", "office"],
  assembly_required: "true"
}
```

**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
```

**shipping** array required

info

Array containing the selected shipping method(s). Drives the `shipping_tier` parameter in GA4 and equivalent fields in other destinations. [**View complete Shipping Object documentation**](/objects/shipping.md)

**shipping\[0]** object required

**name** string required

info

Shipping method name

```
name: "Example Shipping Method"
```

**value** number required

info

Shipping cost value

```
value: 12.99
```

**tax\_included** boolean recommended

info

Whether shipping cost includes taxes

```
tax_included: true
```

**tax\_percent** number recommended

info

Tax percentage for shipping (0-50)

```
tax_percent: 19
```

**id** string

info

Shipping method identifier.

```
id: "shp_abc123"
```

**type** string

info

Shipping type. Free-form string, use consistent naming (e.g. "standard", "express", "next\_day", "pickup", "free").

```
type: "standard"
```

**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**](/objects/user.md)

**id** string recommended

info

Unique customer identifier in your system.

```
id: "cust_abc123"
```

**email** string recommended

info

Customer email address in plaintext. Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.

```
email: "example.customer@example.com"
```

**phone** string recommended

info

Customer phone number in E.164 format (plaintext). Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.

```
phone: "+10000000000"
```

**first\_name** string recommended

info

Customer first name

```
first_name: "Example First Name"
```

**last\_name** string recommended

info

Customer last name

```
last_name: "Example Last Name"
```

**country** string

info

Country name or ISO country code

```
country: "US"
```

**region** string recommended

info

State, province, or region name

```
region: "Example Region"
```

**city** string recommended

info

City or locality name

```
city: "Example City"
```

**street** string

info

Street address including number

```
street: "123 Sample Street"
```

**postal\_code** string

info

Postal code or ZIP code

```
postal_code: "00000"
```

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

* E-commerce Customer
* B2B Lead/Customer
* Subscription Service
* Content Platform

```
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"
}
```

```
properties: {
  company_size: "enterprise",
  industry: "fintech",
  job_title: "marketing_director",
  decision_maker: "true",
  budget_range: "50000-100000",
  lead_source: ["linkedin", "webinar"],
  qualification_status: "qualified",
  sales_stage: "proposal"
}
```

```
properties: {
  subscription_tier: "premium",
  billing_cycle: "annual",
  feature_usage: ["analytics", "reporting", "api"],
  trial_user: "false",
  renewal_date: "2025-06-30",
  support_level: "priority",
  usage_frequency: "daily"
}
```

```
properties: {
  content_preferences: ["technology", "business"],
  engagement_level: "high",
  newsletter_subscriber: "true",
  social_media_follower: "true",
  content_consumption: "premium",
  device_preference: ["mobile", "desktop"],
  timezone: "Example/Timezone"
}
```

## Examples[​](#Examples "Direct link to Examples")

The examples below show how to push `shipping_detail_added` for four common e-commerce niches — **Fashion**, **Electronics**, **Beauty** and **Home & Deco** — each with representative product attributes, plus an additional **Minimal** tab with only the required fields.

* Fashion
* Electronics
* Beauty
* Home & Deco
* Minimal

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "shipping_detail_added",
    "value": 129.98,
    "currency": "USD",
    "exchange_rate": 1
  },
  "context": {
    "url": "https://example.com/checkout/shipping",
    "page_type": "checkout",
    "environment": "prod"
  },
  "products": [
    {
      "id": "prod_tshirt_navy_m",
      "parent_id": "prod_tshirt_model",
      "name": "Example Cotton T-Shirt - Navy / M",
      "parent_name": "Example Cotton T-Shirt",
      "price_base": 59.99,
      "price": 49.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Apparel",
      "sku": "sku_tshirt_navy_m",
      "brand": "Example Brand",
      "type": "variable",
      "properties": { "variant": "Navy / M", "color": "navy", "size": "M" }
    },
    {
      "id": "prod_jeans_blue_32",
      "parent_id": "prod_jeans_model",
      "name": "Example Slim Jeans - Indigo / 32",
      "parent_name": "Example Slim Jeans",
      "price_base": 89.99,
      "price": 79.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Apparel",
      "sku": "sku_jeans_blue_32",
      "brand": "Example Brand",
      "type": "variable",
      "properties": { "variant": "Indigo / 32", "color": "indigo", "size": "32" }
    }
  ],
  "shipping": [
    {
      "name": "Example Standard Shipping",
      "value": 9.99,
      "tax_included": true,
      "tax_percent": 19,
      "id": "shp_abc123",
      "type": "standard"
    }
  ],
  "user": {
    "email": "example.customer@example.com",
    "country": "US"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "shipping_detail_added",
    "value": 1349.98,
    "currency": "USD",
    "exchange_rate": 1
  },
  "context": {
    "url": "https://example.com/checkout/shipping",
    "page_type": "checkout",
    "environment": "prod"
  },
  "products": [
    {
      "id": "prod_headphones_black",
      "parent_id": "prod_headphones_model",
      "name": "Example Wireless Headphones - Black",
      "parent_name": "Example Wireless Headphones",
      "price_base": 299.99,
      "price": 249.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Electronics",
      "sku": "sku_headphones_black",
      "brand": "Example Brand",
      "type": "variable",
      "properties": { "variant": "Black", "color": "black" }
    },
    {
      "id": "prod_laptop_15_512",
      "parent_id": "prod_laptop_model",
      "name": "Example Laptop 15 - 512GB / Silver",
      "parent_name": "Example Laptop 15",
      "price_base": 1299.99,
      "price": 1099.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Electronics",
      "sku": "sku_laptop_15_512",
      "brand": "Example Brand",
      "type": "variable",
      "properties": { "variant": "512GB / Silver", "storage_gb": 512 }
    }
  ],
  "shipping": [
    {
      "name": "Example Express Shipping",
      "value": 24.99,
      "tax_included": true,
      "tax_percent": 19,
      "id": "shp_express_abc123",
      "type": "express"
    }
  ],
  "user": {
    "email": "example.customer@example.com",
    "country": "US"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "shipping_detail_added",
    "value": 74.97,
    "currency": "USD",
    "exchange_rate": 1
  },
  "context": {
    "url": "https://example.com/checkout/shipping",
    "page_type": "checkout",
    "environment": "prod"
  },
  "products": [
    {
      "id": "prod_foundation_shade04",
      "parent_id": "prod_foundation_model",
      "name": "Example Liquid Foundation - Shade 04 / 30ml",
      "parent_name": "Example Liquid Foundation",
      "price_base": 39.99,
      "price": 34.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Beauty",
      "sku": "sku_foundation_shade04_30ml",
      "brand": "Example Brand",
      "type": "variable",
      "properties": { "variant": "Shade 04 / 30ml", "shade": "shade_04_warm_beige" }
    },
    {
      "id": "prod_lipstick_rose",
      "parent_id": "prod_lipstick_model",
      "name": "Example Matte Lipstick - Rose Petal",
      "parent_name": "Example Matte Lipstick",
      "price_base": 24.99,
      "price": 19.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 2,
      "category": "Beauty",
      "sku": "sku_lipstick_rose",
      "brand": "Example Brand",
      "type": "variable",
      "properties": { "variant": "Rose Petal", "shade": "rose_petal" }
    }
  ],
  "shipping": [
    {
      "name": "Example Standard Shipping",
      "value": 9.99,
      "tax_included": true,
      "tax_percent": 19,
      "id": "shp_abc123",
      "type": "standard"
    }
  ],
  "user": {
    "email": "example.customer@example.com",
    "country": "US"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "shipping_detail_added",
    "value": 389.98,
    "currency": "USD",
    "exchange_rate": 1
  },
  "context": {
    "url": "https://example.com/checkout/shipping",
    "page_type": "checkout",
    "environment": "prod"
  },
  "products": [
    {
      "id": "prod_lamp_brass",
      "parent_id": "prod_lamp_model",
      "name": "Example Floor Lamp - Brass",
      "parent_name": "Example Floor Lamp",
      "price_base": 229.99,
      "price": 189.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Home & Living",
      "sku": "sku_lamp_brass",
      "brand": "Example Brand",
      "type": "variable",
      "properties": { "variant": "Brass", "color": "brass" }
    },
    {
      "id": "prod_rug_natural_160",
      "parent_id": "prod_rug_model",
      "name": "Example Wool Rug - Natural / 160x230",
      "parent_name": "Example Wool Rug",
      "price_base": 249.99,
      "price": 199.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Home & Living",
      "sku": "sku_rug_natural_160",
      "brand": "Example Brand",
      "type": "variable",
      "properties": { "variant": "Natural / 160x230", "material": "wool" }
    }
  ],
  "shipping": [
    {
      "name": "Example Standard Shipping",
      "value": 29.99,
      "tax_included": true,
      "tax_percent": 19,
      "id": "shp_abc123",
      "type": "standard"
    }
  ],
  "user": {
    "email": "example.customer@example.com",
    "country": "US"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "shipping_detail_added",
    "value": 249.99,
    "currency": "USD"
  },
  "products": [
    {
      "id": "prod_abc123",
      "name": "Example Product Name",
      "brand": "Example Brand",
      "price_base": 299.99,
      "price": 249.99,
      "tax_included": true,
      "tax_percent": 19,
      "quantity": 1,
      "category": "Example Category"
    }
  ],
  "shipping": [
    {
      "name": "Example Standard Shipping",
      "value": 9.99,
      "type": "standard"
    }
  ]
});
```

Custom properties

Custom properties (`event.properties`, `user.properties`, `products[*].properties`) are **fully processed server-side**. On **browser-side** pixels and tags, only a subset may be available. Server-side processing can also enrich the outgoing payload with additional parameters derived from context and data quality.

## Best Practices[​](#Best-Practices "Direct link to Best Practices")

* **Fire once per confirmed selection** — not on every dropdown change. If the user changes shipping method, fire again.
* **Always include `shipping[0]`** — at least with `name`, `value` and `type`.
* **Use stable `shipping[*].type` values** — `"standard"`, `"express"`, `"next_day"`, `"overnight"`, `"pickup"`, `"free"` etc.
* **Keep cart consistency** — `products[]` must reflect the current cart at this checkout step.


---

# Email Subscribed

Fire the **`email_subscribed`** event when a visitor opts in to a newsletter, mailing list, product alert, back-in-stock notification, or any equivalent email-based subscription. This is the standard signal for email-list growth and is widely used as a soft-conversion event for top-of-funnel campaigns.

Fire the event once when the subscription is confirmed (after double opt-in if your flow requires it, or immediately on successful submission for single opt-in flows). Always include the `user.email` since email-list events are useless without the identity.

This event is the DATA Reshape equivalent of the standard subscribe event in every major advertising and analytics platform — push it once and Reshape fans it out to every connected destination with the correct platform-specific name and field mapping, so you do not need to fire `gtag`, `fbq`, `ttq` or other tracking function calls in parallel.

* **Google Analytics 4** — `subscribe` (with `value`, `currency`).
* **Google Ads** — conversion tracking when configured as a soft conversion.
* **Meta Pixel / Meta Conversions API** — `Subscribe` (with `value`, `currency`, `predicted_ltv`).
* **TikTok Pixel / TikTok Events API** — `Subscribe` (with `value`, `currency`).
* **Other connected destinations** — mapped automatically based on each destination's native schema.

One push, many native events

A single Reshape event can produce **one or more native events per destination**, with different characteristics depending on each website's destination configuration (active pixels, server endpoints, event-mapping rules).

## Complete Reference[​](#Complete-Reference "Direct link to Complete Reference")

The `email_subscribed` event accepts the following objects and fields.

**event** object required

**name** string required

info

Use only static value **email\_subscribed** for `event.name`. DATA Reshape maps this to `subscribe` (GA4) and `Subscribe` (Meta, TikTok) automatically.

```
name: "email_subscribed"
```

**value** number required

info

Estimated value of a subscriber (typical: 1–20 USD predicted LTV contribution).

```
value: 5.00
```

**currency** string required

info

Currency code, ISO 4217 three-letter format.

```
currency: "USD"
```

**id** string

info

Optional subscription event identifier.

```
id: "sub_abc123"
```

**properties** object recommended

info

Custom properties such as `list_name`, `placement`, `signup_source`, etc.

**context** object

info

[**View complete Context Object documentation**](/objects/context-web.md)

**url** string required-if-applicable

info

Collected automatically for standard websites. Required only for SPA applications where URL changes don't trigger automatic page context updates.

```
url:"https://example.com/products/prod_abc123?utm_source=example"
```

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"
```

**user** object required

info

The subscriber's identity. Email is required at minimum. Drives Advanced Matching and identity reconciliation in connected destinations. [**View complete User Object documentation**](/objects/user.md)

**id** string recommended

info

Unique customer identifier in your system.

```
id: "cust_abc123"
```

**email** string recommended

info

Customer email address in plaintext. Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.

```
email: "example.customer@example.com"
```

**phone** string recommended

info

Customer phone number in E.164 format (plaintext). Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.

```
phone: "+10000000000"
```

**first\_name** string recommended

info

Customer first name

```
first_name: "Example First Name"
```

**last\_name** string recommended

info

Customer last name

```
last_name: "Example Last Name"
```

**country** string

info

Country name or ISO country code

```
country: "US"
```

**region** string recommended

info

State, province, or region name

```
region: "Example Region"
```

**city** string recommended

info

City or locality name

```
city: "Example City"
```

**street** string

info

Street address including number

```
street: "123 Sample Street"
```

**postal\_code** string

info

Postal code or ZIP code

```
postal_code: "00000"
```

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

* E-commerce Customer
* B2B Lead/Customer
* Subscription Service
* Content Platform

```
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"
}
```

```
properties: {
  company_size: "enterprise",
  industry: "fintech",
  job_title: "marketing_director",
  decision_maker: "true",
  budget_range: "50000-100000",
  lead_source: ["linkedin", "webinar"],
  qualification_status: "qualified",
  sales_stage: "proposal"
}
```

```
properties: {
  subscription_tier: "premium",
  billing_cycle: "annual",
  feature_usage: ["analytics", "reporting", "api"],
  trial_user: "false",
  renewal_date: "2025-06-30",
  support_level: "priority",
  usage_frequency: "daily"
}
```

```
properties: {
  content_preferences: ["technology", "business"],
  engagement_level: "high",
  newsletter_subscriber: "true",
  social_media_follower: "true",
  content_consumption: "premium",
  device_preference: ["mobile", "desktop"],
  timezone: "Example/Timezone"
}
```

## Examples[​](#Examples "Direct link to Examples")

The examples below show how to push `email_subscribed` for four common subscription scenarios — **Newsletter**, **Product Alert**, **Back-in-stock Alert** and **Price Drop Alert** — plus an additional **Minimal** tab with only the required fields.

* Newsletter
* Product Alert
* Back-in-stock Alert
* Price Drop Alert
* Minimal

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "email_subscribed",
    "value": 5.00,
    "currency": "USD",
    "id": "sub_abc123",
    "properties": {}
  },
  "context": {
    "url": "https://example.com/",
    "page_type": "home",
    "environment": "prod"
  },
  "user": {
    "email": "example.customer@example.com",
    "first_name": "Example First Name",
    "country": "US"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "email_subscribed",
    "value": 8.00,
    "currency": "USD",
    "id": "sub_abc123",
    "properties": {}
  },
  "context": {
    "url": "https://example.com/products/wireless-headphones-black",
    "page_type": "product",
    "environment": "prod"
  },
  "user": {
    "email": "example.customer@example.com",
    "country": "US"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "email_subscribed",
    "value": 12.00,
    "currency": "USD",
    "id": "sub_abc123",
    "properties": {}
  },
  "context": {
    "url": "https://example.com/products/cotton-tshirt-navy-m",
    "page_type": "product",
    "environment": "prod"
  },
  "user": {
    "email": "example.customer@example.com",
    "country": "US"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "email_subscribed",
    "value": 10.00,
    "currency": "USD",
    "id": "sub_abc123",
    "properties": {}
  },
  "context": {
    "url": "https://example.com/products/laptop-15-512",
    "page_type": "product",
    "environment": "prod"
  },
  "user": {
    "email": "example.customer@example.com",
    "country": "US"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "email_subscribed",
    "value": 5.00,
    "currency": "USD"
  },
  "user": {
    "email": "example.customer@example.com"
  }
});
```

Custom properties

Custom properties (`event.properties`, `user.properties`, `products[*].properties`) are **fully processed server-side**. On **browser-side** pixels and tags, only a subset may be available. Server-side processing can also enrich the outgoing payload with additional parameters derived from context and data quality.

## Best Practices[​](#Best-Practices "Direct link to Best Practices")

* **Fire after subscription confirmation** — for double opt-in flows, fire on email confirmation, not on initial form submit (otherwise you count unconfirmed subscribers as conversions).
* **Always include the `user.email`** — email-subscription events without an email are useless. Email is the identity for every email-platform destination.
* **Use a small but non-zero `event.value`** — even 1–5 USD enables value-based bidding to favor users likely to subscribe.
* **Capture `list_name` and `placement` in `properties`** — critical for segmenting which lists/placements drive the most valuable subscribers.
* **Fire server-side from your subscription handler** — most reliable for double-opt-in confirmation flows.


---

# Lead Closed

Fire the **`lead_closed`** event when a lead reaches a final stage in your sales pipeline — Closed Won (deal signed), Closed Lost (deal lost to competitor / no decision / price / etc.), or any equivalent terminal CRM stage. This is the **bottom-of-funnel signal** for B2B and high-consideration purchases — uploading it as an offline conversion to Google Ads and Meta is the most powerful way to optimize ad delivery toward real revenue.

Fire the event once per close action, typically server-side from your CRM when the deal stage is set to Closed. Use the same `event.id` as the original `lead_created` so destinations can match the close to the original capture and compute true ROAS.

This event is the DATA Reshape equivalent of the standard lead-closed event in every major advertising and analytics platform — push it once and Reshape fans it out to every connected destination with the correct platform-specific name and field mapping, so you do not need to fire `gtag`, `fbq`, `ttq` or other tracking function calls in parallel.

* **Google Analytics 4** — no dedicated standard event; mapped as a custom event.
* **Google Ads** — offline conversion upload with `transaction_id` from `event.id`, plus Enhanced Conversions from `user`. This is the highest-value signal for Google Ads optimization.
* **Meta Pixel / Meta Conversions API** — no dedicated standard event; Reshape can send a custom CamelCase event `LeadClosed` (or `LeadClosedWon` / `LeadClosedLost` depending on configuration). Critical for Meta's offline conversion API.
* **TikTok Pixel / TikTok Events API** — no dedicated standard event; Reshape can send a custom CamelCase event `LeadClosed` when connected.
* **Other connected destinations** — mapped automatically based on each destination's native schema.

One push, many native events

A single Reshape event can produce **one or more native events per destination**, with different characteristics depending on each website's destination configuration (active pixels, server endpoints, event-mapping rules).

## Complete Reference[​](#Complete-Reference "Direct link to Complete Reference")

The `lead_closed` event accepts the following objects and fields.

**event** object required

**name** string required

info

Use only static value **lead\_closed** for `event.name`. DATA Reshape maps this to a custom event in GA4, and a custom CamelCase event `LeadClosed` in Meta and TikTok when connected.

```
name: "lead_closed"
```

**value** number required

info

**For Closed Won**: actual deal value (annual contract value, total order value). **For Closed Lost**: `0`.

```
value: 4500.00
```

**currency** string required

info

Currency code, ISO 4217 three-letter format.

```
currency: "USD"
```

**id** string required

info

Lead ID (same as the original `lead_created` ID).

```
id: "lead_abc123"
```

**properties** object recommended

info

Custom properties such as `close_outcome` (`won` / `lost`), `closure_reason`, `sales_cycle_days`, `deal_type`, etc.

**context** object

info

For server-side firing (typical), use the API context. [**View complete Context API Object documentation**](/objects/context-api.md)

**url** string required-if-applicable

info

Collected automatically for standard websites. Required only for SPA applications where URL changes don't trigger automatic page context updates.

```
url:"https://example.com/products/prod_abc123?utm_source=example"
```

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"
```

**user** object required

info

The closed lead identity. Same `user.id` as in the original `lead_created` event. [**View complete User Object documentation**](/objects/user.md)

**id** string recommended

info

Unique customer identifier in your system.

```
id: "cust_abc123"
```

**email** string recommended

info

Customer email address in plaintext. Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.

```
email: "example.customer@example.com"
```

**phone** string recommended

info

Customer phone number in E.164 format (plaintext). Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.

```
phone: "+10000000000"
```

**first\_name** string recommended

info

Customer first name

```
first_name: "Example First Name"
```

**last\_name** string recommended

info

Customer last name

```
last_name: "Example Last Name"
```

**country** string

info

Country name or ISO country code

```
country: "US"
```

**region** string recommended

info

State, province, or region name

```
region: "Example Region"
```

**city** string recommended

info

City or locality name

```
city: "Example City"
```

**street** string

info

Street address including number

```
street: "123 Sample Street"
```

**postal\_code** string

info

Postal code or ZIP code

```
postal_code: "00000"
```

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

* E-commerce Customer
* B2B Lead/Customer
* Subscription Service
* Content Platform

```
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"
}
```

```
properties: {
  company_size: "enterprise",
  industry: "fintech",
  job_title: "marketing_director",
  decision_maker: "true",
  budget_range: "50000-100000",
  lead_source: ["linkedin", "webinar"],
  qualification_status: "qualified",
  sales_stage: "proposal"
}
```

```
properties: {
  subscription_tier: "premium",
  billing_cycle: "annual",
  feature_usage: ["analytics", "reporting", "api"],
  trial_user: "false",
  renewal_date: "2025-06-30",
  support_level: "priority",
  usage_frequency: "daily"
}
```

```
properties: {
  content_preferences: ["technology", "business"],
  engagement_level: "high",
  newsletter_subscriber: "true",
  social_media_follower: "true",
  content_consumption: "premium",
  device_preference: ["mobile", "desktop"],
  timezone: "Example/Timezone"
}
```

## Examples[​](#Examples "Direct link to Examples")

The examples below show how to push `lead_closed` for four common close outcomes — **Closed Won**, **Closed Lost - Competitor**, **Closed Lost - No Decision** and **Closed Lost - Price** — plus an additional **Minimal** tab with only the required fields.

* Closed Won
* Lost - Competitor
* Lost - No Decision
* Lost - Price
* Minimal

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "lead_closed",
    "value": 4500.00,
    "currency": "USD",
    "id": "lead_abc123",
    "properties": {}
  },
  "context": {
    "url": "https://crm.example.com/deals/lead_abc123",
    "environment": "prod"
  },
  "user": {
    "id": "cust_abc123",
    "email": "example.customer@example.com",
    "phone": "+10000000000",
    "first_name": "Example First Name",
    "last_name": "Example Last Name",
    "country": "US",
    "properties": { "company": "Example Company Inc.", "company_size": "200-500" }
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "lead_closed",
    "value": 0,
    "currency": "USD",
    "id": "lead_abc123",
    "properties": {}
  },
  "context": {
    "url": "https://crm.example.com/deals/lead_abc123",
    "environment": "prod"
  },
  "user": {
    "id": "cust_abc123",
    "email": "example.lead@example.com"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "lead_closed",
    "value": 0,
    "currency": "USD",
    "id": "lead_abc123",
    "properties": {}
  },
  "context": {
    "url": "https://crm.example.com/deals/lead_abc123",
    "environment": "prod"
  },
  "user": {
    "id": "cust_abc123",
    "email": "example.lead@example.com"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "lead_closed",
    "value": 0,
    "currency": "USD",
    "id": "lead_abc123",
    "properties": {}
  },
  "context": {
    "url": "https://crm.example.com/deals/lead_abc123",
    "environment": "prod"
  },
  "user": {
    "id": "cust_abc123",
    "email": "example.lead@example.com"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "lead_closed",
    "value": 4500.00,
    "currency": "USD",
    "id": "lead_abc123"
  },
  "user": {
    "id": "cust_abc123",
    "email": "example.customer@example.com"
  }
});
```

Custom properties

Custom properties (`event.properties`, `user.properties`, `products[*].properties`) are **fully processed server-side**. On **browser-side** pixels and tags, only a subset may be available. Server-side processing can also enrich the outgoing payload with additional parameters derived from context and data quality.

## Best Practices[​](#Best-Practices "Direct link to Best Practices")

* **Use the same `event.id` as the original `lead_created`** — this is what lets Google Ads and Meta attribute the closed deal to the original click and compute true ROAS.
* **Fire server-side from your CRM** — this is always a CRM-originated event, not a browser event.
* **For Closed Won, set `event.value` to the actual deal value** — this is the single most important number for ad-platform value-based optimization.
* **For Closed Lost, set `event.value` to `0`** and capture `closure_reason` — useful for negative-audience signals and pipeline analytics.
* **Upload as offline conversion** — this is the highest-leverage use of `lead_closed`. Both Google Ads and Meta have offline-conversion APIs that ingest this event and use it to retrain ad-delivery algorithms toward similar high-value users.
* **Capture `sales_cycle_days`** — useful for benchmarking sales velocity and feeding back into qualification rules.


---

# Lead Created

Fire the **`lead_created`** event whenever a visitor takes an action that indicates business interest — submitting a contact form, requesting a product demo, requesting a quote, asking for a callback, downloading gated content, or any equivalent form-based capture. This is the foundational top-of-funnel conversion event for any lead-generation business.

Fire the event once per form submission, after the submission is confirmed successful (server validated, lead record created). Always include a unique `event.id` (your internal lead/submission ID) so destinations can deduplicate retries and so server-side reporting matches CRM records. Use `event.value` to express the estimated monetary value of the lead — even an approximate value enables value-based bidding in Google Ads and Meta.

This event is the DATA Reshape equivalent of the standard lead/form-submit event in every major advertising and analytics platform — push it once and Reshape fans it out to every connected destination with the correct platform-specific name and field mapping, so you do not need to fire `gtag`, `fbq`, `ttq` or other tracking function calls in parallel.

* **Google Analytics 4** — `generate_lead` (with `value`, `currency`, `lead_source`).
* **Google Ads** — conversion tracking with `transaction_id` from `event.id`, plus Enhanced Conversions from the `user` object.
* **Meta Pixel / Meta Conversions API** — `Lead` (with `value`, `currency`, `content_name`, `content_category`).
* **TikTok Pixel / TikTok Events API** — `SubmitForm` (with `value`, `currency`); some configurations also fire `Contact`.
* **Other connected destinations** — mapped automatically based on each destination's native schema.

One push, many native events

A single Reshape event can produce **one or more native events per destination**, with different characteristics depending on each website's destination configuration (active pixels, server endpoints, event-mapping rules).

## Complete Reference[​](#Complete-Reference "Direct link to Complete Reference")

The `lead_created` event accepts the following objects and fields. Required fields must always be present in the payload — everything else is optional but strongly recommended. The `user` object is what makes the lead actionable in your downstream destinations: even just an email enables Advanced Matching in Meta, Enhanced Conversions in Google Ads, Advanced Matching in TikTok and equivalent identity flows in other connected destinations.

**event** object required

**name** string required

info

Use only static value **lead\_created** for `event.name`. DATA Reshape maps this to `generate_lead` (GA4), `Lead` (Meta), and `SubmitForm` (TikTok) automatically.

```
name: "lead_created"
```

**value** number required

info

Estimated monetary value of the lead. Used for value-based bidding and ROAS computation across destinations.

```
value: 250.00
```

**currency** string required

info

Currency code, ISO 4217 three-letter format.

```
currency: "USD"
```

**exchange\_rate** number

info

Default is 1.

```
exchange_rate: 1
```

**id** string required

info

Unique lead/submission ID from your system. Required for deduplication across destinations.

```
id: "lead_abc123"
```

**properties** object recommended

info

**Custom Event Properties Examples**

* Ecommerce Order
* B2B Lead
* Subscription Service

```
properties: {
  fulfillment_method: "delivery",
  gift_wrap: "true"
}
```

```
properties: {
  lead_status: "converted",
  sales_stage: "proposal"
}
```

```
properties: {
  subscription_tier: "premium",
  billing_cycle: "annual",
  trial_user: "false",
  renewal_date: "2025-06-30",
  support_level: "priority",
  usage_frequency: "daily"
}
```

**context** object

info

[**View complete Context Object documentation**](/objects/context-web.md)

**url** string required-if-applicable

info

Collected automatically for standard websites. Required only for SPA applications where URL changes don't trigger automatic page context updates.

```
url:"https://example.com/products/prod_abc123?utm_source=example"
```

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"
```

**user** object required

info

The user identity captured in the form. Email at minimum, plus phone, name and any other captured fields. These drive Advanced Matching for Meta and TikTok, Enhanced Conversions for Google Ads, and identity reconciliation in other connected destinations. [**View complete User Object documentation**](/objects/user.md)

**id** string recommended

info

Unique customer identifier in your system.

```
id: "cust_abc123"
```

**email** string recommended

info

Customer email address in plaintext. Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.

```
email: "example.customer@example.com"
```

**phone** string recommended

info

Customer phone number in E.164 format (plaintext). Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.

```
phone: "+10000000000"
```

**first\_name** string recommended

info

Customer first name

```
first_name: "Example First Name"
```

**last\_name** string recommended

info

Customer last name

```
last_name: "Example Last Name"
```

**country** string

info

Country name or ISO country code

```
country: "US"
```

**region** string recommended

info

State, province, or region name

```
region: "Example Region"
```

**city** string recommended

info

City or locality name

```
city: "Example City"
```

**street** string

info

Street address including number

```
street: "123 Sample Street"
```

**postal\_code** string

info

Postal code or ZIP code

```
postal_code: "00000"
```

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

* E-commerce Customer
* B2B Lead/Customer
* Subscription Service
* Content Platform

```
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"
}
```

```
properties: {
  company_size: "enterprise",
  industry: "fintech",
  job_title: "marketing_director",
  decision_maker: "true",
  budget_range: "50000-100000",
  lead_source: ["linkedin", "webinar"],
  qualification_status: "qualified",
  sales_stage: "proposal"
}
```

```
properties: {
  subscription_tier: "premium",
  billing_cycle: "annual",
  feature_usage: ["analytics", "reporting", "api"],
  trial_user: "false",
  renewal_date: "2025-06-30",
  support_level: "priority",
  usage_frequency: "daily"
}
```

```
properties: {
  content_preferences: ["technology", "business"],
  engagement_level: "high",
  newsletter_subscriber: "true",
  social_media_follower: "true",
  content_consumption: "premium",
  device_preference: ["mobile", "desktop"],
  timezone: "Example/Timezone"
}
```

## Examples[​](#Examples "Direct link to Examples")

The examples below show how to push `lead_created` for four common form-capture scenarios — **Contact Form**, **Demo Request**, **Quote Request** and **Callback Request** — each with representative event properties for that scenario, plus an additional **Minimal** tab with only the required fields.

* Contact Form
* Demo Request
* Quote Request
* Callback Request
* Minimal

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "lead_created",
    "value": 150.00,
    "currency": "USD",
    "exchange_rate": 1,
    "id": "lead_abc123",
    "properties": {}
  },
  "context": {
    "url": "https://example.com/contact",
    "page_type": "contact",
    "environment": "prod"
  },
  "user": {
    "id": "cust_abc123",
    "email": "example.lead@example.com",
    "phone": "+10000000000",
    "first_name": "Example First Name",
    "last_name": "Example Last Name",
    "country": "US",
    "properties": {
      "lead_quality": "unknown",
      "acquisition_channel": "organic_search"
    }
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "lead_created",
    "value": 1500.00,
    "currency": "USD",
    "exchange_rate": 1,
    "id": "lead_abc123",
    "properties": {}
  },
  "context": {
    "url": "https://example.com/request-demo",
    "page_type": "demo_request",
    "environment": "prod"
  },
  "user": {
    "id": "cust_abc123",
    "email": "example.lead@example.com",
    "phone": "+10000000000",
    "first_name": "Example First Name",
    "last_name": "Example Last Name",
    "country": "US",
    "predicted_value": 5000.00,
    "properties": {
      "company": "Example Company Inc.",
      "job_title": "Example Job Title",
      "industry": "software",
      "lead_quality": "high"
    }
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "lead_created",
    "value": 750.00,
    "currency": "USD",
    "exchange_rate": 1,
    "id": "lead_abc123",
    "properties": {}
  },
  "context": {
    "url": "https://example.com/pricing/request-quote",
    "page_type": "pricing",
    "environment": "prod"
  },
  "user": {
    "id": "cust_abc123",
    "email": "example.lead@example.com",
    "phone": "+10000000000",
    "first_name": "Example First Name",
    "last_name": "Example Last Name",
    "country": "US",
    "predicted_value": 3500.00,
    "properties": {
      "company": "Example Company Inc.",
      "job_title": "Example Job Title",
      "company_size": "200-500"
    }
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "lead_created",
    "value": 200.00,
    "currency": "USD",
    "exchange_rate": 1,
    "id": "lead_abc123",
    "properties": {}
  },
  "context": {
    "url": "https://example.com/contact/callback",
    "page_type": "contact",
    "environment": "prod"
  },
  "user": {
    "id": "cust_abc123",
    "email": "example.lead@example.com",
    "phone": "+10000000000",
    "first_name": "Example First Name",
    "last_name": "Example Last Name",
    "country": "US",
    "properties": {
      "lead_quality": "medium",
      "acquisition_channel": "paid_search"
    }
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "lead_created",
    "value": 150.00,
    "currency": "USD",
    "id": "lead_abc123"
  },
  "user": {
    "email": "example.lead@example.com"
  }
});
```

Custom properties

Custom properties (`event.properties`, `user.properties`, `products[*].properties`) are **fully processed server-side**. On **browser-side** pixels and tags, only a subset may be available. Server-side processing can also enrich the outgoing payload with additional parameters derived from context and data quality.

## Best Practices[​](#Best-Practices "Direct link to Best Practices")

* **Always provide `event.id`** — your internal lead/submission ID. Used for cross-destination deduplication and for matching CRM records when leads are uploaded as offline conversions later.
* **Fire only on confirmed submission** — wait until the lead record is created server-side; never fire on button click before validation succeeds.
* **`event.value` should be your estimated lead value** — even an approximate value enables value-based bidding (Google Ads tCPA/tROAS, Meta value optimization).
* **Include the `user` object with at least an email** — this enables Advanced Matching in Meta and TikTok, Enhanced Conversions in Google Ads, and identity reconciliation in other connected destinations. Server-side firing (post-submit webhook) is the most reliable.
* **Capture lead source in `properties`** — `lead_source` and `form_name` are critical for attribution and downstream lead-scoring.
* **Fire server-side from your form handler** — client-side capture catches the marketing context; a parallel server-side push from the form handler ensures the lead is recorded even if the user closes the browser or uses an ad blocker. DATA Reshape deduplicates via `event.id`.


---

# Lead Disqualified

Fire the **`lead_disqualified`** event when a lead is disqualified by your marketing or sales process — out of ICP (Ideal Customer Profile), no budget, no authority, no timing, duplicate, invalid contact, or any other reason that removes the lead from active pursuit. This event is a valuable **negative signal**: when uploaded as an exclusion to ad platforms, it helps the algorithm steer away from similar low-quality leads.

Fire the event once per disqualification action, typically server-side from your CRM when a lead stage is moved to Disqualified/Rejected/Closed Lost (pre-opportunity).

This event is the DATA Reshape equivalent of the standard lead-disqualified event in every major advertising and analytics platform — push it once and Reshape fans it out to every connected destination with the correct platform-specific name and field mapping, so you do not need to fire `gtag`, `fbq`, `ttq` or other tracking function calls in parallel.

* **Google Analytics 4** — no dedicated standard event; mapped as a custom event.
* **Meta Pixel / Meta Conversions API** — no dedicated standard event; Reshape can send a custom CamelCase event `LeadDisqualified` when connected. Can be configured as a negative signal for audience exclusion.
* **TikTok Pixel / TikTok Events API** — no dedicated standard event; Reshape can send a custom CamelCase event `LeadDisqualified` when connected.
* **Other connected destinations** — mapped automatically based on each destination's native schema; CRM connectors typically update the lead stage to disqualified.

One push, many native events

A single Reshape event can produce **one or more native events per destination**, with different characteristics depending on each website's destination configuration (active pixels, server endpoints, event-mapping rules).

## Complete Reference[​](#Complete-Reference "Direct link to Complete Reference")

The `lead_disqualified` event accepts the following objects and fields.

**event** object required

**name** string required

info

Use only static value **lead\_disqualified** for `event.name`. DATA Reshape maps this to a custom event in GA4, and a custom CamelCase event `LeadDisqualified` in Meta and TikTok when connected.

```
name: "lead_disqualified"
```

**value** number required

info

Typically `0` for disqualified leads.

```
value: 0
```

**currency** string required

info

Currency code, ISO 4217 three-letter format.

```
currency: "USD"
```

**id** string required

info

Lead ID (same as the original `lead_created` ID).

```
id: "lead_abc123"
```

**reason** string recommended

info

The **disqualification reason** — critical for downstream analytics and negative-audience configuration. Free-form string; use a consistent vocabulary (`out_of_icp`, `no_budget`, `no_authority`, `no_timing`, `duplicate`, `invalid_contact`, `competitor`, ...).

```
reason: "out_of_icp"
```

**properties** object

info

Any additional custom key-value data about the disqualification.

**context** object

info

For server-side firing (typical), use the API context. [**View complete Context API Object documentation**](/objects/context-api.md)

**url** string required-if-applicable

info

Collected automatically for standard websites. Required only for SPA applications where URL changes don't trigger automatic page context updates.

```
url:"https://example.com/products/prod_abc123?utm_source=example"
```

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"
```

**user** object required

info

The disqualified lead identity. Same `user.id` as in the original `lead_created` event. [**View complete User Object documentation**](/objects/user.md)

**id** string recommended

info

Unique customer identifier in your system.

```
id: "cust_abc123"
```

**email** string recommended

info

Customer email address in plaintext. Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.

```
email: "example.customer@example.com"
```

**phone** string recommended

info

Customer phone number in E.164 format (plaintext). Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.

```
phone: "+10000000000"
```

**first\_name** string recommended

info

Customer first name

```
first_name: "Example First Name"
```

**last\_name** string recommended

info

Customer last name

```
last_name: "Example Last Name"
```

**country** string

info

Country name or ISO country code

```
country: "US"
```

**region** string recommended

info

State, province, or region name

```
region: "Example Region"
```

**city** string recommended

info

City or locality name

```
city: "Example City"
```

**street** string

info

Street address including number

```
street: "123 Sample Street"
```

**postal\_code** string

info

Postal code or ZIP code

```
postal_code: "00000"
```

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

* E-commerce Customer
* B2B Lead/Customer
* Subscription Service
* Content Platform

```
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"
}
```

```
properties: {
  company_size: "enterprise",
  industry: "fintech",
  job_title: "marketing_director",
  decision_maker: "true",
  budget_range: "50000-100000",
  lead_source: ["linkedin", "webinar"],
  qualification_status: "qualified",
  sales_stage: "proposal"
}
```

```
properties: {
  subscription_tier: "premium",
  billing_cycle: "annual",
  feature_usage: ["analytics", "reporting", "api"],
  trial_user: "false",
  renewal_date: "2025-06-30",
  support_level: "priority",
  usage_frequency: "daily"
}
```

```
properties: {
  content_preferences: ["technology", "business"],
  engagement_level: "high",
  newsletter_subscriber: "true",
  social_media_follower: "true",
  content_consumption: "premium",
  device_preference: ["mobile", "desktop"],
  timezone: "Example/Timezone"
}
```

## Examples[​](#Examples "Direct link to Examples")

The examples below show how to push `lead_disqualified` for four common rejection reasons — **Out of ICP**, **No Budget**, **No Authority** and **Duplicate** — plus an additional **Minimal** tab with only the required fields.

* Out of ICP
* No Budget
* No Authority
* Duplicate
* Minimal

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "lead_disqualified",
    "value": 0,
    "currency": "USD",
    "id": "lead_abc123",
    "reason": "out_of_icp"
  },
  "context": {
    "url": "https://crm.example.com/leads/lead_abc123",
    "environment": "prod"
  },
  "user": {
    "id": "cust_abc123",
    "email": "example.lead@example.com"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "lead_disqualified",
    "value": 0,
    "currency": "USD",
    "id": "lead_abc123",
    "reason": "no_budget"
  },
  "context": {
    "url": "https://crm.example.com/leads/lead_abc123",
    "environment": "prod"
  },
  "user": {
    "id": "cust_abc123",
    "email": "example.lead@example.com"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "lead_disqualified",
    "value": 0,
    "currency": "USD",
    "id": "lead_abc123",
    "reason": "no_authority"
  },
  "context": {
    "url": "https://crm.example.com/leads/lead_abc123",
    "environment": "prod"
  },
  "user": {
    "id": "cust_abc123",
    "email": "example.lead@example.com"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "lead_disqualified",
    "value": 0,
    "currency": "USD",
    "id": "lead_abc123",
    "reason": "duplicate"
  },
  "context": {
    "url": "https://crm.example.com/leads/lead_abc123",
    "environment": "prod"
  },
  "user": {
    "id": "cust_abc123",
    "email": "example.lead@example.com"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "lead_disqualified",
    "value": 0,
    "currency": "USD",
    "id": "lead_abc123"
  },
  "user": {
    "id": "cust_abc123",
    "email": "example.lead@example.com"
  }
});
```

Custom properties

Custom properties (`event.properties`, `user.properties`, `products[*].properties`) are **fully processed server-side**. On **browser-side** pixels and tags, only a subset may be available. Server-side processing can also enrich the outgoing payload with additional parameters derived from context and data quality.

## Best Practices[​](#Best-Practices "Direct link to Best Practices")

* **Use the same `event.id` as the original `lead_created`** — this matches the disqualification to the original lead.
* **Always set `reason`** — without it, the event is useless for analytics. Use a consistent vocabulary: `out_of_icp`, `no_budget`, `no_authority`, `no_timing`, `duplicate`, `invalid_contact`, `competitor`, etc.
* **Fire server-side from your CRM** — this event always originates from a CRM stage change.
* **Use as a negative signal in ad platforms** — uploading disqualified leads as an exclusion audience helps Google Ads and Meta steer away from similar low-quality clicks.


---

# Lead Qualified

Fire the **`lead_qualified`** event when a lead is qualified by your marketing or sales process — meeting MQL (Marketing Qualified Lead) threshold, advancing to SQL (Sales Qualified Lead), passing a manual qualification review, or any equivalent pipeline transition. This event is the canonical signal for moving a lead from raw capture to active sales pursuit.

Fire the event once per qualification transition (do not re-fire on requalification). This event is most often fired **server-side from your CRM** when a stage change occurs — not from the browser.

This event is the DATA Reshape equivalent of the standard lead-qualified event in every major advertising and analytics platform — push it once and Reshape fans it out to every connected destination with the correct platform-specific name and field mapping, so you do not need to fire `gtag`, `fbq`, `ttq` or other tracking function calls in parallel.

* **Google Analytics 4** — no dedicated standard event; mapped as a custom event.
* **Meta Pixel / Meta Conversions API** — no dedicated standard event; Reshape can send a custom CamelCase event `LeadQualified` when connected. Useful for offline-conversion uploads to optimize ad delivery toward higher-quality leads.
* **TikTok Pixel / TikTok Events API** — no dedicated standard event; Reshape can send a custom CamelCase event `LeadQualified` when connected.
* **Other connected destinations** — mapped automatically based on each destination's native schema; CRM connectors typically use this to update the lead stage.

One push, many native events

A single Reshape event can produce **one or more native events per destination**, with different characteristics depending on each website's destination configuration (active pixels, server endpoints, event-mapping rules).

## Complete Reference[​](#Complete-Reference "Direct link to Complete Reference")

The `lead_qualified` event accepts the following objects and fields.

**event** object required

**name** string required

info

Use only static value **lead\_qualified** for `event.name`. DATA Reshape maps this to a custom event in GA4, and a custom CamelCase event `LeadQualified` in Meta and TikTok when connected.

```
name: "lead_qualified"
```

**value** number required

info

Updated estimated value of the qualified lead. Typically higher than the initial `lead_created` value.

```
value: 1500.00
```

**currency** string required

info

Currency code, ISO 4217 three-letter format.

```
currency: "USD"
```

**id** string required

info

Lead ID (same as the original `lead_created` ID so destinations can match the stage transition to the original lead).

```
id: "lead_abc123"
```

**properties** object recommended

info

Custom properties such as `qualification_method`, `lead_score`, `sales_rep_assigned`, etc.

**context** object

info

For server-side firing (typical), use the API context. [**View complete Context API Object documentation**](/objects/context-api.md)

**url** string required-if-applicable

info

Collected automatically for standard websites. Required only for SPA applications where URL changes don't trigger automatic page context updates.

```
url:"https://example.com/products/prod_abc123?utm_source=example"
```

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"
```

**user** object required

info

The qualified lead identity. Same `user.id` as in the original `lead_created` event. [**View complete User Object documentation**](/objects/user.md)

**id** string recommended

info

Unique customer identifier in your system.

```
id: "cust_abc123"
```

**email** string recommended

info

Customer email address in plaintext. Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.

```
email: "example.customer@example.com"
```

**phone** string recommended

info

Customer phone number in E.164 format (plaintext). Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.

```
phone: "+10000000000"
```

**first\_name** string recommended

info

Customer first name

```
first_name: "Example First Name"
```

**last\_name** string recommended

info

Customer last name

```
last_name: "Example Last Name"
```

**country** string

info

Country name or ISO country code

```
country: "US"
```

**region** string recommended

info

State, province, or region name

```
region: "Example Region"
```

**city** string recommended

info

City or locality name

```
city: "Example City"
```

**street** string

info

Street address including number

```
street: "123 Sample Street"
```

**postal\_code** string

info

Postal code or ZIP code

```
postal_code: "00000"
```

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

* E-commerce Customer
* B2B Lead/Customer
* Subscription Service
* Content Platform

```
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"
}
```

```
properties: {
  company_size: "enterprise",
  industry: "fintech",
  job_title: "marketing_director",
  decision_maker: "true",
  budget_range: "50000-100000",
  lead_source: ["linkedin", "webinar"],
  qualification_status: "qualified",
  sales_stage: "proposal"
}
```

```
properties: {
  subscription_tier: "premium",
  billing_cycle: "annual",
  feature_usage: ["analytics", "reporting", "api"],
  trial_user: "false",
  renewal_date: "2025-06-30",
  support_level: "priority",
  usage_frequency: "daily"
}
```

```
properties: {
  content_preferences: ["technology", "business"],
  engagement_level: "high",
  newsletter_subscriber: "true",
  social_media_follower: "true",
  content_consumption: "premium",
  device_preference: ["mobile", "desktop"],
  timezone: "Example/Timezone"
}
```

## Examples[​](#Examples "Direct link to Examples")

The examples below show how to push `lead_qualified` for four common qualification scenarios — **MQL Threshold**, **Sales Qualified**, **Auto-Qualified** and **Manual Review** — plus an additional **Minimal** tab with only the required fields.

* MQL Threshold
* Sales Qualified
* Auto-Qualified
* Manual Review
* Minimal

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "lead_qualified",
    "value": 1000.00,
    "currency": "USD",
    "id": "lead_abc123",
    "properties": {}
  },
  "context": {
    "url": "https://crm.example.com/leads/lead_abc123",
    "environment": "prod"
  },
  "user": {
    "id": "cust_abc123",
    "email": "example.lead@example.com",
    "properties": { "company": "Example Company Inc.", "industry": "software" }
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "lead_qualified",
    "value": 2500.00,
    "currency": "USD",
    "id": "lead_abc123",
    "properties": {}
  },
  "context": {
    "url": "https://crm.example.com/leads/lead_abc123",
    "environment": "prod"
  },
  "user": {
    "id": "cust_abc123",
    "email": "example.lead@example.com",
    "properties": { "company": "Example Company Inc.", "company_size": "200-500" }
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "lead_qualified",
    "value": 1500.00,
    "currency": "USD",
    "id": "lead_abc123",
    "properties": {}
  },
  "context": {
    "url": "https://crm.example.com/leads/lead_abc123",
    "environment": "prod"
  },
  "user": {
    "id": "cust_abc123",
    "email": "example.lead@example.com"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "lead_qualified",
    "value": 2000.00,
    "currency": "USD",
    "id": "lead_abc123",
    "properties": {}
  },
  "context": {
    "url": "https://crm.example.com/leads/lead_abc123",
    "environment": "prod"
  },
  "user": {
    "id": "cust_abc123",
    "email": "example.lead@example.com"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "lead_qualified",
    "value": 1500.00,
    "currency": "USD",
    "id": "lead_abc123"
  },
  "user": {
    "id": "cust_abc123",
    "email": "example.lead@example.com"
  }
});
```

Custom properties

Custom properties (`event.properties`, `user.properties`, `products[*].properties`) are **fully processed server-side**. On **browser-side** pixels and tags, only a subset may be available. Server-side processing can also enrich the outgoing payload with additional parameters derived from context and data quality.

## Best Practices[​](#Best-Practices "Direct link to Best Practices")

* **Use the same `event.id` as the original `lead_created`** — this is what lets destinations match the qualification event to the original lead capture.
* **Fire server-side from your CRM** — this event almost always originates from a CRM stage change, not from the browser.
* **Update `event.value` to the refined estimate** — qualified leads typically have a higher predicted value than raw leads.
* **Upload as offline conversion to Google Ads and Meta** — this is the strongest signal for ad-delivery optimization, because it tells the platform which raw clicks turned into actual sales-ready leads.
* **Capture `qualification_method` and `lead_score`** — these are the most valuable properties for downstream analytics.


---

# Login

Fire the **`login`** event when a returning user successfully authenticates on your website — via email/password, social sign-in (Google, Apple, Facebook), magic link, SSO, or any other authentication method. This event is used to attribute returning-user sessions to a stable identity, which improves user-journey reports and enables cross-device tracking.

Fire the event once per successful authentication. Do not fire it on auto-renewed sessions (silent token refresh, "remember me" auto-login) — those are not deliberate authentication actions.

This event is the DATA Reshape equivalent of the standard login event in every major advertising and analytics platform — push it once and Reshape fans it out to every connected destination with the correct platform-specific name and field mapping, so you do not need to fire `gtag`, `fbq`, `ttq` or other tracking function calls in parallel.

* **Google Analytics 4** — `login` (with `method` parameter).
* **Google Ads** — typically not used as a conversion; included for cross-platform consistency.
* **Meta Pixel / Meta Conversions API** — no dedicated standard event; Reshape can send a custom CamelCase event `Login` when connected.
* **TikTok Pixel / TikTok Events API** — no dedicated standard event; Reshape can send a custom CamelCase event `Login` when connected.
* **Other connected destinations** — mapped automatically based on each destination's native schema.

One push, many native events

A single Reshape event can produce **one or more native events per destination**, with different characteristics depending on each website's destination configuration (active pixels, server endpoints, event-mapping rules).

## Complete Reference[​](#Complete-Reference "Direct link to Complete Reference")

The `login` event accepts the following objects and fields.

**event** object required

**name** string required

info

Use only static value **login** for `event.name`. DATA Reshape maps this to `login` (GA4) and a custom CamelCase event `Login` for Meta and TikTok when connected.

```
name: "login"
```

**value** number required

info

Typically `0` for login events. Some accounts use a small predicted-session-value for value-based bidding.

```
value: 0
```

**currency** string required

info

Currency code, ISO 4217 three-letter format.

```
currency: "USD"
```

**id** string

info

Optional login event identifier.

```
id: "login_abc123"
```

**properties** object recommended

info

Custom properties such as `method`, `device`, `session_id`, etc.

**context** object

info

[**View complete Context Object documentation**](/objects/context-web.md)

**url** string required-if-applicable

info

Collected automatically for standard websites. Required only for SPA applications where URL changes don't trigger automatic page context updates.

```
url:"https://example.com/products/prod_abc123?utm_source=example"
```

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"
```

**user** object required

info

The authenticated user. `id` and `email` at minimum so destinations can stitch the session to a stable identity. [**View complete User Object documentation**](/objects/user.md)

**id** string recommended

info

Unique customer identifier in your system.

```
id: "cust_abc123"
```

**email** string recommended

info

Customer email address in plaintext. Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.

```
email: "example.customer@example.com"
```

**phone** string recommended

info

Customer phone number in E.164 format (plaintext). Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.

```
phone: "+10000000000"
```

**first\_name** string recommended

info

Customer first name

```
first_name: "Example First Name"
```

**last\_name** string recommended

info

Customer last name

```
last_name: "Example Last Name"
```

**country** string

info

Country name or ISO country code

```
country: "US"
```

**region** string recommended

info

State, province, or region name

```
region: "Example Region"
```

**city** string recommended

info

City or locality name

```
city: "Example City"
```

**street** string

info

Street address including number

```
street: "123 Sample Street"
```

**postal\_code** string

info

Postal code or ZIP code

```
postal_code: "00000"
```

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

* E-commerce Customer
* B2B Lead/Customer
* Subscription Service
* Content Platform

```
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"
}
```

```
properties: {
  company_size: "enterprise",
  industry: "fintech",
  job_title: "marketing_director",
  decision_maker: "true",
  budget_range: "50000-100000",
  lead_source: ["linkedin", "webinar"],
  qualification_status: "qualified",
  sales_stage: "proposal"
}
```

```
properties: {
  subscription_tier: "premium",
  billing_cycle: "annual",
  feature_usage: ["analytics", "reporting", "api"],
  trial_user: "false",
  renewal_date: "2025-06-30",
  support_level: "priority",
  usage_frequency: "daily"
}
```

```
properties: {
  content_preferences: ["technology", "business"],
  engagement_level: "high",
  newsletter_subscriber: "true",
  social_media_follower: "true",
  content_consumption: "premium",
  device_preference: ["mobile", "desktop"],
  timezone: "Example/Timezone"
}
```

## Examples[​](#Examples "Direct link to Examples")

The examples below show how to push `login` for four common authentication methods — **Email Login**, **Google Login**, **Apple Login** and **Magic Link** — plus an additional **Minimal** tab with only the required fields.

* Email Login
* Google Login
* Apple Login
* Magic Link
* Minimal

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "login",
    "value": 0,
    "currency": "USD",
    "id": "login_abc123",
    "properties": {}
  },
  "context": {
    "url": "https://example.com/login",
    "page_type": "login",
    "environment": "prod"
  },
  "user": {
    "id": "cust_abc123",
    "email": "example.customer@example.com",
    "country": "US"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "login",
    "value": 0,
    "currency": "USD",
    "id": "login_abc123",
    "properties": {}
  },
  "context": {
    "url": "https://example.com/login",
    "page_type": "login",
    "environment": "prod"
  },
  "user": {
    "id": "cust_abc123",
    "email": "example.customer@example.com",
    "country": "US"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "login",
    "value": 0,
    "currency": "USD",
    "id": "login_abc123",
    "properties": {}
  },
  "context": {
    "url": "https://example.com/login",
    "page_type": "login",
    "environment": "prod"
  },
  "user": {
    "id": "cust_abc123",
    "email": "example.customer@example.com",
    "country": "US"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "login",
    "value": 0,
    "currency": "USD",
    "id": "login_abc123",
    "properties": {}
  },
  "context": {
    "url": "https://example.com/auth/verify",
    "page_type": "login",
    "environment": "prod"
  },
  "user": {
    "id": "cust_abc123",
    "email": "example.customer@example.com",
    "country": "US"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "login",
    "value": 0,
    "currency": "USD"
  },
  "user": {
    "email": "example.customer@example.com"
  }
});
```

Custom properties

Custom properties (`event.properties`, `user.properties`, `products[*].properties`) are **fully processed server-side**. On **browser-side** pixels and tags, only a subset may be available. Server-side processing can also enrich the outgoing payload with additional parameters derived from context and data quality.

## Best Practices[​](#Best-Practices "Direct link to Best Practices")

* **Fire only on deliberate authentication** — not on silent token refresh, auto-login from "remember me", or session-resume on page reload.
* **Include the `method` property** — `email`, `google_oauth`, `apple_oauth`, `magic_link`, `sso`, etc.
* **Always include the `user.id`** — same identifier across `sign_up`, `login`, and subsequent events lets destinations build a coherent user journey.
* **Fire server-side from your auth handler** — most reliable, captures the authentication even if the user redirects immediately after.


---

# Sign Up

Fire the **`sign_up`** event when a visitor successfully creates a new account on your website — through email signup, social sign-in (Google, Apple, Facebook), magic-link verification, or any other registration flow. This is the canonical signal for account-creation conversions and onboarding-funnel optimization.

Fire the event once when the account is successfully created (record persisted, email verified if your flow requires it). Use `event.id` for deduplication and include the `user` object with at least an email so destinations can build user-level conversions and audiences.

This event is the DATA Reshape equivalent of the standard registration event in every major advertising and analytics platform — push it once and Reshape fans it out to every connected destination with the correct platform-specific name and field mapping, so you do not need to fire `gtag`, `fbq`, `ttq` or other tracking function calls in parallel.

* **Google Analytics 4** — `sign_up` (with `method` parameter).
* **Google Ads** — conversion tracking with Enhanced Conversions from `user`.
* **Meta Pixel / Meta Conversions API** — `CompleteRegistration` (with `value`, `currency`, `content_name`).
* **TikTok Pixel / TikTok Events API** — `CompleteRegistration` (with `value`, `currency`).
* **Other connected destinations** — mapped automatically based on each destination's native schema.

One push, many native events

A single Reshape event can produce **one or more native events per destination**, with different characteristics depending on each website's destination configuration (active pixels, server endpoints, event-mapping rules).

## Complete Reference[​](#Complete-Reference "Direct link to Complete Reference")

The `sign_up` event accepts the following objects and fields.

**event** object required

**name** string required

info

Use only static value **sign\_up** for `event.name`. DATA Reshape maps this to `sign_up` (GA4) and `CompleteRegistration` (Meta, TikTok) automatically.

```
name: "sign_up"
```

**value** number required

info

Estimated value of a registered user (e.g. predicted LTV or onboarding bonus). Used for value-based bidding.

```
value: 50.00
```

**currency** string required

info

Currency code, ISO 4217 three-letter format.

```
currency: "USD"
```

**id** string

info

Optional unique sign-up ID from your system.

```
id: "signup_abc123"
```

**properties** object recommended

info

Custom properties such as `method` (signup mechanism), `referral_source`, etc.

**context** object

info

[**View complete Context Object documentation**](/objects/context-web.md)

**url** string required-if-applicable

info

Collected automatically for standard websites. Required only for SPA applications where URL changes don't trigger automatic page context updates.

```
url:"https://example.com/products/prod_abc123?utm_source=example"
```

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"
```

**user** object required

info

The newly registered user. Include `id`, `email`, and any captured fields. Drives Advanced Matching, Enhanced Conversions, and identity reconciliation in connected destinations. [**View complete User Object documentation**](/objects/user.md)

**id** string recommended

info

Unique customer identifier in your system.

```
id: "cust_abc123"
```

**email** string recommended

info

Customer email address in plaintext. Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.

```
email: "example.customer@example.com"
```

**phone** string recommended

info

Customer phone number in E.164 format (plaintext). Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.

```
phone: "+10000000000"
```

**first\_name** string recommended

info

Customer first name

```
first_name: "Example First Name"
```

**last\_name** string recommended

info

Customer last name

```
last_name: "Example Last Name"
```

**country** string

info

Country name or ISO country code

```
country: "US"
```

**region** string recommended

info

State, province, or region name

```
region: "Example Region"
```

**city** string recommended

info

City or locality name

```
city: "Example City"
```

**street** string

info

Street address including number

```
street: "123 Sample Street"
```

**postal\_code** string

info

Postal code or ZIP code

```
postal_code: "00000"
```

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

* E-commerce Customer
* B2B Lead/Customer
* Subscription Service
* Content Platform

```
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"
}
```

```
properties: {
  company_size: "enterprise",
  industry: "fintech",
  job_title: "marketing_director",
  decision_maker: "true",
  budget_range: "50000-100000",
  lead_source: ["linkedin", "webinar"],
  qualification_status: "qualified",
  sales_stage: "proposal"
}
```

```
properties: {
  subscription_tier: "premium",
  billing_cycle: "annual",
  feature_usage: ["analytics", "reporting", "api"],
  trial_user: "false",
  renewal_date: "2025-06-30",
  support_level: "priority",
  usage_frequency: "daily"
}
```

```
properties: {
  content_preferences: ["technology", "business"],
  engagement_level: "high",
  newsletter_subscriber: "true",
  social_media_follower: "true",
  content_consumption: "premium",
  device_preference: ["mobile", "desktop"],
  timezone: "Example/Timezone"
}
```

## Examples[​](#Examples "Direct link to Examples")

The examples below show how to push `sign_up` for four common registration methods — **Email Signup**, **Google Sign-in**, **Apple Sign-in** and **Facebook Sign-in** — plus an additional **Minimal** tab with only the required fields.

* Email Signup
* Google Sign-in
* Apple Sign-in
* Facebook Sign-in
* Minimal

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "sign_up",
    "value": 50.00,
    "currency": "USD",
    "id": "signup_abc123",
    "properties": {}
  },
  "context": {
    "url": "https://example.com/signup",
    "page_type": "signup",
    "environment": "prod"
  },
  "user": {
    "id": "cust_abc123",
    "email": "example.customer@example.com",
    "first_name": "Example First Name",
    "last_name": "Example Last Name",
    "country": "US"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "sign_up",
    "value": 50.00,
    "currency": "USD",
    "id": "signup_abc123",
    "properties": {}
  },
  "context": {
    "url": "https://example.com/signup",
    "page_type": "signup",
    "environment": "prod"
  },
  "user": {
    "id": "cust_abc123",
    "email": "example.customer@example.com",
    "first_name": "Example First Name",
    "last_name": "Example Last Name",
    "country": "US"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "sign_up",
    "value": 50.00,
    "currency": "USD",
    "id": "signup_abc123",
    "properties": {}
  },
  "context": {
    "url": "https://example.com/signup",
    "page_type": "signup",
    "environment": "prod"
  },
  "user": {
    "id": "cust_abc123",
    "email": "example.customer@example.com",
    "country": "US"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "sign_up",
    "value": 50.00,
    "currency": "USD",
    "id": "signup_abc123",
    "properties": {}
  },
  "context": {
    "url": "https://example.com/signup",
    "page_type": "signup",
    "environment": "prod"
  },
  "user": {
    "id": "cust_abc123",
    "email": "example.customer@example.com",
    "first_name": "Example First Name",
    "last_name": "Example Last Name",
    "country": "US"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "sign_up",
    "value": 50.00,
    "currency": "USD"
  },
  "user": {
    "email": "example.customer@example.com"
  }
});
```

Custom properties

Custom properties (`event.properties`, `user.properties`, `products[*].properties`) are **fully processed server-side**. On **browser-side** pixels and tags, only a subset may be available. Server-side processing can also enrich the outgoing payload with additional parameters derived from context and data quality.

## Best Practices[​](#Best-Practices "Direct link to Best Practices")

* **Fire only on successful account creation** — wait for the user record to be persisted (and email verified if your flow requires it).
* **Include the `method` property** — `email`, `google_oauth`, `apple_oauth`, `facebook_oauth`, `magic_link`, `sso`, etc. This is what GA4 maps to its `method` parameter.
* **Always include the `user` object with an email** — enables Advanced Matching, Enhanced Conversions, and identity reconciliation in connected destinations.
* **Use a stable `user.id`** — same ID across `sign_up`, `login`, and subsequent events lets destinations build proper user-journey reports.
* **Fire server-side from your registration handler** — catches users who close the browser before the client-side push fires.


---

# User Updated

Fire the **`user_updated`** event when an authenticated user updates any of their profile information — name, address, phone, email, marketing preferences, language, etc. This event keeps identity data in sync between your platform and downstream destinations, and is particularly important for Advanced Matching, Enhanced Conversions, and identity-reconciliation flows where a stale or partial identity record degrades match rates.

Fire the event once per update action, with the `user` object containing the **full updated identity** (not just the changed fields) so downstream destinations always have the latest snapshot.

This event is the DATA Reshape equivalent of the standard user-update event in every major advertising and analytics platform — push it once and Reshape fans it out to every connected destination with the correct platform-specific name and field mapping, so you do not need to fire `gtag`, `fbq`, `ttq` or other tracking function calls in parallel.

* **Google Analytics 4** — no dedicated standard event; mapped as a custom event.
* **Meta Pixel / Meta Conversions API** — no dedicated standard event; Reshape can send a custom CamelCase event `UserUpdated` when connected. Advanced Matching benefits from the refreshed identity.
* **TikTok Pixel / TikTok Events API** — no dedicated standard event; Reshape can send a custom CamelCase event `UserUpdated` when connected. Advanced Matching benefits from the refreshed identity.
* **Other connected destinations** — mapped automatically based on each destination's native schema; CRM/email connectors use this to keep profile records in sync.

One push, many native events

A single Reshape event can produce **one or more native events per destination**, with different characteristics depending on each website's destination configuration (active pixels, server endpoints, event-mapping rules).

## Complete Reference[​](#Complete-Reference "Direct link to Complete Reference")

The `user_updated` event accepts the following objects and fields.

**event** object required

**name** string required

info

Use only static value **user\_updated** for `event.name`. DATA Reshape maps this to a custom event in GA4, and a custom CamelCase event `UserUpdated` in Meta and TikTok when connected.

```
name: "user_updated"
```

**value** number required

info

Typically `0` for profile updates.

```
value: 0
```

**currency** string required

info

Currency code, ISO 4217 three-letter format.

```
currency: "USD"
```

**id** string

info

Optional update event identifier.

```
id: "userupd_abc123"
```

**properties** object recommended

info

Custom properties such as `update_type` (e.g. `profile`, `address`, `preferences`, `email`), `changed_fields`, etc.

**context** object

info

[**View complete Context Object documentation**](/objects/context-web.md)

**url** string required-if-applicable

info

Collected automatically for standard websites. Required only for SPA applications where URL changes don't trigger automatic page context updates.

```
url:"https://example.com/products/prod_abc123?utm_source=example"
```

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"
```

**user** object required

info

The **full updated** user identity (not just the changed fields). Send the complete snapshot so destinations can refresh their profile records. [**View complete User Object documentation**](/objects/user.md)

**id** string recommended

info

Unique customer identifier in your system.

```
id: "cust_abc123"
```

**email** string recommended

info

Customer email address in plaintext. Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.

```
email: "example.customer@example.com"
```

**phone** string recommended

info

Customer phone number in E.164 format (plaintext). Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.

```
phone: "+10000000000"
```

**first\_name** string recommended

info

Customer first name

```
first_name: "Example First Name"
```

**last\_name** string recommended

info

Customer last name

```
last_name: "Example Last Name"
```

**country** string

info

Country name or ISO country code

```
country: "US"
```

**region** string recommended

info

State, province, or region name

```
region: "Example Region"
```

**city** string recommended

info

City or locality name

```
city: "Example City"
```

**street** string

info

Street address including number

```
street: "123 Sample Street"
```

**postal\_code** string

info

Postal code or ZIP code

```
postal_code: "00000"
```

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

* E-commerce Customer
* B2B Lead/Customer
* Subscription Service
* Content Platform

```
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"
}
```

```
properties: {
  company_size: "enterprise",
  industry: "fintech",
  job_title: "marketing_director",
  decision_maker: "true",
  budget_range: "50000-100000",
  lead_source: ["linkedin", "webinar"],
  qualification_status: "qualified",
  sales_stage: "proposal"
}
```

```
properties: {
  subscription_tier: "premium",
  billing_cycle: "annual",
  feature_usage: ["analytics", "reporting", "api"],
  trial_user: "false",
  renewal_date: "2025-06-30",
  support_level: "priority",
  usage_frequency: "daily"
}
```

```
properties: {
  content_preferences: ["technology", "business"],
  engagement_level: "high",
  newsletter_subscriber: "true",
  social_media_follower: "true",
  content_consumption: "premium",
  device_preference: ["mobile", "desktop"],
  timezone: "Example/Timezone"
}
```

## Examples[​](#Examples "Direct link to Examples")

The examples below show how to push `user_updated` for four common update scenarios — **Profile Update**, **Address Update**, **Preferences Update** and **Email Update** — plus an additional **Minimal** tab with only the required fields.

* Profile Update
* Address Update
* Preferences Update
* Email Update
* Minimal

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "user_updated",
    "value": 0,
    "currency": "USD",
    "id": "userupd_abc123",
    "properties": {}
  },
  "context": {
    "url": "https://example.com/account/profile",
    "page_type": "account",
    "environment": "prod"
  },
  "user": {
    "id": "cust_abc123",
    "email": "example.customer@example.com",
    "phone": "+10000000000",
    "first_name": "Example First Name",
    "last_name": "Example Last Name",
    "country": "US"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "user_updated",
    "value": 0,
    "currency": "USD",
    "id": "userupd_abc123",
    "properties": {}
  },
  "context": {
    "url": "https://example.com/account/addresses",
    "page_type": "account",
    "environment": "prod"
  },
  "user": {
    "id": "cust_abc123",
    "email": "example.customer@example.com",
    "phone": "+10000000000",
    "first_name": "Example First Name",
    "last_name": "Example Last Name",
    "country": "US",
    "region": "Example Region",
    "city": "Example City",
    "street": "123 Sample Street",
    "postal_code": "00000"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "user_updated",
    "value": 0,
    "currency": "USD",
    "id": "userupd_abc123",
    "properties": {}
  },
  "context": {
    "url": "https://example.com/account/preferences",
    "page_type": "account",
    "environment": "prod"
  },
  "user": {
    "id": "cust_abc123",
    "email": "example.customer@example.com",
    "country": "US",
    "properties": {
      "marketing_consent": false,
      "preferred_language": "en",
      "preferred_categories": ["apparel", "accessories"]
    }
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "user_updated",
    "value": 0,
    "currency": "USD",
    "id": "userupd_abc123",
    "properties": {}
  },
  "context": {
    "url": "https://example.com/account/email",
    "page_type": "account",
    "environment": "prod"
  },
  "user": {
    "id": "cust_abc123",
    "email": "example.customer@example.com",
    "country": "US"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "user_updated",
    "value": 0,
    "currency": "USD"
  },
  "user": {
    "id": "cust_abc123",
    "email": "example.customer@example.com"
  }
});
```

Custom properties

Custom properties (`event.properties`, `user.properties`, `products[*].properties`) are **fully processed server-side**. On **browser-side** pixels and tags, only a subset may be available. Server-side processing can also enrich the outgoing payload with additional parameters derived from context and data quality.

## Best Practices[​](#Best-Practices "Direct link to Best Practices")

* **Send the full updated identity** — include all known user fields, not just the changed ones. Downstream destinations refresh their profile with whatever fields are present.
* **Always include the stable `user.id`** — this is what destinations use to match the update to an existing profile.
* **Fire once per update action** — not on every keystroke. Wait for the form submit / save action.
* **Capture `update_type` in `properties`** — useful for analytics segmentation (which kinds of updates happen most).
* **Fire server-side from your account-update handler** — most reliable, captures the update even if the user navigates away.


---

# Click Interaction

Fire the **`click`** event to track meaningful click interactions on your website — buttons, links, downloads, video controls, social-share icons, and any other clickable element that signals user engagement. This is a generic interaction event for any click that doesn't have a more specific event (`click_to_phone`, `click_to_email`, `click_to_whatsapp` are auto-tracked separately).

Fire the event once per click, with `event.properties` capturing what was clicked. The richer the properties (element name, action, target, position), the more useful the data for analytics segmentation.

This event is the DATA Reshape equivalent of the standard click event in every major advertising and analytics platform — push it once and Reshape fans it out to every connected destination with the correct platform-specific name and field mapping, so you do not need to fire `gtag`, `fbq`, `ttq` or other tracking function calls in parallel.

* **Google Analytics 4** — no dedicated standard event; mapped as a custom `click` event. Properties become custom event params.
* **Google Ads** — typically not used as a conversion; can be configured for engagement-based audiences.
* **Meta Pixel / Meta Conversions API** — no dedicated standard event; Reshape can send a custom CamelCase event `Click` when connected.
* **TikTok Pixel / TikTok Events API** — no dedicated standard event; Reshape can send a custom CamelCase event `Click` when connected.
* **Other connected destinations** — mapped automatically based on each destination's native schema.

One push, many native events

A single Reshape event can produce **one or more native events per destination**, with different characteristics depending on each website's destination configuration (active pixels, server endpoints, event-mapping rules).

## Complete Reference[​](#Complete-Reference "Direct link to Complete Reference")

The `click` event accepts the following objects and fields.

**event** object required

**name** string required

info

Use only static value **click** for `event.name`.

```
name: "click"
```

**value** number required

info

Typically `0` for generic clicks. Use a non-zero value for engagement-based scoring (e.g. download click might be worth more than a button click).

```
value: 0
```

**currency** string required

info

Currency code, ISO 4217 three-letter format.

```
currency: "USD"
```

**id** string

info

Optional click event identifier.

```
id: "click_abc123"
```

**properties** object recommended

info

Custom properties describing what was clicked — `element_name`, `element_action`, `element_target`, `element_position`, etc. The richer the properties, the more useful for analytics segmentation.

**context** object

info

[**View complete Context Object documentation**](/objects/context-web.md)

**url** string required-if-applicable

info

Collected automatically for standard websites. Required only for SPA applications where URL changes don't trigger automatic page context updates.

```
url:"https://example.com/products/prod_abc123?utm_source=example"
```

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"
```

**user** object recommended

info

[**View complete User Object documentation**](/objects/user.md)

**id** string recommended

info

Unique customer identifier in your system.

```
id: "cust_abc123"
```

**email** string recommended

info

Customer email address in plaintext. Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.

```
email: "example.customer@example.com"
```

**phone** string recommended

info

Customer phone number in E.164 format (plaintext). Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.

```
phone: "+10000000000"
```

**first\_name** string recommended

info

Customer first name

```
first_name: "Example First Name"
```

**last\_name** string recommended

info

Customer last name

```
last_name: "Example Last Name"
```

**country** string

info

Country name or ISO country code

```
country: "US"
```

**region** string recommended

info

State, province, or region name

```
region: "Example Region"
```

**city** string recommended

info

City or locality name

```
city: "Example City"
```

**street** string

info

Street address including number

```
street: "123 Sample Street"
```

**postal\_code** string

info

Postal code or ZIP code

```
postal_code: "00000"
```

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

* E-commerce Customer
* B2B Lead/Customer
* Subscription Service
* Content Platform

```
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"
}
```

```
properties: {
  company_size: "enterprise",
  industry: "fintech",
  job_title: "marketing_director",
  decision_maker: "true",
  budget_range: "50000-100000",
  lead_source: ["linkedin", "webinar"],
  qualification_status: "qualified",
  sales_stage: "proposal"
}
```

```
properties: {
  subscription_tier: "premium",
  billing_cycle: "annual",
  feature_usage: ["analytics", "reporting", "api"],
  trial_user: "false",
  renewal_date: "2025-06-30",
  support_level: "priority",
  usage_frequency: "daily"
}
```

```
properties: {
  content_preferences: ["technology", "business"],
  engagement_level: "high",
  newsletter_subscriber: "true",
  social_media_follower: "true",
  content_consumption: "premium",
  device_preference: ["mobile", "desktop"],
  timezone: "Example/Timezone"
}
```

## Examples[​](#Examples "Direct link to Examples")

The examples below show how to push `click` for five common element types — **Button**, **Link**, **Download**, **Video** and **Social Share** — plus an additional **Minimal** tab with only the required fields.

* Button
* Link
* Download
* Video
* Social Share
* Minimal

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "click",
    "value": 0,
    "currency": "USD",
    "properties": {}
  },
  "context": {
    "url": "https://example.com/",
    "page_type": "home",
    "environment": "prod"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "click",
    "value": 0,
    "currency": "USD",
    "properties": {}
  },
  "context": {
    "url": "https://example.com/",
    "page_type": "home",
    "environment": "prod"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "click",
    "value": 5.00,
    "currency": "USD",
    "properties": {}
  },
  "context": {
    "url": "https://example.com/pricing",
    "page_type": "pricing",
    "environment": "prod"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "click",
    "value": 0,
    "currency": "USD",
    "properties": {}
  },
  "context": {
    "url": "https://example.com/product",
    "page_type": "product",
    "environment": "prod"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "click",
    "value": 0,
    "currency": "USD",
    "properties": {}
  },
  "context": {
    "url": "https://example.com/blog/example-post",
    "page_type": "blog_post",
    "environment": "prod"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "click",
    "value": 0,
    "currency": "USD",
    "properties": {}
  }
});
```

Custom properties

Custom properties (`event.properties`, `user.properties`, `products[*].properties`) are **fully processed server-side**. On **browser-side** pixels and tags, only a subset may be available. Server-side processing can also enrich the outgoing payload with additional parameters derived from context and data quality.

## Best Practices[​](#Best-Practices "Direct link to Best Practices")

* **Be selective** — track only meaningful clicks that have analytic or attribution value. Tracking every click pollutes data and inflates event counts.
* **Use consistent `element_type` values** — `button`, `link`, `download`, `video`, `social_share`, `image`, `icon`, etc. Consistent typing produces clean reports across destinations.
* **Capture `element_name`** — a stable, semantic name for the clicked element (e.g. `request_demo`, `footer_pricing`, `pricing_guide_pdf`). This is what destinations use for segmentation.
* **Use `value` for engagement scoring** — assign higher values to clicks that signal stronger intent (downloads, video plays > generic link clicks).
* **For phone/email/WhatsApp clicks, use the dedicated auto-tracked events** — `click_to_phone`, `click_to_email`, `click_to_whatsapp` are fired automatically by DATA Reshape and do not need manual pushing.


---

# Click to Email

Automatic tracking

This event is **automatically tracked** by DATA Reshape whenever a visitor clicks a `mailto:` link on your website. You do not need to push it manually.

The reference below applies only to advanced cases — for example, when you need to trigger this event programmatically from a non-DOM source (synthetic clicks from a SPA framework, custom email widget, etc.).

## When to Use[​](#When-to-Use "Direct link to When to Use")

Trigger this event when a visitor clicks on an email address link (`mailto:` link) on your website, indicating intent to send an email to your business.

## Complete Reference[​](#Complete-Reference "Direct link to Complete Reference")

**event** object required

**name** string required

info

Use only static value **click\_to\_email** for `event.name`.

```
name: "click_to_email"
```

**value** number required

info

Estimated value of an email lead. Set to 0 if not applicable.

```
value: 30.00
```

**currency** string required

info

Currency code. Use your default currency.

```
currency: "USD"
```

**exchange\_rate** number

info

Custom exchange rate for multi-currency. Default is 1.

```
exchange_rate: 1
```

**id** string

info

Optional event identifier.

```
id: "CLICK_EMAIL_12345"
```

**properties** object recommended

info

**Custom Event Properties Examples**

* Ecommerce Order
* B2B Lead
* Subscription Service

```
properties: {
  fulfillment_method: "delivery",
  gift_wrap: "true"
}
```

```
properties: {
  lead_status: "converted",
  sales_stage: "proposal"
}
```

```
properties: {
  subscription_tier: "premium",
  billing_cycle: "annual",
  trial_user: "false",
  renewal_date: "2025-06-30",
  support_level: "priority",
  usage_frequency: "daily"
}
```

**context** object

info

[**View complete Context Object documentation**](/objects/context-web.md)

**url** string required-if-applicable

info

Collected automatically for standard websites. Required only for SPA applications where URL changes don't trigger automatic page context updates.

```
url:"https://example.com/products/prod_abc123?utm_source=example"
```

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"
```

**user** object recommended

info

[**View complete User Object documentation**](/objects/user.md)

**id** string recommended

info

Unique customer identifier in your system.

```
id: "cust_abc123"
```

**email** string recommended

info

Customer email address in plaintext. Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.

```
email: "example.customer@example.com"
```

**phone** string recommended

info

Customer phone number in E.164 format (plaintext). Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.

```
phone: "+10000000000"
```

**first\_name** string recommended

info

Customer first name

```
first_name: "Example First Name"
```

**last\_name** string recommended

info

Customer last name

```
last_name: "Example Last Name"
```

**country** string

info

Country name or ISO country code

```
country: "US"
```

**region** string recommended

info

State, province, or region name

```
region: "Example Region"
```

**city** string recommended

info

City or locality name

```
city: "Example City"
```

**street** string

info

Street address including number

```
street: "123 Sample Street"
```

**postal\_code** string

info

Postal code or ZIP code

```
postal_code: "00000"
```

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

* E-commerce Customer
* B2B Lead/Customer
* Subscription Service
* Content Platform

```
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"
}
```

```
properties: {
  company_size: "enterprise",
  industry: "fintech",
  job_title: "marketing_director",
  decision_maker: "true",
  budget_range: "50000-100000",
  lead_source: ["linkedin", "webinar"],
  qualification_status: "qualified",
  sales_stage: "proposal"
}
```

```
properties: {
  subscription_tier: "premium",
  billing_cycle: "annual",
  feature_usage: ["analytics", "reporting", "api"],
  trial_user: "false",
  renewal_date: "2025-06-30",
  support_level: "priority",
  usage_frequency: "daily"
}
```

```
properties: {
  content_preferences: ["technology", "business"],
  engagement_level: "high",
  newsletter_subscriber: "true",
  social_media_follower: "true",
  content_consumption: "premium",
  device_preference: ["mobile", "desktop"],
  timezone: "Example/Timezone"
}
```

## Examples[​](#Examples "Direct link to Examples")

* Complete
* Minimal

```
{
  "event": {
    "name": "click_to_email",
    "value": 30.00,
    "currency": "USD",
    "exchange_rate": 1,
    "properties": {}
  },
  "context": {
    "url": "https://example.com/about",
    "page_type": "about",
    "environment": "prod"
  },
  "user": {
    "id": "cust_abc123",
    "email": "example.customer@example.com",
    "phone": "+10000000000",
    "first_name": "Example First Name",
    "last_name": "Example Last Name",
    "country": "US",
    "region": "Example City",
    "city": "Example City"
  }
}
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "click_to_email"
  }
});
```

## Best Practices[​](#Best-Practices "Direct link to Best Practices")

* **Let DATA Reshape handle the tracking automatically** — every click on a `mailto:` link is detected and forwarded to your destinations without any code needed on your side.
* **Use proper `mailto:` links in your markup** — accessible, standard links are what the auto-tracker detects. Custom JavaScript click handlers that prevent navigation may bypass automatic detection.
* **Use the manual push only for edge cases** — synthetic clicks from a SPA framework, a custom widget that doesn't use a standard link, or a programmatic trigger from a non-DOM event.
* **Capture context in `event.properties` when pushing manually** — `element_position`, `element_label`, or other attributes that help you understand which placements drive the most email clicks.


---

# Click to Phone

Automatic tracking

This event is **automatically tracked** by DATA Reshape whenever a visitor clicks a `tel:` link on your website. You do not need to push it manually.

The reference below applies only to advanced cases — for example, when you need to trigger this event programmatically from a non-DOM source (synthetic clicks from a SPA framework, custom call-tracking widget, etc.).

## When to Use[​](#When-to-Use "Direct link to When to Use")

Trigger this event when a visitor clicks on a phone number link (`tel:` link) on your website, indicating intent to call your business.

## Complete Reference[​](#Complete-Reference "Direct link to Complete Reference")

**event** object required

**name** string required

info

Use only static value **click\_to\_phone** for `event.name`.

```
name: "click_to_phone"
```

**value** number required

info

Estimated value of a phone call lead. Set to 0 if not applicable.

```
value: 50.00
```

**currency** string required

info

Currency code. Use your default currency.

```
currency: "USD"
```

**exchange\_rate** number

info

Custom exchange rate for multi-currency. Default is 1.

```
exchange_rate: 1
```

**id** string

info

Optional event identifier.

```
id: "CLICK_PHONE_12345"
```

**properties** object recommended

info

**Custom Event Properties Examples**

* Ecommerce Order
* B2B Lead
* Subscription Service

```
properties: {
  fulfillment_method: "delivery",
  gift_wrap: "true"
}
```

```
properties: {
  lead_status: "converted",
  sales_stage: "proposal"
}
```

```
properties: {
  subscription_tier: "premium",
  billing_cycle: "annual",
  trial_user: "false",
  renewal_date: "2025-06-30",
  support_level: "priority",
  usage_frequency: "daily"
}
```

**context** object

info

[**View complete Context Object documentation**](/objects/context-web.md)

**url** string required-if-applicable

info

Collected automatically for standard websites. Required only for SPA applications where URL changes don't trigger automatic page context updates.

```
url:"https://example.com/products/prod_abc123?utm_source=example"
```

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"
```

**user** object recommended

info

[**View complete User Object documentation**](/objects/user.md)

**id** string recommended

info

Unique customer identifier in your system.

```
id: "cust_abc123"
```

**email** string recommended

info

Customer email address in plaintext. Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.

```
email: "example.customer@example.com"
```

**phone** string recommended

info

Customer phone number in E.164 format (plaintext). Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.

```
phone: "+10000000000"
```

**first\_name** string recommended

info

Customer first name

```
first_name: "Example First Name"
```

**last\_name** string recommended

info

Customer last name

```
last_name: "Example Last Name"
```

**country** string

info

Country name or ISO country code

```
country: "US"
```

**region** string recommended

info

State, province, or region name

```
region: "Example Region"
```

**city** string recommended

info

City or locality name

```
city: "Example City"
```

**street** string

info

Street address including number

```
street: "123 Sample Street"
```

**postal\_code** string

info

Postal code or ZIP code

```
postal_code: "00000"
```

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

* E-commerce Customer
* B2B Lead/Customer
* Subscription Service
* Content Platform

```
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"
}
```

```
properties: {
  company_size: "enterprise",
  industry: "fintech",
  job_title: "marketing_director",
  decision_maker: "true",
  budget_range: "50000-100000",
  lead_source: ["linkedin", "webinar"],
  qualification_status: "qualified",
  sales_stage: "proposal"
}
```

```
properties: {
  subscription_tier: "premium",
  billing_cycle: "annual",
  feature_usage: ["analytics", "reporting", "api"],
  trial_user: "false",
  renewal_date: "2025-06-30",
  support_level: "priority",
  usage_frequency: "daily"
}
```

```
properties: {
  content_preferences: ["technology", "business"],
  engagement_level: "high",
  newsletter_subscriber: "true",
  social_media_follower: "true",
  content_consumption: "premium",
  device_preference: ["mobile", "desktop"],
  timezone: "Example/Timezone"
}
```

## Examples[​](#Examples "Direct link to Examples")

* Complete
* Minimal

```
{
  "event": {
    "name": "click_to_phone",
    "value": 50.00,
    "currency": "USD",
    "exchange_rate": 1,
    "properties": {}
  },
  "context": {
    "url": "https://example.com/contact",
    "page_type": "contact",
    "environment": "prod"
  },
  "user": {
    "id": "cust_abc123",
    "email": "example.customer@example.com",
    "phone": "+10000000000",
    "first_name": "Example First Name",
    "last_name": "Example Last Name",
    "country": "US",
    "region": "Example City",
    "city": "Example City"
  }
}
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "click_to_phone"
  }
});
```

## Best Practices[​](#Best-Practices "Direct link to Best Practices")

* **Let DATA Reshape handle the tracking automatically** — every click on a `tel:` link is detected and forwarded to your destinations without any code needed on your side.
* **Use proper `tel:` links in your markup** — accessible, standard links are what the auto-tracker detects. Custom JavaScript click handlers that prevent navigation may bypass automatic detection.
* **Use the manual push only for edge cases** — synthetic clicks from a SPA framework, a custom widget that doesn't use a standard link, or a programmatic trigger from a non-DOM event.
* **Capture context in `event.properties` when pushing manually** — `element_position`, `element_label`, or other attributes that help you understand which placements drive the most call clicks.


---

# Click to WhatsApp

Automatic tracking

This event is **automatically tracked** by DATA Reshape whenever a visitor clicks a `wa.me` or `whatsapp://` link on your website. You do not need to push it manually.

The reference below applies only to advanced cases — for example, when you need to trigger this event programmatically from a non-DOM source (synthetic clicks from a SPA framework, custom chat widget, etc.).

## When to Use[​](#When-to-Use "Direct link to When to Use")

Trigger this event when a visitor clicks on a WhatsApp link (`wa.me` or `whatsapp://` link) on your website, indicating intent to start a WhatsApp conversation with your business.

## Complete Reference[​](#Complete-Reference "Direct link to Complete Reference")

**event** object required

**name** string required

info

Use only static value **click\_to\_whatsapp** for `event.name`.

```
name: "click_to_whatsapp"
```

**value** number required

info

Estimated value of a WhatsApp conversation lead. Set to 0 if not applicable.

```
value: 50.00
```

**currency** string required

info

Currency code. Use your default currency.

```
currency: "USD"
```

**exchange\_rate** number

info

Custom exchange rate for multi-currency. Default is 1.

```
exchange_rate: 1
```

**id** string

info

Optional event identifier.

```
id: "CLICK_WA_12345"
```

**properties** object recommended

info

**Custom Event Properties Examples**

* Ecommerce Order
* B2B Lead
* Subscription Service

```
properties: {
  fulfillment_method: "delivery",
  gift_wrap: "true"
}
```

```
properties: {
  lead_status: "converted",
  sales_stage: "proposal"
}
```

```
properties: {
  subscription_tier: "premium",
  billing_cycle: "annual",
  trial_user: "false",
  renewal_date: "2025-06-30",
  support_level: "priority",
  usage_frequency: "daily"
}
```

**context** object

info

[**View complete Context Object documentation**](/objects/context-web.md)

**url** string required-if-applicable

info

Collected automatically for standard websites. Required only for SPA applications where URL changes don't trigger automatic page context updates.

```
url:"https://example.com/products/prod_abc123?utm_source=example"
```

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"
```

**user** object recommended

info

[**View complete User Object documentation**](/objects/user.md)

**id** string recommended

info

Unique customer identifier in your system.

```
id: "cust_abc123"
```

**email** string recommended

info

Customer email address in plaintext. Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.

```
email: "example.customer@example.com"
```

**phone** string recommended

info

Customer phone number in E.164 format (plaintext). Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.

```
phone: "+10000000000"
```

**first\_name** string recommended

info

Customer first name

```
first_name: "Example First Name"
```

**last\_name** string recommended

info

Customer last name

```
last_name: "Example Last Name"
```

**country** string

info

Country name or ISO country code

```
country: "US"
```

**region** string recommended

info

State, province, or region name

```
region: "Example Region"
```

**city** string recommended

info

City or locality name

```
city: "Example City"
```

**street** string

info

Street address including number

```
street: "123 Sample Street"
```

**postal\_code** string

info

Postal code or ZIP code

```
postal_code: "00000"
```

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

* E-commerce Customer
* B2B Lead/Customer
* Subscription Service
* Content Platform

```
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"
}
```

```
properties: {
  company_size: "enterprise",
  industry: "fintech",
  job_title: "marketing_director",
  decision_maker: "true",
  budget_range: "50000-100000",
  lead_source: ["linkedin", "webinar"],
  qualification_status: "qualified",
  sales_stage: "proposal"
}
```

```
properties: {
  subscription_tier: "premium",
  billing_cycle: "annual",
  feature_usage: ["analytics", "reporting", "api"],
  trial_user: "false",
  renewal_date: "2025-06-30",
  support_level: "priority",
  usage_frequency: "daily"
}
```

```
properties: {
  content_preferences: ["technology", "business"],
  engagement_level: "high",
  newsletter_subscriber: "true",
  social_media_follower: "true",
  content_consumption: "premium",
  device_preference: ["mobile", "desktop"],
  timezone: "Example/Timezone"
}
```

## Examples[​](#Examples "Direct link to Examples")

* Complete
* Minimal

```
{
  "event": {
    "name": "click_to_whatsapp",
    "value": 50.00,
    "currency": "USD",
    "exchange_rate": 1,
    "properties": {}
  },
  "context": {
    "url": "https://example.com/products/laptop",
    "page_type": "product",
    "environment": "prod"
  },
  "user": {
    "id": "cust_abc123",
    "email": "example.customer@example.com",
    "phone": "+10000000000",
    "first_name": "Example First Name",
    "last_name": "Example Last Name",
    "country": "US",
    "region": "Example City",
    "city": "Example City"
  }
}
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "click_to_whatsapp"
  }
});
```

## Best Practices[​](#Best-Practices "Direct link to Best Practices")

* **Let DATA Reshape handle the tracking automatically** — every click on a `wa.me` or `whatsapp:` link is detected and forwarded to your destinations without any code needed on your side.
* **Use proper `wa.me` or `whatsapp:` links in your markup** — accessible, standard links are what the auto-tracker detects. Custom JavaScript click handlers that prevent navigation may bypass automatic detection.
* **Use the manual push only for edge cases** — synthetic clicks from a SPA framework, a custom widget that doesn't use a standard link, or a programmatic trigger from a non-DOM event.
* **Capture context in `event.properties` when pushing manually** — `element_position`, `element_label`, or other attributes that help you understand which placements drive the most WhatsApp message clicks.


---

# Page Viewed

Fire the **`page_viewed`** event when a Single Page Application (SPA) navigates to a new route — React, Vue, Angular, Svelte and similar frameworks update the URL via the History API without triggering a full page reload, so the standard page-view detection does not fire automatically. Push this event on every route change to keep page-view counts accurate.

For traditional multi-page websites, you do not need to fire this event manually — page views are detected automatically on full page loads.

This event is the DATA Reshape equivalent of the standard page-view event in every major advertising and analytics platform — push it once and Reshape fans it out to every connected destination with the correct platform-specific name and field mapping, so you do not need to fire `gtag`, `fbq`, `ttq` or other tracking function calls in parallel.

* **Google Analytics 4** — `page_view` (with `page_location`, `page_title`).
* **Google Ads** — page-view signal used for remarketing audiences.
* **Meta Pixel / Meta Conversions API** — `PageView` (with source URL).
* **TikTok Pixel / TikTok Events API** — `Pageview` (with source URL).
* **Other connected destinations** — mapped automatically based on each destination's native schema.

One push, many native events

A single Reshape event can produce **one or more native events per destination**, with different characteristics depending on each website's destination configuration (active pixels, server endpoints, event-mapping rules).

## Complete Reference[​](#Complete-Reference "Direct link to Complete Reference")

The `page_viewed` event accepts the following objects and fields.

**event** object required

**name** string required

info

Use only static value **page\_viewed** for `event.name`. DATA Reshape maps this to `page_view` (GA4), `PageView` (Meta), and `Pageview` (TikTok) automatically.

```
name: "page_viewed"
```

**value** number required

info

Typically `0` for page views.

```
value: 0
```

**currency** string required

info

Currency code, ISO 4217 three-letter format.

```
currency: "USD"
```

**id** string

info

Optional page-view event identifier.

```
id: "pv_abc123"
```

**context** object required

info

Must include the current route URL for SPA tracking. Optionally include `page_type` for analytics segmentation. [**View complete Context Object documentation**](/objects/context-web.md)

**url** string required-if-applicable

info

Collected automatically for standard websites. Required only for SPA applications where URL changes don't trigger automatic page context updates.

```
url:"https://example.com/products/prod_abc123?utm_source=example"
```

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"
```

**user** object recommended

info

[**View complete User Object documentation**](/objects/user.md)

**id** string recommended

info

Unique customer identifier in your system.

```
id: "cust_abc123"
```

**email** string recommended

info

Customer email address in plaintext. Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.

```
email: "example.customer@example.com"
```

**phone** string recommended

info

Customer phone number in E.164 format (plaintext). Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.

```
phone: "+10000000000"
```

**first\_name** string recommended

info

Customer first name

```
first_name: "Example First Name"
```

**last\_name** string recommended

info

Customer last name

```
last_name: "Example Last Name"
```

**country** string

info

Country name or ISO country code

```
country: "US"
```

**region** string recommended

info

State, province, or region name

```
region: "Example Region"
```

**city** string recommended

info

City or locality name

```
city: "Example City"
```

**street** string

info

Street address including number

```
street: "123 Sample Street"
```

**postal\_code** string

info

Postal code or ZIP code

```
postal_code: "00000"
```

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

* E-commerce Customer
* B2B Lead/Customer
* Subscription Service
* Content Platform

```
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"
}
```

```
properties: {
  company_size: "enterprise",
  industry: "fintech",
  job_title: "marketing_director",
  decision_maker: "true",
  budget_range: "50000-100000",
  lead_source: ["linkedin", "webinar"],
  qualification_status: "qualified",
  sales_stage: "proposal"
}
```

```
properties: {
  subscription_tier: "premium",
  billing_cycle: "annual",
  feature_usage: ["analytics", "reporting", "api"],
  trial_user: "false",
  renewal_date: "2025-06-30",
  support_level: "priority",
  usage_frequency: "daily"
}
```

```
properties: {
  content_preferences: ["technology", "business"],
  engagement_level: "high",
  newsletter_subscriber: "true",
  social_media_follower: "true",
  content_consumption: "premium",
  device_preference: ["mobile", "desktop"],
  timezone: "Example/Timezone"
}
```

## Examples[​](#Examples "Direct link to Examples")

The examples below show a complete `page_viewed` payload and a minimal payload with only the required fields.

* Complete
* Minimal

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "page_viewed",
    "value": 0,
    "currency": "USD",
    "id": "pv_abc123"
  },
  "context": {
    "url": "https://example.com/dashboard/analytics",
    "page_type": "dashboard",
    "environment": "prod"
  },
  "user": {
    "id": "cust_abc123",
    "email": "example.customer@example.com",
    "country": "US"
  }
});
```

```
window.reshape = window.reshape || [];
reshape.push({
  "event": {
    "name": "page_viewed",
    "value": 0,
    "currency": "USD"
  },
  "context": {
    "url": "https://example.com/dashboard/analytics"
  }
});
```

Custom properties

Custom properties (`event.properties`, `user.properties`, `products[*].properties`) are **fully processed server-side**. On **browser-side** pixels and tags, only a subset may be available. Server-side processing can also enrich the outgoing payload with additional parameters derived from context and data quality.

## SPA Implementation[​](#SPA-Implementation "Direct link to SPA Implementation")

Hook into your router and call `reshape.push({ event: { name: "page_viewed" }, ... })` on every successful route transition. Examples:

* **React Router** — subscribe to `useLocation()` or `history.listen()` and fire on change.
* **Vue Router** — `router.afterEach()` hook.
* **Angular Router** — `Router.events.subscribe()` filtering on `NavigationEnd`.
* **Svelte / Nuxt / Next.js** — equivalent route-change hooks for each framework.

Pass the new URL as `context.url` so destinations record the correct page.

## Best Practices[​](#Best-Practices "Direct link to Best Practices")

* **Fire only for SPA route changes** — for full page loads on multi-page sites, page views are detected automatically.
* **Always pass the new `context.url`** — this is what destinations record as the page URL.
* **Set `context.page_type` when possible** — enables clean segmentation in destinations that support page-type filtering.
* **Fire after the route transition completes** — wait until the new view is rendered, not on intent-to-navigate.
* **Avoid duplicate page views** — make sure your router hook fires exactly once per route change, not on every state update.


---

# DATA Reshape Documentation

DATA Reshape is a server-side tracking platform that collects, processes, and streams data from your website to analytics and marketing destinations. It operates under your own domain (first-party) for accurate data collection, bypassing ad blockers and browser restrictions.

## Documentation[​](#Documentation "Direct link to Documentation")

| Section                                | Description                                           |
| -------------------------------------- | ----------------------------------------------------- |
| [Custom Domain](/general/subdomain.md) | DNS configuration for first-party tracking            |
| [Global Code](/general/global-code.md) | JavaScript library installation on your website       |
| [Monitoring](/general/monitoring.md)   | Allow the DATA Reshape monitor through your firewall  |
| [Events](/events.md)                   | E-commerce, lead generation, and interaction events   |
| [API](/api.md)                         | Server-to-server webhook delivery                     |
| [Objects](/objects.md)                 | Standardized schema for products, users, transactions |
| [Destinations](/destinations.md)       | Wire analytics, advertising and CRM platforms         |

## Quick Start[​](#Quick-Start "Direct link to Quick Start")

1. **Set up your subdomain** — [Custom Domain](/general/subdomain.md)
2. **Install the tracking script** — [Global Code](/general/global-code.md)
3. **Implement events** — [Events](/events.md)
4. **Configure destinations** — [Destinations](/destinations.md)

***

For setup and onboarding: **<support@datareshape.ro>**


---

# Global Code Setup

The DATA Reshape tracking script is a lightweight JavaScript snippet that enables server-side tracking across all pages of your website. It collects event data, manages user sessions, and forwards information to your configured destinations.

The script operates under your own domain (first-party), avoiding ad blockers and third-party cookie restrictions.

## Prerequisites[​](#Prerequisites "Direct link to Prerequisites")

Required Before Implementation

Only implement after receiving confirmation from the DATA Reshape team that your custom domain and SSL certificate are active.

You will need:

* **Custom tracking subdomain** (e.g. `dre2.YOUR_DOMAIN.TLD`)
* **Script ID** provided by the DATA Reshape team

## Implementation[​](#Implementation "Direct link to Implementation")

Add this code to your website's `<head>` section on **all pages**:

```
<script>
(function(R,e,s,h,a,p,E){
  var b=R.Reshape=R.Reshape||{};
  b.setCookie=function(n,v,t,d){try{e.cookie=n+'='+v+';max-age='+t+';domain='+d+';path=/;SameSite=None;Secure';}catch(e){}};
  b.id=a;b.cdn=h;b.sts=new Date().getTime();
  E=e.getElementsByTagName(s)[0];p=e.createElement(s);p.async=true;p.src="https://"+h+"/main.js?id="+a;E.parentNode.insertBefore(p,E);
})(window,document,"script","YOUR_SUBDOMAIN","YOUR_SCRIPT_ID");
</script>
```

Replace **`YOUR_SUBDOMAIN`** with your custom subdomain and **`YOUR_SCRIPT_ID`** with your Script ID.

### HTML Template Example[​](#HTML-Template-Example "Direct link to HTML Template Example")

Here's how it should look in a complete HTML document:

```
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Your Website</title>
    
    <!-- DATA Reshape Tracking Code -->
    <script>
    (function(R,e,s,h,a,p,E){
      var b=R.Reshape=R.Reshape||{};
      b.setCookie=function(n,v,t,d){try{e.cookie=n+'='+v+';max-age='+t+';domain='+d+';path=/;SameSite=None;Secure';}catch(e){}};
      b.id=a;b.cdn=h;b.sts=new Date().getTime();
      E=e.getElementsByTagName(s)[0];p=e.createElement(s);p.async=true;p.src="https://"+h+"/main.js?id="+a;E.parentNode.insertBefore(p,E);
    })(window,document,"script","YOUR_SUBDOMAIN","YOUR_SCRIPT_ID");
    </script>
</head>
<body>
    <!-- Your website content -->
</body>
</html>
```

## Platform-Specific Guides[​](#Platform-Specific-Guides "Direct link to Platform-Specific Guides")

| Platform  | Guide                                                |
| --------- | ---------------------------------------------------- |
| WordPress | [WordPress Setup](/general/global-code/wordpress.md) |
| Shopify   | [Shopify Setup](/general/global-code/shopify.md)     |

## Multiple Script IDs[​](#Multiple-Script-IDs "Direct link to Multiple Script IDs")

A single website can use different Script IDs based on subdomain or pathname — useful for multi-store setups (e.g. Magento), multi-market configurations, or the PLUS plan with separate tracking configs.

```
<script>
var getScriptConfig = function() {
  var path = window.location.pathname;
  var hostname = window.location.hostname;
  
  if (hostname.indexOf('store-b.') > -1) return { subdomain: 'dre2.store-b.com', id: 'STOREB_ID' };
  if (path.indexOf('/shop/') === 0) return { subdomain: 'dre2.YOUR_DOMAIN.TLD', id: 'SHOP_SCRIPT_ID' };
  
  return { subdomain: 'dre2.YOUR_DOMAIN.TLD', id: 'MAIN_SCRIPT_ID' };
};

var config = getScriptConfig();

(function(R,e,s,h,a,p,E){
  var b=R.Reshape=R.Reshape||{};
  b.setCookie=function(n,v,t,d){try{e.cookie=n+'='+v+';max-age='+t+';domain='+d+';path=/;SameSite=None;Secure';}catch(e){}};
  b.id=a;b.cdn=h;b.sts=new Date().getTime();
  E=e.getElementsByTagName(s)[0];p=e.createElement(s);p.async=true;p.src="https://"+h+"/main.js?id="+a;E.parentNode.insertBefore(p,E);
})(window,document,"script",config.subdomain,config.id);
</script>
```

## Content Security Policy (CSP)[​](#Content-Security-Policy-CSP "Direct link to Content Security Policy (CSP)")

If your website uses Content Security Policy, add these directives:

```
Content-Security-Policy: script-src 'self' 'unsafe-inline' https://YOUR_SUBDOMAIN; connect-src 'self' https://YOUR_SUBDOMAIN;
```

## Verification[​](#Verification "Direct link to Verification")

End-to-end verification is performed by the DATA Reshape team. Reach out at **<support@datareshape.ro>** once the tracking code is installed, and we will run the confirmation tests, validate the data flowing to each connected destination, and confirm the configuration is correct.

Why DATA Reshape verifies the data

The tracking surface is built **privacy-first**: payloads are obfuscated, PII is normalized and hashed before it leaves the browser, sensitive parameters are encrypted at rest, identity is partitioned per account, and destination-specific protections (such as opt-out signals, data-minimization filters, and limited-use modes) are applied server-side before any downstream call.

Because of these advanced privacy and tracking protections, **the data observable from the outside is intentionally not enough to validate quality on your own**. DATA Reshape is the only party with the visibility needed to confirm that events, identifiers, conversions, and destination deliveries are correct end-to-end.

Privacy by design is a feature of the platform, not an inconvenience — it's what keeps the implementation compliant out of the box and protects your customers' data regardless of which destinations you connect later.

## Troubleshooting[​](#Troubleshooting "Direct link to Troubleshooting")

A few install-time issues are visible directly in the browser and can be fixed without help:

| Symptom                                            | Cause                                                        | Fix                                                                                       |
| -------------------------------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------- |
| `ERR_NAME_NOT_RESOLVED` for the tracking subdomain | DNS not configured or still propagating                      | Verify the subdomain DNS records; allow 24–48h for global propagation.                    |
| `Mixed Content` warning for the tracking subdomain | Page served over HTTPS but the subdomain is reached via HTTP | Make sure the tracking subdomain has a valid SSL certificate and is reachable over HTTPS. |

For anything beyond install-time visibility — events that don't seem to arrive, deduplication concerns, destination-side discrepancies, or any other doubt about data quality — please contact **<support@datareshape.ro>**. By design, the only reliable view into event flow and destination delivery is the internal one; we'll confirm the state, identify the cause, and guide the fix.

## Next Steps[​](#Next-Steps "Direct link to Next Steps")

Once the script loads correctly:

1. **Implement events** — see [Events documentation](/events.md)
2. **Add user data** — include [User object](/objects/user.md) for better attribution
3. **Configure destinations** — connect your analytics and advertising platforms


---

# Gomag Implementation Guide

DATA Reshape integrates with Gomag stores via the platform's tracking code injection points and DATA Reshape's first-party tracking subdomain. Full installation walkthrough coming soon.

## Prerequisites[​](#Prerequisites "Direct link to Prerequisites")

Required before implementation

Only install after your **custom domain and SSL certificate are active**. The tracking subdomain (e.g. `dre2.YOUR_DOMAIN.TLD`) must share the **same root domain** as the storefront for cookies and CORS to work.

You will need:

* **Custom tracking subdomain** — e.g. `dre2.YOUR_DOMAIN.TLD`
* **Script ID** — provided by the DATA Reshape team

Implementation support — DATA Reshape can do this for you

You do not have to install everything by yourself. DATA Reshape provides **hands-on implementation support** and will perform the setup, audit, verification, and per-destination configuration on your Gomag store. To enable that, please create a dedicated **Administrator account** for us and email the credentials to **<gomag@datareshape.ro>**.

* **Role:** Administrator (required to inject the tracking code, manage apps/integrations, and verify the install across page types).
* **Recommended:** create a fresh user (e.g. `datareshape`) instead of sharing an existing one — easier to track activity and revoke.
* **Access can be revoked** at any time once the installation and verification are confirmed live.

After access is granted, DATA Reshape will install the tracking code, audit and clean up duplicate destination code, adjust any conflicting integrations, and run the end-to-end verification — then report back when everything is live.

## Verification[​](#Verification "Direct link to Verification")

End-to-end verification is performed by the DATA Reshape team. Reach out at **<gomag@datareshape.ro>** or **<support@datareshape.ro>** once the tracking code is installed.

Why DATA Reshape verifies the data

The tracking surface is built **privacy-first**: payloads are obfuscated, PII is normalized and hashed before it leaves the browser, sensitive parameters are encrypted at rest, identity is partitioned per account, and destination-specific protections (such as opt-out signals, data-minimization filters, and limited-use modes) are applied server-side before any downstream call.

Because of these advanced privacy and tracking protections, **the data observable from the outside is intentionally not enough to validate quality on your own**. DATA Reshape is the only party with the visibility needed to confirm that events, identifiers, conversions, and destination deliveries are correct end-to-end.


---

# MerchantPro Implementation Guide

DATA Reshape integrates with MerchantPro stores via the platform's tracking code injection points and DATA Reshape's first-party tracking subdomain. Full installation walkthrough coming soon.

## Prerequisites[​](#Prerequisites "Direct link to Prerequisites")

Required before implementation

Only install after your **custom domain and SSL certificate are active**. The tracking subdomain (e.g. `dre2.YOUR_DOMAIN.TLD`) must share the **same root domain** as the storefront for cookies and CORS to work.

You will need:

* **Custom tracking subdomain** — e.g. `dre2.YOUR_DOMAIN.TLD`
* **Script ID** — provided by the DATA Reshape team

Implementation support — DATA Reshape can do this for you

You do not have to install everything by yourself. DATA Reshape provides **hands-on implementation support** and will perform the setup, audit, verification, and per-destination configuration on your MerchantPro store. To enable that, please create a dedicated **Administrator account** for us and email the credentials to **<merchantpro@datareshape.ro>**.

* **Role:** Administrator (required to inject the tracking code, manage apps/integrations, and verify the install across page types).
* **Recommended:** create a fresh user (e.g. `datareshape`) instead of sharing an existing one — easier to track activity and revoke.
* **Access can be revoked** at any time once the installation and verification are confirmed live.

After access is granted, DATA Reshape will install the tracking code, audit and clean up duplicate destination code, adjust any conflicting integrations, and run the end-to-end verification — then report back when everything is live.

## Verification[​](#Verification "Direct link to Verification")

End-to-end verification is performed by the DATA Reshape team. Reach out at **<merchantpro@datareshape.ro>** or **<support@datareshape.ro>** once the tracking code is installed.

Why DATA Reshape verifies the data

The tracking surface is built **privacy-first**: payloads are obfuscated, PII is normalized and hashed before it leaves the browser, sensitive parameters are encrypted at rest, identity is partitioned per account, and destination-specific protections (such as opt-out signals, data-minimization filters, and limited-use modes) are applied server-side before any downstream call.

Because of these advanced privacy and tracking protections, **the data observable from the outside is intentionally not enough to validate quality on your own**. DATA Reshape is the only party with the visibility needed to confirm that events, identifiers, conversions, and destination deliveries are correct end-to-end.


---

# Shopify Implementation Guide

DATA Reshape installs on Shopify with **two assets** that work together:

1. A **theme snippet** included in `theme.liquid` — runs in the storefront window.
2. A **Custom Pixel** added in Shopify Admin (Customer events) — the only surface in Shopify where `checkout` / `thank-you` / `order status` events are observable.

The two assets share the same configuration (subdomain + script ID + mode). One config controls both.

Terminology

Throughout this page, **global tracking code** (or **tracking snippet**) refers to the small inline JavaScript block you paste into the theme snippet and the Custom Pixel — the bootstrap. The script it loads from your subdomain at runtime is referred to abstractly as the **runtime script**.

## Prerequisites[​](#Prerequisites "Direct link to Prerequisites")

Required before implementation

Only install after your **custom domain and SSL certificate are active**. The tracking subdomain (e.g. `dre2.YOUR_DOMAIN.TLD`) must share the **same root domain** as the storefront for cookies and CORS to work.

You will need:

* **Custom tracking subdomain** — e.g. `dre2.YOUR_DOMAIN.TLD`
* **Script ID** — provided by the DATA Reshape team

Implementation support — DATA Reshape can do this for you

You do not have to install everything by yourself. DATA Reshape provides **hands-on implementation support** and will perform the setup, audit, verification, and per-destination configuration on your store. To enable that, please grant us the following so we can do the work and run the checks end-to-end:

* **Collaborator access** (not staff) — accept the **collaborator** access request that DATA Reshape sends from Shopify, and provide the **collaborator request PIN** displayed under **Settings → Users → Security**. We do not accept staff accounts; collaborator is the standard model and can be revoked at any time.
* **Theme access** — required to install / update the global tracking code in `theme.liquid` and the optional product-page enrichment block.
* **Apps access** — required to audit and adjust the sales channels (Facebook & Instagram, Google, TikTok) and any other apps that may push to managed destinations.
* **Customer events access** — required to create, configure, and validate the DATA Reshape Custom Pixel.
* **Notifications access** — required to inspect order, checkout and customer notification templates that may carry tracking parameters or trigger destination events.
* **Customer privacy access** — required to verify the consent banner configuration, the Shopify-native consent signals, and to confirm that consent state is correctly propagated to the DATA Reshape Custom Pixel and downstream destinations.

After access is granted, DATA Reshape will run the installation, the cleanup of duplicate destination code, the privacy settings on the Custom Pixel, the sales-channel adjustments, and the end-to-end verification — and report back when everything is live. Access can be revoked at any time once the work is done.

## Operating modes[​](#Operating-modes "Direct link to Operating modes")

Pick the mode that fits your store. The choice is set via the `parent` field in the shared config.

### Mixed mode (`parent: 1`) — recommended[​](#Mixed-mode-parent-1--recommended "Direct link to Mixed-mode-parent-1--recommended")

The runtime script is loaded in the **storefront parent window** via the theme snippet. The Custom Pixel observes the relevant events and forwards them to the storefront, where the full DATA Reshape SDK consumes them. On surfaces the storefront cannot reach (checkout, thank-you, order status), the Custom Pixel takes over and runs the runtime script on its own. All the coordination between the two is handled internally — you do not need to wire anything.

**Use it when** you can edit `theme.liquid` and want the richest behavior on non-checkout pages (full DOM access, in-page consent banner integration, etc.).

### Pixel-only mode (`parent: 0`)[​](#Pixel-only-mode-parent-0 "Direct link to Pixel-only-mode-parent-0")

The runtime script runs **only inside the Custom Pixel** on every page. The theme snippet, if present, detects `parent: 0` and exits — no scripts in the storefront. The pixel becomes the sole tracking surface.

**Use it when** you cannot or do not want to inject scripts in the theme (security policy, store-front lockdown, etc.). Trade-off: no DOM access on non-checkout pages.

## Step 1 — Add the theme snippet[​](#Step-1--Add-the-theme-snippet "Direct link to Step 1 — Add the theme snippet")

Remove existing destination code first

Before installing the snippet, **delete or comment out every other piece of code in the theme (and every other Custom Pixel / Shopify app) that talks to a destination DATA Reshape manages on this account** — Meta Pixel / Conversions API, Google Tag (`gtag.js`, GTM), TikTok Pixel, Pinterest Tag, Snap Pixel, Klaviyo onsite tracking, etc.

DATA Reshape **owns the full lifecycle** for every connected destination — pixel fire, server-side conversion API call, consent enforcement, deduplication. If the original theme code or a parallel pixel also fires for the same destination, you will get **double events, double conversions, inflated CPA, and inconsistent attribution** — the two emitters will not deduplicate against each other.

Concrete checklist:

* In `theme.liquid` / `layout/*.liquid` — search for `fbq(`, `gtag(`, `ttq.`, `pintrk(`, `snaptr(`, any inline `<script>` containing pixel IDs (`G-...`, `GTM-...`, Meta numeric IDs, TikTok `pixel_code`, etc.). Delete or comment out.
* In **Customer events** (where you're about to add this Custom Pixel) — disable or remove any other custom pixel for the same destinations.
* In **Apps** — uninstall or pause apps **only if tracking is their sole function**. If the app also provides other services you actively use (catalog sync, ad management, shop pages, merchant feed, customer support widget, etc.), **keep it installed** and turn off only the tracking / data-sharing setting inside the app. See the next callout for sales channels specifically.
* In **checkout.liquid** (Plus only) and in `additional_scripts` (Plus) — same audit.

The only tracking surface for managed destinations on this store should be DATA Reshape. Anything else either duplicates or contradicts what DATA Reshape sends server-side.

**Skipping this cleanup is the single most common cause of data anomalies on Shopify installs** — major duplication of events and conversions, double-counted revenue, mismatched attribution between destinations, inflated CPA in ad platforms, dedup logic broken end-to-end. These issues are often noticed only weeks later in destination dashboards and are painful to unwind. Do the audit before you go live.

Shopify sales channels (Facebook & Instagram, Google, TikTok) — adjust settings, don't uninstall

The official sales channel apps (Facebook & Instagram, Google, TikTok) do **more** than tracking — they sync your product catalog, manage shop on Facebook, push the merchant feed to Google Merchant Center, etc. **If any of those non-tracking features are in use, keep the channel installed** and turn off **only the tracking / data-sharing portion** so it doesn't run in parallel with DATA Reshape. Uninstall the channel only if you are not using anything from it.

For each channel app that maps to a destination DATA Reshape manages on your account, open the app's **Settings → Share data** section and set the data-sharing mode to **off** / **disabled**. Catalog sync, shop pages, merchant feed and other non-tracking features can stay on.

**Example — Facebook & Instagram sales channel:**

| Setting        | Required when DATA Reshape handles Meta tracking | Why                                                                                                                                                                                                                                                            |
| -------------- | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Share data** | `Data sharing is off`                            | Turning this on would make Shopify fire the Meta Pixel + advanced matching + Conversions API in parallel with DATA Reshape, producing double events and breaking deduplication. DATA Reshape already covers all of these from a single, deduplicated pipeline. |
| **Catalog**    | `Catalog in sync` (keep on)                      | Catalog sync feeds product data into Meta for Shops, ads and dynamic creatives — it doesn't emit tracking events. Safe and recommended to leave enabled.                                                                                                       |

Apply the same logic to the **Google** sales channel (turn off Google Tag / Enhanced Conversions data sharing, keep Merchant Center feed) and the **TikTok** sales channel (turn off Pixel / Events API data sharing, keep catalog + Shop integrations).

If DATA Reshape does **not** manage a particular destination on your account (e.g. Meta tracking handled by DATA Reshape, but Pinterest is left to the official Pinterest channel), leave that channel's data sharing on. The rule applies per destination, not blanket.

Recommended pattern: create a dedicated Liquid snippet so the tracking code lives in **one isolated file** that's trivial to find, review, and update.

### 1a. Create the snippet file[​](#1a-Create-the-snippet-file "Direct link to 1a. Create the snippet file")

Open Shopify Admin → **Online Store → Themes → … → Edit code** → in the left tree, scroll to **Snippets** → **Add a new snippet** → name it `dataReshapeCode` (file becomes `snippets/dataReshapeCode.liquid`). Paste this content:

```
{%- comment -%} DO NOT MODIFY BELOW {%- endcomment -%}
<script>
const Reshape = window.Reshape = {
    shopify: {
        config: [
            { sub: 'dre2.YOUR_DOMAIN.TLD', id: 'YOUR_SCRIPT_ID', parent: 1 }
        ]
    }
};
(function(R,e,s,h,a,p,E){function g(x){var c=(""+x).split("."),d=/\.co\.|\.com\.|\.org\.|\.edu\.|\.net\.|\.asn\./.test(x)?3:2;return c.slice(-d).join(".")}var r=g(R.location.hostname),c,i,S=h.shopify,C=S.config;for(i=0;i<C.length;i++){if(g(C[i].sub)===r){c=C[i];break}}if(!c){console.warn("[DATA Reshape] Domain not configured:",R.location.hostname);return}S.parent=c.parent;if(!c.parent)return;var _r=R._reshape=R._reshape||[];R.addEventListener("message",function(v){if(v.data&&v.data.reshape)_r.push(v.data.reshape)});h.setCookie=function(n,v,t,d){try{e.cookie=n+"="+v+";max-age="+t+";domain="+d+";path=/;SameSite=None;Secure"}catch(e){}};h.id=c.id;h.cdn=c.sub;h.sts=new Date().getTime();E=e.getElementsByTagName(s)[0];var P=e.createElement(s);P.async=true;P.src="https://"+c.sub+"/main.js?id="+c.id;E.parentNode.insertBefore(P,E);(function A(n){if(R.Shopify&&R.Shopify.analytics&&R.Shopify.analytics.publish){R.Shopify.analytics.publish("reshape:parent",{})}else if(n<60){setTimeout(function(){A(n+1)},50)}})(0)})(window,document,"script",Reshape);
</script>
```

Replace `dre2.YOUR_DOMAIN.TLD` and `YOUR_SCRIPT_ID` with the values provided to you, then save.

### 1b. Include it in `theme.liquid`[​](#1b-Include-it-in-themeliquid "Direct link to 1b-Include-it-in-themeliquid")

Open `layout/theme.liquid` (or whichever layout file your theme uses as the global wrapper) and add the render call **immediately below `{{ content_for_header }}`**, wrapped in marker comments so future editors don't move or delete it accidentally:

```
{%- comment -%} DATA RESHAPE TRACKING (PLEASE DO NOT DELETE OR MOVE) {%- endcomment -%}
{% render 'dataReshapeCode' %}
{%- comment -%} END DATA RESHAPE TRACKING {%- endcomment -%}
```

Save the file.

Position matters

The snippet must run **after** `{{ content_for_header }}` so Shopify-injected scripts initialize first. Placing it inside the `<head>` before `content_for_header` can leave the snippet initializing before Shopify is ready, delaying the coordination between the theme snippet and the Custom Pixel.

Pixel-only setup

If you are deploying in pixel-only mode, set `parent: 0` in the config. The snippet will still render, detect the mode, and exit without injecting anything in the storefront. Keeping the snippet rendered (even in pixel-only mode) makes it trivial to flip back to mixed mode later — just change `parent: 1` in the snippet file, no theme edit needed.

## Step 2 — Install the Custom Pixel[​](#Step-2--Install-the-Custom-Pixel "Direct link to Step 2 — Install the Custom Pixel")

In Shopify Admin go to **Settings → Customer events → Add custom pixel**. Name it `DATA Reshape`, configure the **Customer privacy** block as described in [the section below](#Customer-privacy-settings), and paste this code:

```
// == CONFIG =========
const Reshape = window.Reshape = {
    shopify: {
        id: '', // leave empty unless DATA Reshape support asks you to set it
        config: [
            { sub: 'dre2.YOUR_DOMAIN.TLD', id: 'YOUR_SCRIPT_ID', parent: 1 }
        ]
    }
};

// == PIXEL ==========
// NOTE: Do not modify below
(function(R,e,s,h,a,p,E){
function g(x){var c=(""+x).split("."),d=/\.co\.|\.com\.|\.org\.|\.edu\.|\.net\.|\.asn\./.test(x)?3:2;return c.slice(-d).join(".")}
var l=a?.context?.document?.location||{},o=l.hostname||"",f=l.pathname||"",w=l.origin||"*",r=g(o),c,i,S=h.shopify,C=S.config;
for(i=0;i<C.length;i++){if(g(C[i].sub)===r){c=C[i];break}}if(!c){console.warn("[DATA Reshape] Domain not configured:",o);return}
h.id=c.id;h.cdn=c.sub;h.sts=new Date().getTime();S.api=api;S.parent=c.parent;i=f&&(f.indexOf(S.id)===1||f.indexOf("checkout")===1||f.indexOf("orders")===1);
var t=c.parent&&!i,_r=R._reshape=R._reshape||[];p.subscribe("all_events",function(d){_r.push(d);if(t){try{parent.postMessage({reshape:d},w)}catch(e){}}});
function M(){E=e.getElementsByTagName(s)[0];var P=e.createElement(s);P.async=true;P.src="https://"+c.sub+"/main.js?id="+c.id;E.parentNode.insertBefore(P,E);}
if(!c.parent||i){M()}else{var y=0;p.subscribe("reshape:parent",function(){y=1});setTimeout(function(){if(!y){S.parent=0;t=0;M()}},1e3)}
})(window,document,"script", Reshape, init, analytics);
```

Replace `dre2.YOUR_DOMAIN.TLD` and `YOUR_SCRIPT_ID` with the values provided to you. Leave `shopify.id` as the empty string `''` — it is an internal hint used only for detecting a legacy Shopify URL pattern. DATA Reshape support will let you know if your store needs a non-empty value. **Save** and **Connect** the pixel.

Keep both configs in sync

The `config` array in the theme snippet and the Custom Pixel must contain the **same entries**. If they drift, the storefront and the pixel will disagree on `parent` mode or load the wrong script ID.

### Customer privacy settings[​](#Customer-privacy-settings "Direct link to Customer privacy settings")

In the Custom Pixel edit screen, the **Customer privacy** block must be set as follows. DATA Reshape **does its own consent enforcement** downstream — it reads the Shopify-native consent signal automatically, enforces per-destination consent categories (`analytics` / `personalization` / `marketing`), and applies the operating mode configured for your account. Letting Shopify gate the pixel here would short-circuit that — events would never reach DATA Reshape, so there would be nothing to enforce on.

| Field          | Value                                                                                                                              | Why                                                                                                                                                                                                                                                     |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Permission** | `Not required` *(The pixel will always run)*                                                                                       | The pixel itself must always run so DATA Reshape can apply its own per-account, per-destination consent rules (default-denied, restricted pings, replay on consent, etc.). See [Consent Overview](/events/consent/overview.md) for the operating modes. |
| **Data sale**  | `Data collected does not qualify as data sale` *(The pixel will collect data when the customer opts out of their data being sold)* | The pixel does not directly sell data — it streams to your configured destinations under your account's privacy configuration. CCPA/CPRA opt-out is honored by DATA Reshape per destination, not by suppressing the pixel here.                         |

Why not "Required" or "Data sale"?

Selecting **Required** would make Shopify suppress the pixel based on its own consent banner state, before any event reaches DATA Reshape — meaning DATA Reshape would observe nothing for opted-out visitors, and would not be able to apply Anonymous Ping, Replay-on-consent, or any other operating mode that depends on seeing the events first.

Selecting either **Data sale** variant would similarly let Shopify drop events client-side for opted-out US visitors, bypassing the per-destination opt-out signaling (Meta `data_processing_options`, TikTok `limited_data_use`, etc.) that DATA Reshape sends to each destination on your behalf.

The intent is **not** to ignore consent — it is to centralize the enforcement in DATA Reshape, which has visibility into every destination and applies the right behavior per category and per visitor.

## Configuration reference[​](#Configuration-reference "Direct link to Configuration reference")

The same shape is used in both places:

```
Reshape.shopify.config = [
    { sub: 'dre2.YOUR_DOMAIN.TLD', id: 'YOUR_SCRIPT_ID', parent: 1 }
];
```

| Field    | Type   | Required               | Purpose                                                                                                                                                   |
| -------- | ------ | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sub`    | string | yes                    | Tracking subdomain that serves the runtime script. Must share the storefront's root domain. The match also covers `www.`, `shop.`, etc.                   |
| `id`     | string | yes                    | Tracking script ID assigned by DATA Reshape. Used as `?id=...` on the runtime script URL.                                                                 |
| `parent` | number | optional (default `1`) | `1` = mixed mode (runtime script in storefront + Custom Pixel coordinating with it). `0` = pixel-only mode (runtime script inside the Custom Pixel only). |

### Multi-store config (one merchant, multiple country shops)[​](#Multi-store-config-one-merchant-multiple-country-shops "Direct link to Multi-store config (one merchant, multiple country shops)")

The right entry is auto-selected at runtime by matching the current hostname's **root domain** against `sub`. One snippet + one pixel can serve every shop.

```
config: [
    { sub: 'dre2.yourdomain.ro',  id: 'SCRIPT_ID_RO', parent: 1 },
    { sub: 'dre2.yourdomain.eu',  id: 'SCRIPT_ID_EU', parent: 0 },
    { sub: 'dre2.YOUR_DOMAIN.TLD', id: 'SCRIPT_ID_COM' }   // parent defaults to 1
]
```

## Pushing custom events[​](#Pushing-custom-events "Direct link to Pushing custom events")

Beyond the events the Custom Pixel and the optional Liquid block produce automatically, you can push any of the events documented in [Events Reference](/events.md) — `lead_created`, `email_subscribed`, `click`, custom interactions, etc.

DATA Reshape only accepts events from a single explicit channel

By design, DATA Reshape **does not process arbitrary page events** — it would let unrelated scripts pollute your data, double-count, or send malformed payloads to destinations. The only way to feed DATA Reshape from your own code is the channel below; everything else is ignored.

The right method depends on which surface your code is running on. In **mixed mode** (`parent: 1`), most theme code runs in the storefront so you use `reshape.push(...)` there; code running inside the Custom Pixel still uses the pixel-side method below. In **pixel-only mode** (`parent: 0`), only the pixel-side method is available.

* Storefront (theme / theme apps)
* Custom Pixel

Available when `parent: 1` is configured. Use it from `theme.liquid`, any other Liquid template, theme JS files, or third-party storefront apps:

```
window.reshape = window.reshape || [];
reshape.push({
  event: {
    name: "lead_created",
    value: 250,
    currency: "USD",
    id: "lead_abc123"
  },
  user: {
    email: "example.customer@example.com",
    first_name: "Example First Name"
  }
});
```

Available in any mode, from inside the Custom Pixel code. Uses Shopify's [Web Pixels API emitting method](https://shopify.dev/docs/api/web-pixels-api/emitting-data) on the dedicated `reshape:push` channel:

```
const reshapeData = {
  event: {
    name: "lead_created",
    value: 250,
    currency: "USD",
    id: "lead_abc123"
  },
  user: {
    email: "example.customer@example.com",
    first_name: "Example First Name"
  }
};

Shopify.analytics.publish('reshape:push', reshapeData);
```

`reshapeData` has the exact same shape as the object you would pass to `reshape.push(...)` in the storefront — see [Events Reference](/events.md) for the payload of each event.

## Optional — product page enrichment[​](#Optional--product-page-enrichment "Direct link to Optional — product page enrichment")

The Custom Pixel covers the standard storefront and checkout events automatically (`product_viewed` on PDP, `product_added_to_cart`, `checkout_started`, `checkout_completed`, etc.). On Online Store 2.0 themes you can additionally push a **richer `product_viewed` payload** from `theme.liquid` so destinations receive variant images, categories, parent SKU and logged-in customer data — fields the Custom Pixel does not surface on its own.

Paste this immediately after the snippet block, still in `theme.liquid`:

```
{%- comment -%}
  =====================================================================
  DATA Reshape — product page enrichment (optional)
  ---------------------------------------------------------------------
  Sends a richer `product_viewed` payload from the storefront when a
  product template is rendered. Includes variant images, categories,
  parent SKU and logged-in customer data — fields the Custom Pixel
  cannot surface on its own.

  Deduplicated server-side against the Custom Pixel's `product_viewed`,
  so adding this block never produces double counts.

  Safe to remove or comment out — DATA Reshape will keep working from
  the Custom Pixel alone, with a lighter `product_viewed` payload.
  =====================================================================
{%- endcomment -%}

{%- if template contains 'product' -%}
{% liquid
  assign created_timestamp = product.created_at | date: '%s' | times: 1000
  assign total_price = 0
  for variant in product.variants
    assign total_price = total_price | plus: variant.price
  endfor
  assign average_price = total_price | times: 1.0 | divided_by: product.variants.size | times: 0.01
%}
<script>
window.reshape = window.reshape || [];
window.reshape.push({
  "event": {
    "name": "product_viewed",
    "value": {{ average_price | round: 2 }},
    "currency": {{ shop.currency | json }}
  },
  "context": {
    "environment": "prod",
    "page_type": "product"
  },
  "products": [
    {% for variant in product.variants %}
    {
      "id": "{{ variant.id }}",
      "parent_id": "{{ product.id }}",
      "sku": {{ variant.sku | json }},
      "parent_sku": {{ product.variants.first.sku | json }},
      {% if variant.barcode != blank %}"gtin": {{ variant.barcode | json }},{% endif %}
      "name": {{ product.title | json }},
      "parent_name": {{ product.title | json }},
      "brand": {{ product.vendor | json }},
      "type": {% if product.variants.size > 1 %}"variable"{% else %}"simple"{% endif %},
      "price_base": {% if variant.compare_at_price > 0 %}{{ variant.compare_at_price | times: 0.01 | round: 2 }}{% else %}{{ variant.price | times: 0.01 | round: 2 }}{% endif %},
      "price": {{ variant.price | times: 0.01 | round: 2 }},
      "currency": {{ shop.currency | json }},
      "tax_included": {{ shop.taxes_included }},
      "quantity": 1,
      "stock_status": {{ variant.available }},
      "created_at": {{ created_timestamp }},
      "url": {{ variant.url | prepend: shop.secure_url | json }},
      "parent_url": {{ product.url | prepend: shop.secure_url | json }},
      "image": {{ variant.featured_image.src | default: product.featured_image.src | image_url: width: 1024 | prepend: 'https:' | json }},
      "images": [
        {% for image in product.images limit: 5 %}
        {{ image.src | image_url: width: 1024 | prepend: 'https:' | json }}{% unless forloop.last %},{% endunless %}
        {% endfor %}
      ],
      "category": {{ product.type | json }},
      "categories": [
        {% for collection in product.collections limit: 5 %}
        { "name": {{ collection.title | json }}, "id": "{{ collection.id }}" }{% unless forloop.last %},{% endunless %}
        {% endfor %}
      ],
      "properties": {
        {% assign variant_values = "" %}
        {% for option in variant.options %}
          {% if option %}
            {% if variant_values != "" %}{% assign variant_values = variant_values | append: " / " %}{% endif %}
            {% assign variant_values = variant_values | append: option %}
          {% endif %}
        {% endfor %}
        "variant": {{ variant_values | json }}
      }
    }{% unless forloop.last %},{% endunless %}
    {% endfor %}
  ]
  {% if customer %},
  "user": {
    "id": "{{ customer.id }}",
    "email": {{ customer.email | json }},
    {% if customer.phone %}"phone": {{ customer.phone | json }},{% endif %}
    "first_name": {{ customer.first_name | json }},
    "last_name": {{ customer.last_name | json }},
    {% if customer.default_address %}
    "country": {{ customer.default_address.country | json }},
    "region": {{ customer.default_address.province | json }},
    "city": {{ customer.default_address.city | json }},
    "street": {{ customer.default_address.street | json }},
    "postal_code": {{ customer.default_address.zip | json }},
    {% endif %}
    "orders_total_number": {{ customer.orders_count }},
    "orders_total_value": {{ customer.total_spent | times: 0.01 | round: 2 }},
    "created_at": {{ customer.created_at | date: '%s' | times: 1000 }}
  }
  {% endif %}
});
</script>
{%- endif -%}
```

DATA Reshape **deduplicates** the enriched push against the Web Pixels `product_viewed` automatically, so adding this block never produces double counts.

## Why these permissions?[​](#Why-these-permissions "Direct link to Why these permissions?")

| Asset                               | Why                                                                                                              |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Theme code edit**                 | To insert the snippet in `theme.liquid` for mixed mode.                                                          |
| **Customer events**                 | The only surface in Shopify where `checkout` / `thank-you` / `order status` events are observable.               |
| **Partner access** *(if requested)* | Lets the DATA Reshape team install the snippet and pixel on your behalf without exposing your admin credentials. |

## Verification[​](#Verification "Direct link to Verification")

End-to-end verification is performed by the DATA Reshape team. Reach out at **<support@datareshape.ro>** once the snippet and the Custom Pixel are installed, and we will run the confirmation tests, validate the data flowing to each connected destination, and confirm the configuration is correct.

Why DATA Reshape verifies the data

The tracking surface is built **privacy-first**: payloads are obfuscated, PII is normalized and hashed before it leaves the browser, sensitive parameters are encrypted at rest, identity is partitioned per account, and destination-specific protections (such as opt-out signals, data-minimization filters, and limited-use modes) are applied server-side before any downstream call.

Because of these advanced privacy and tracking protections, **the data observable from the outside is intentionally not enough to validate quality on your own**. DATA Reshape is the only party with the visibility needed to confirm that events, identifiers, conversions, and destination deliveries are correct end-to-end.

Privacy by design is a feature of the platform, not an inconvenience — it's what keeps the implementation compliant out of the box and protects your customers' data regardless of which destinations you connect later.

## Troubleshooting[​](#Troubleshooting "Direct link to Troubleshooting")

Most installation-time issues you can fix yourself surface as a single browser console message:

| Symptom                                                          | Likely cause                                             | Fix                                                                                     |
| ---------------------------------------------------------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `[DATA Reshape] Domain not configured: …` in the browser console | The active hostname's root doesn't match any `sub` entry | Add the right `sub` for this store, or correct a typo. The match uses root domain only. |

For anything beyond this — events that don't seem to arrive, deduplication concerns, destination-side discrepancies, or any other doubt about data quality — please contact **<support@datareshape.ro>**. By design, the only reliable view into event flow and destination delivery is the internal one; we'll confirm the state, identify the cause, and guide the fix.

## Next steps[​](#Next-steps "Direct link to Next steps")

1. **Confirm destinations** — see [Destinations](/destinations.md) for per-platform setup.
2. **Add custom events** — see [Events Reference](/events.md) for the full catalog of events DATA Reshape can capture on Shopify beyond what the Custom Pixel covers automatically.
3. **Validate consent flow** — see [Consent Overview](/events/consent/overview.md) for how Shopify-native consent signals are picked up automatically.


---

# WordPress Implementation Guide

Multiple methods to implement DATA Reshape tracking on WordPress. Choose the one that fits your setup.

## Prerequisites[​](#Prerequisites "Direct link to Prerequisites")

Required Before Implementation

Only implement after receiving confirmation that your custom domain and SSL certificate are active.

You will need:

* **Custom tracking subdomain** (e.g. `dre2.YOUR_DOMAIN.TLD`)
* **Script ID** provided by the DATA Reshape team

Implementation support — DATA Reshape can do this for you

You do not have to install everything by yourself. DATA Reshape provides **hands-on implementation support** and will perform the setup, audit, verification, and per-destination configuration on your WordPress site. To enable that, please create a dedicated **Administrator account** for us and email the credentials to **<wordpress@datareshape.ro>**.

* **Role:** Administrator (required to edit theme files, manage plugins, and access caching / security settings).
* **Recommended:** create a fresh user (e.g. `datareshape`) instead of sharing an existing one — easier to track activity and revoke.
* **Access can be revoked** at any time once the installation and verification are confirmed live.

After access is granted, DATA Reshape will install the tracking code (theme / functions / plugin method, whichever is safest for your setup), audit and clean up duplicate destination code, adjust any conflicting caching/minification settings, and run the end-to-end verification — then report back when everything is live.

## Method 1: Official DATA Reshape plugin (Recommended for WooCommerce)[​](#Method-1-Official-DATA-Reshape-plugin-Recommended-for-WooCommerce "Direct link to Method 1: Official DATA Reshape plugin (Recommended for WooCommerce)")

The fastest and safest install for **WooCommerce** stores — the official DATA Reshape plugin published on wordpress.org:

**[DATA Reshape for WooCommerce](https://wordpress.org/plugins/datalayer-tracking-datareshape-woocommerce)**

What it does:

* Injects the DATA Reshape tracking code on every front-end page (no theme edits, survives theme updates).
* Auto-maps WooCommerce events — product viewed, add/remove to cart, checkout started, order placed, etc. — into the DATA Reshape event vocabulary, so most ecommerce events flow without any custom coding.
* Reads the configured tracking subdomain and Script ID from a single settings page.

Install steps:

1. In WordPress admin → **Plugins → Add New** → search `DATA Reshape WooCommerce` (or use the [direct link](https://wordpress.org/plugins/datalayer-tracking-datareshape-woocommerce)).
2. Click **Install Now** → **Activate**.
3. Open the plugin's settings page → set **Tracking subdomain** (e.g. `dre2.YOUR_DOMAIN.TLD`) and **Script ID** → **Save**.
4. Clear any caching plugins.

For **non-WooCommerce** WordPress sites, use one of the manual install methods below (Theme header, functions.php, child theme, or a generic headers-and-footers plugin). The events still need to be pushed from the page, but the tracking code itself loads exactly the same way.

## Method 2: Theme header.php[​](#Method-2-Theme-headerphp "Direct link to Method 2: Theme header.php")

The most reliable manual method when the plugin doesn't apply — works across all WordPress configurations.

1. Go to **Appearance → Theme Editor** → select **header.php**
2. Add this code **before** the `</head>` tag:

```
<!-- DATA Reshape Tracking Code -->
<script>
(function(R,e,s,h,a,p,E){
  var b=R.Reshape=R.Reshape||{};
  b.setCookie=function(n,v,t,d){try{e.cookie=n+'='+v+';max-age='+t+';domain='+d+';path=/;SameSite=None;Secure';}catch(e){}};
  b.id=a;b.cdn=h;b.sts=new Date().getTime();
  E=e.getElementsByTagName(s)[0];p=e.createElement(s);p.async=true;p.src="https://"+h+"/main.js?id="+a;E.parentNode.insertBefore(p,E);
})(window,document,"script","YOUR_SUBDOMAIN","YOUR_SCRIPT_ID");
</script>
<?php wp_head(); ?>
</head>
```

3. Click **Update File** and clear any caching plugins

Theme Updates

Changes to theme files are lost during theme updates. Use a child theme or the functions.php method for persistence.

## Method 3: functions.php[​](#Method-3-functionsphp "Direct link to Method 3: functions.php")

Programmatic implementation via WordPress hooks. Add to the end of **Appearance → Theme Editor → functions.php**:

```
function add_data_reshape_tracking() {
    $subdomain = 'YOUR_SUBDOMAIN';
    $script_id = 'YOUR_SCRIPT_ID';
    
    if (!is_admin()) {
        ?>
        <script>
        (function(R,e,s,h,a,p,E){
            var b=R.Reshape=R.Reshape||{};
            b.setCookie=function(n,v,t,d){try{e.cookie=n+'='+v+';max-age='+t+';domain='+d+';path=/;SameSite=None;Secure';}catch(e){}};
            b.id=a;b.cdn=h;b.sts=new Date().getTime();
            E=e.getElementsByTagName(s)[0];p=e.createElement(s);p.async=true;p.src="https://"+h+"/main.js?id="+a;E.parentNode.insertBefore(p,E);
        })(window,document,"script","<?php echo esc_js($subdomain); ?>","<?php echo esc_js($script_id); ?>");
        </script>
        <?php
    }
}
add_action('wp_head', 'add_data_reshape_tracking');
```

## Method 4: Insert Headers and Footers Plugin[​](#Method-4-Insert-Headers-and-Footers-Plugin "Direct link to Method 4: Insert Headers and Footers Plugin")

If you prefer not to edit theme files:

1. **Plugins → Add New** → search "Insert Headers and Footers" → install and activate
2. **Settings → Insert Headers and Footers** → paste in **Scripts in Header**:

```
<script>
(function(R,e,s,h,a,p,E){
  var b=R.Reshape=R.Reshape||{};
  b.setCookie=function(n,v,t,d){try{e.cookie=n+'='+v+';max-age='+t+';domain='+d+';path=/;SameSite=None;Secure';}catch(e){}};
  b.id=a;b.cdn=h;b.sts=new Date().getTime();
  E=e.getElementsByTagName(s)[0];p=e.createElement(s);p.async=true;p.src="https://"+h+"/main.js?id="+a;E.parentNode.insertBefore(p,E);
})(window,document,"script","YOUR_SUBDOMAIN","YOUR_SCRIPT_ID");
</script>
```

3. Click **Save** and clear cache

## Method 5: Child Theme[​](#Method-5-Child-Theme "Direct link to Method 5: Child Theme")

For persistence during theme updates. Create `/wp-content/themes/your-child-theme/functions.php`:

```
<?php
function add_data_reshape_tracking() {
    if (!is_admin()) {
        ?>
        <script>
        (function(R,e,s,h,a,p,E){
            var b=R.Reshape=R.Reshape||{};
            b.setCookie=function(n,v,t,d){try{e.cookie=n+'='+v+';max-age='+t+';domain='+d+';path=/;SameSite=None;Secure';}catch(e){}};
            b.id=a;b.cdn=h;b.sts=new Date().getTime();
            E=e.getElementsByTagName(s)[0];p=e.createElement(s);p.async=true;p.src="https://"+h+"/main.js?id="+a;E.parentNode.insertBefore(p,E);
        })(window,document,"script","YOUR_SUBDOMAIN","YOUR_SCRIPT_ID");
        </script>
        <?php
    }
}
add_action('wp_head', 'add_data_reshape_tracking');
```

## Caching Plugins[​](#Caching-Plugins "Direct link to Caching Plugins")

| Plugin             | Action                                                                     |
| ------------------ | -------------------------------------------------------------------------- |
| **WP Rocket**      | Settings → File Optimization → add subdomain to Excluded Inline JavaScript |
| **W3 Total Cache** | Performance → Minify → add to "Never minify" JS list                       |
| **WPEngine**       | No configuration needed                                                    |

## Verification[​](#Verification "Direct link to Verification")

End-to-end verification is performed by the DATA Reshape team. Reach out at **<support@datareshape.ro>** once the tracking code is installed, and we will run the confirmation tests, validate the data flowing to each connected destination, and confirm the configuration is correct.

Why DATA Reshape verifies the data

The tracking surface is built **privacy-first**: payloads are obfuscated, PII is normalized and hashed before it leaves the browser, sensitive parameters are encrypted at rest, identity is partitioned per account, and destination-specific protections (such as opt-out signals, data-minimization filters, and limited-use modes) are applied server-side before any downstream call.

Because of these advanced privacy and tracking protections, **the data observable from the outside is intentionally not enough to validate quality on your own**. DATA Reshape is the only party with the visibility needed to confirm that events, identifiers, conversions, and destination deliveries are correct end-to-end.

Privacy by design is a feature of the platform, not an inconvenience — it's what keeps the implementation compliant out of the box and protects your customers' data regardless of which destinations you connect later.

## Troubleshooting[​](#Troubleshooting "Direct link to Troubleshooting")

A few WordPress-specific install-time issues you can fix yourself:

| Symptom                                                            | Likely cause                                                                                              | Fix                                                                                                                                           |
| ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| Script not present in page source                                  | `wp_head()` is not called inside `header.php`, or the chosen install method does not run on the front end | Confirm `wp_head()` is invoked in your theme's `<head>`, or switch to the **Insert Headers and Footers** plugin method.                       |
| Script loads on some pages only                                    | Install method is template-specific (e.g. only single posts)                                              | Ensure the method runs on every page type (homepage, pages, posts, categories, products if WooCommerce).                                      |
| Script suppressed after enabling a security or minification plugin | Plugin conflict                                                                                           | Temporarily deactivate security/minification plugins and confirm the script reappears; whitelist the subdomain in the plugin's configuration. |
| Old script appears even after replacing the code                   | Page or object cache still serves an older response                                                       | Clear all caches (WP cache, CDN, browser) and re-test in incognito. See the **Caching Plugins** table above.                                  |

For anything beyond install-time visibility — events that don't seem to arrive, deduplication concerns, destination-side discrepancies, or any other doubt about data quality — please contact **<support@datareshape.ro>**. By design, the only reliable view into event flow and destination delivery is the internal one; we'll confirm the state, identify the cause, and guide the fix.


---

# Allow Monitoring Your Tracking

## Why am I receiving "Website Inaccessible" alerts?[​](#Why-am-I-receiving-Website-Inaccessible-alerts "Direct link to Why am I receiving \"Website Inaccessible\" alerts?")

DATA Reshape automatically monitors your site every few minutes to verify that your tracking setup is installed and functioning correctly.

If your site uses a **firewall**, **WAF (Web Application Firewall)**, or **bot protection service**, the monitor may be blocked before it can verify your tracking. When this happens, you will receive alerts such as:

* **Website Inaccessible** — the monitor received a non-200 response or a timeout
* **Cloudflare Challenge Blocking** — the monitor received a Cloudflare challenge/CAPTCHA page instead of your actual site

These alerts do not mean your tracking is broken — they mean the monitor cannot reach your site to verify it.

## How to identify the DATA Reshape monitor[​](#How-to-identify-the-DATA-Reshape-monitor "Direct link to How to identify the DATA Reshape monitor")

Every monitoring request includes the following identifiers:

### Custom HTTP header[​](#Custom-HTTP-header "Direct link to Custom HTTP header")

Every request includes the header:

```
x-dre-monitor
```

The value of this header may vary (e.g. `basic`, `advanced`) and can change over time. **Your firewall rule should match on the header name only, not on a specific value.** This ensures it continues to work regardless of future changes.

### User-Agent[​](#User-Agent "Direct link to User-Agent")

The User-Agent string always contains `(DATA Reshape)`. Examples:

```
Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 ... Chrome/145.0.0.0 Safari/537.36 (DATA Reshape)
Mozilla/5.0 (iPhone; CPU iPhone OS 18_7 like Mac OS X) AppleWebKit/605.1.15 ... Safari/604.1 (DATA Reshape)
```

### No fixed IP address[​](#No-fixed-IP-address "Direct link to No fixed IP address")

The monitor runs on distributed cloud infrastructure. IP addresses may change at any time, so **IP-based whitelisting is not recommended**.

## General instructions (any firewall)[​](#General-instructions-any-firewall "Direct link to General instructions (any firewall)")

Regardless of which firewall or WAF provider you use, the steps are the same:

1. **Create a rule** that matches requests containing the header `x-dre-monitor` (match on header name, not value)
2. **Set the action** to allow/skip/bypass bot protection for matching requests
3. **Place the rule** above (higher priority than) any blocking rules
4. **Deploy** and verify — the DATA Reshape alerts should resolve automatically within a few minutes

If your firewall does not support matching on custom headers, use the User-Agent string instead — match requests where the User-Agent contains `(DATA Reshape)`.

tip

The custom header method (`x-dre-monitor`) is preferred because User-Agent strings are easily spoofed, while custom headers are harder to guess.

***

## Cloudflare[​](#Cloudflare "Direct link to Cloudflare")

Cloudflare is the most common case where the DATA Reshape monitor gets blocked, especially when **Bot Fight Mode** or **Super Bot Fight Mode** is enabled.

### Option A: WAF Custom Rule (recommended)[​](#Option-A-WAF-Custom-Rule-recommended "Direct link to Option A: WAF Custom Rule (recommended)")

**1.** Log in to the [Cloudflare Dashboard](https://dash.cloudflare.com/) and select your domain.

**2.** Go to **Security** → **WAF** → **Custom rules**.

**3.** Click **Create rule**.

**4.** Configure:

* **Rule name:** `Allow DATA Reshape Monitor`
* **Field:** Header
* **Operator:** exists
* **Value:** `x-dre-monitor`
* **Action:** Skip → select **All remaining custom rules**, **Bot Fight Mode**, and **Super Bot Fight Mode**

**5.** Drag the rule to **position 1** (highest priority).

**6.** Click **Deploy**.

### Alternative: Expression Editor[​](#Alternative-Expression-Editor "Direct link to Alternative: Expression Editor")

If you prefer the expression editor, use:

```
(len(http.request.headers["x-dre-monitor"]) > 0)
```

Action: **Skip** → All remaining custom rules, Bot Fight Mode, Super Bot Fight Mode.

### Verifying it works[​](#Verifying-it-works "Direct link to Verifying it works")

After deploying, check **Security** → **Events** in the Cloudflare Dashboard. You should see requests with the `x-dre-monitor` header being skipped instead of challenged. The DATA Reshape alert will resolve automatically at the next check cycle.

***

## Sucuri[​](#Sucuri "Direct link to Sucuri")

**1.** Log in to the [Sucuri Dashboard](https://dashboard.sucuri.net/) and select your site.

**2.** Go to **Access Control** → **Header Allow**.

**3.** Add a rule to allow requests that contain the header `x-dre-monitor`.

If header-based rules are not available on your plan, go to **Access Control** → **User-Agent Allow** and add `DATA Reshape` as an allowed User-Agent string.

***

## Akamai[​](#Akamai "Direct link to Akamai")

**1.** In the Akamai Control Center, open your **Security Configuration**.

**2.** Go to **Custom Rules** or **Rate Controls**.

**3.** Create an exception rule:

* Match condition: Request header `x-dre-monitor` is present
* Action: Allow

**4.** Place the rule above any bot mitigation or rate limiting rules.

**5.** Activate the configuration.

***

## AWS WAF (CloudFront)[​](#AWS-WAF-CloudFront "Direct link to AWS WAF (CloudFront)")

**1.** In the AWS Console, go to **WAF & Shield** → **Web ACLs**.

**2.** Select your Web ACL.

**3.** Add a new rule with priority above your blocking rules:

* Rule type: Regular rule
* Match condition: Header `x-dre-monitor` is present
* Action: Allow

**4.** Save and deploy.

***

## Other providers[​](#Other-providers "Direct link to Other providers")

For any firewall or bot protection not listed above, the principle is the same:

1. Find the section for custom rules, exceptions, or whitelisting
2. Create a rule matching requests that contain the header `x-dre-monitor`
3. Set the action to allow/bypass
4. Ensure it has higher priority than blocking rules

If you need help with a specific provider, contact us at **<support@datareshape.ro>**.

## FAQ[​](#FAQ "Direct link to FAQ")

### Will this weaken my site's security?[​](#Will-this-weaken-my-sites-security "Direct link to Will this weaken my site's security?")

No. The rule only bypasses bot protection for requests containing the `x-dre-monitor` header. All other traffic remains fully protected.

### Why not whitelist by IP address?[​](#Why-not-whitelist-by-IP-address "Direct link to Why not whitelist by IP address?")

The DATA Reshape monitor runs on distributed cloud infrastructure (Cloudflare Workers). Source IP addresses are shared and may change without notice. Header-based identification is reliable and does not require maintenance.

### What happens if I don't add the rule?[​](#What-happens-if-I-dont-add-the-rule "Direct link to What happens if I don't add the rule?")

The monitor will continue to be blocked, and you will keep receiving "Website Inaccessible" or "Cloudflare Challenge Blocking" alerts. Your tracking will still work normally for real visitors — only the automated monitoring check is affected.

### How do I know the rule is working?[​](#How-do-I-know-the-rule-is-working "Direct link to How do I know the rule is working?")

After adding the rule, any active "Website Inaccessible" alert from DATA Reshape will automatically resolve within a few minutes (at the next monitoring cycle). You can also check your firewall's request logs for the `x-dre-monitor` header.


---

# Custom Domain Setup

DATA Reshape uses a subdomain on your own domain (e.g. `dre2.YOUR_DOMAIN.TLD`) to collect tracking data as first-party. This avoids ad blockers and third-party cookie restrictions, improving data accuracy.

## Prerequisites[​](#Prerequisites "Direct link to Prerequisites")

You will need:

* **Domain control** — administrative access to your domain's DNS settings
* **Subdomain choice** — we recommend `dre2` but any available subdomain works
* **Contact with DATA Reshape** — to receive the SSL validation target and confirm activation

Ad Blocker Prevention

Avoid obvious tracking-related names like `ads`, `track`, `pixel`, or `analytics` — these are commonly blocked.

## Platform-Specific Guides[​](#Platform-Specific-Guides "Direct link to Platform-Specific Guides")

For Cloudflare or cPanel, use the dedicated guides instead:

| DNS Provider                                     | Guide                                                |
| ------------------------------------------------ | ---------------------------------------------------- |
| Cloudflare                                       | [Cloudflare Setup](/general/subdomain/cloudflare.md) |
| cPanel hosting (HostGator, Bluehost, SiteGround) | [cPanel Setup](/general/subdomain/cpanel.md)         |

The steps below cover most other DNS providers: GoDaddy, Namecheap, and similar.

## Configuration Steps[​](#Configuration-Steps "Direct link to Configuration Steps")

### 1. Access DNS Management[​](#1-Access-DNS-Management "Direct link to 1. Access DNS Management")

Log into your domain registrar or hosting provider and navigate to DNS settings. Common labels: "Manage DNS", "DNS Zone Editor", "Advanced DNS", "Domain Settings".

### 2. Create Both CNAME Records[​](#2-Create-Both-CNAME-Records "Direct link to 2. Create Both CNAME Records")

Add both records in your DNS management panel:

| Type  | Name                   | Target                                                     | TTL         |
| ----- | ---------------------- | ---------------------------------------------------------- | ----------- |
| CNAME | `dre2`                 | `app.datareshape.net`                                      | Auto / 3600 |
| CNAME | `_acme-challenge.dre2` | `dre2.YOUR_DOMAIN.TLD.5c7e7c9aba529dca.dcv.cloudflare.com` | Auto / 3600 |

The first record routes tracking requests. The second is for automatic SSL certificate provisioning.

warning

Replace **`YOUR_DOMAIN.TLD`** with your actual domain everywhere in the table above — both in the Name and Target fields.

info

Some providers require the full domain format (e.g. `dre2.YOUR_DOMAIN.TLD` instead of `dre2`). Try short format first.

### 3. Verify[​](#3-Verify "Direct link to 3. Verify")

**DNS check:**

```
nslookup dre2.YOUR_DOMAIN.TLD
# Should resolve to: app.datareshape.net
```

**SSL check:** visit `https://dre2.YOUR_DOMAIN.TLD` — you should see a valid SSL certificate once provisioned (allow 24-48h).

## Provider Notes[​](#Provider-Notes "Direct link to Provider Notes")

**GoDaddy** — DNS → Manage Zones → Add Record. Use short format: `dre2`.

**Namecheap** — Advanced DNS → Add New Record. Use short format: `dre2`.

**Other providers** — try short format first (`dre2`), then full format (`dre2.YOUR_DOMAIN.TLD`) if it doesn't work.

## Troubleshooting[​](#Troubleshooting "Direct link to Troubleshooting")

| Issue                    | Solution                                                                                           |
| ------------------------ | -------------------------------------------------------------------------------------------------- |
| Cannot find DNS settings | Check if DNS is managed externally (Cloudflare, etc.). Look for "Zone Editor" or "Domain Settings" |
| CNAME conflict           | Remove any existing A, AAAA, or TXT records for the same subdomain first                           |
| Error about format       | Try short format vs full format — some providers auto-complete the domain                          |
| Not resolving after 24h+ | Verify values are exactly correct. Use a DNS checker tool                                          |

## Next Steps[​](#Next-Steps "Direct link to Next Steps")

1. Contact the DATA Reshape team at <support@datareshape.ro> to confirm setup completion
2. Once confirmed, implement the tracking code — see [Global Code Setup](/general/global-code.md)


---

# Cloudflare DNS Configuration

Cloudflare requires specific proxy settings for DATA Reshape to work. Both CNAME records **must** use DNS only (gray cloud).

Critical

Cloudflare's proxy (orange cloud) **must be disabled** for your tracking subdomain. The orange cloud interferes with SSL certificate provisioning and tracking functionality.

## Configuration Steps[​](#Configuration-Steps "Direct link to Configuration Steps")

### 1. Access Cloudflare DNS[​](#1-Access-Cloudflare-DNS "Direct link to 1. Access Cloudflare DNS")

Log into [Cloudflare Dashboard](https://dash.cloudflare.com) → select your domain → **DNS** in the left sidebar.

### 2. Create Both CNAME Records[​](#2-Create-Both-CNAME-Records "Direct link to 2. Create Both CNAME Records")

Click **"Add record"** and add both:

| Type  | Name                   | Target                                                     | Proxy       | TTL  |
| ----- | ---------------------- | ---------------------------------------------------------- | ----------- | ---- |
| CNAME | `dre2`                 | `app.datareshape.net`                                      | ☁️ DNS only | Auto |
| CNAME | `_acme-challenge.dre2` | `dre2.YOUR_DOMAIN.TLD.5c7e7c9aba529dca.dcv.cloudflare.com` | ☁️ DNS only | Auto |

The first record routes tracking requests. The second is for automatic SSL certificate provisioning.

warning

Replace **`YOUR_DOMAIN.TLD`** with your actual domain everywhere in the table above — both in the Name and Target fields.

## Troubleshooting[​](#Troubleshooting "Direct link to Troubleshooting")

| Issue                             | Solution                                                             |
| --------------------------------- | -------------------------------------------------------------------- |
| Tracking failures, timeout errors | Check proxy status — click orange cloud to turn it gray              |
| SSL certificate errors            | Verify both CNAME records exist. Wait 24-48h for provisioning        |
| CNAME not resolving               | Check record names and targets are exactly correct                   |
| Intermittent tracking failures    | Verify gray cloud. Check Cloudflare security rules and rate limiting |

## Next Steps[​](#Next-Steps "Direct link to Next Steps")

Contact the DATA Reshape team at <support@datareshape.ro> to confirm setup completion.


---

# cPanel DNS Configuration

For shared hosting providers using cPanel: HostGator, Bluehost, SiteGround, and others.

## Configuration Steps[​](#Configuration-Steps "Direct link to Configuration Steps")

### 1. Access Zone Editor[​](#1-Access-Zone-Editor "Direct link to 1. Access Zone Editor")

Login to cPanel → find **"Zone Editor"** in the Domains section → click **"Manage"** for your domain.

### 2. Create Both CNAME Records[​](#2-Create-Both-CNAME-Records "Direct link to 2. Create Both CNAME Records")

Click **"Add Record"** and add both:

| Type  | Name                                    | Target                                                     | TTL   |
| ----- | --------------------------------------- | ---------------------------------------------------------- | ----- |
| CNAME | `dre2.YOUR_DOMAIN.TLD.`                 | `app.datareshape.net`                                      | 14400 |
| CNAME | `_acme-challenge.dre2.YOUR_DOMAIN.TLD.` | `dre2.YOUR_DOMAIN.TLD.5c7e7c9aba529dca.dcv.cloudflare.com` | 14400 |

The first record routes tracking requests. The second is for automatic SSL certificate provisioning.

warning

Replace **`YOUR_DOMAIN.TLD`** with your actual domain everywhere in the table above — both in the Name and Target fields.

cPanel Format

cPanel typically requires the full subdomain with a trailing dot (e.g. `dre2.YOUR_DOMAIN.TLD.`). Some cPanel versions auto-complete this.

## Troubleshooting[​](#Troubleshooting "Direct link to Troubleshooting")

| Issue                          | Solution                                                                    |
| ------------------------------ | --------------------------------------------------------------------------- |
| Cannot find Zone Editor        | Search "DNS" or "Zone" in cPanel. Contact hosting provider if not available |
| Permission denied              | Contact hosting provider to request DNS modification permissions            |
| Records disappear after saving | Check for conflicting records. Try with/without trailing dot                |
| Invalid format error           | Try short format (`dre2`) vs full format (`dre2.YOUR_DOMAIN.TLD.`)          |

## Next Steps[​](#Next-Steps "Direct link to Next Steps")

Contact the DATA Reshape team at <support@datareshape.ro> to confirm setup completion.


---

# Objects Overview

Data objects are the building blocks of the DATA Reshape tracking system. These standardized structures ensure consistent tracking across all events and implementations — both web (JavaScript) and webhook (server-to-server).

## Objects[​](#Objects "Direct link to Objects")

### Event & Context[​](#Event--Context "Direct link to Event & Context")

**[Event Object](/objects/event.md)** Core structure for all tracked events. Contains event name, value, currency, unique ID, and custom properties.

**[Context Object - Web](/objects/context-web.md)** Browser context for web implementations. Page URL, page type, and environment. Most data is collected automatically — manual setup needed only for SPAs.

**[Context Object - API](/objects/context-api.md)** Server-side context for webhook implementations. Environment, data source, user agent, IP address, and URL context preserved from the original user session.

### E-commerce[​](#E-commerce "Direct link to E-commerce")

**[Product Object](/objects/product.md)** Product identification, pricing, inventory, categories, images, product-level coupons, and custom properties. Used in all product-related events.

**[Shipping Object](/objects/shipping.md)** Shipping method, cost, and tax information. Required for checkout and shipping events.

**[Payment Object](/objects/payment.md)** Payment method, amount, and type. Supports split payments with multiple methods per order.

**[Coupon Object](/objects/coupon.md)** Discount codes and promotional offers with value, tax information, and classification. Applied at order-level or product-level.

### User & Consent[​](#User--Consent "Direct link to User & Consent")

**[User Object](/objects/user.md)** Customer identification, contact information, geographic data, order history, and custom properties. Send email and phone as plaintext only — hashing is handled automatically.

**[Consent Object](/objects/consent-api.md)** User consent preferences for analytics, personalization, and marketing data processing.

**[Cookies Object](/objects/cookies.md)** Flat key-value map of browser cookies for platform attribution. Only cookies mapped by DATA Reshape are processed.

## Implementation[​](#Implementation "Direct link to Implementation")

All objects use the same structure for both web and API implementations. The only differences are in the context object (web vs API) and how data is collected (automatically via JavaScript or manually via webhooks).

Start with the required fields and add optional data progressively. The more complete the data, the better the attribution and audience matching across destinations.

Per-destination parameter restrictions

Independently of the objects you send, **each destination can be configured to receive only a subset of these parameters** — typically to enforce data-minimization for PII fields (email, phone, address, etc.) or to align with the consent state. The configuration is set per destination at account setup. See the [Consent Overview](/events/consent/overview.md) for a full description of how this interacts with consent and operating modes.


---

# Consent Object

## Overview[​](#Overview "Direct link to Overview")

The consent object defines the user's explicit preferences regarding data collection and processing. It ensures that all downstream processing, reporting, and platform integrations respect the user's privacy choices.

It contains three required boolean categories that control data usage, plus an optional identifier:

* **analytics** — consent for collecting data used in performance monitoring and usage statistics
* **personalization** — consent for collecting data used to tailor user experiences and customize content
* **marketing** — consent for collecting data used in advertising, remarketing, and campaign measurement
* **id** *(optional)* — a stable identifier from your CMP (or any internal reference) that links the consent record to a verifiable source. Required when the [audit-trail persistence](/events/consent/overview.md#Audit-trail) feature is enabled on the account.

Consent values gate other objects

The values you send in the consent object directly influence **what DATA Reshape is allowed to forward from the other objects** in the same payload — primarily fields considered PII (email, phone, names, address) in the `user` object, and identifiers in `cookies` and `context`. The exact restrictions per consent category are defined at account setup and can vary per destination. Consider this object the gatekeeper for everything else in the payload, not just an informational flag.

## Complete Reference[​](#Complete-Reference "Direct link to Complete Reference")

expand all ▾collapse all ▸

**consent** object

**analytics** boolean required

info

Indicates the user’s explicit consent regarding the collection and processing of data for analytical purposes, such as performance monitoring, usage statistics, and service optimization.

```
analytics: true
```

**personalization** boolean required

info

Indicates the user’s explicit consent regarding the collection and processing of data for personalization purposes, enabling tailored experiences and content customization.

```
personalization: true
```

**marketing** boolean required

info

Indicates the user’s explicit consent regarding the collection and processing of data for marketing purposes, such as targeted advertising, remarketing, and campaign measurement.

```
marketing: true
```

**id** string

info

Optional consent-record identifier. When present, DATA Reshape can persist or relay the consent decision under this ID — useful when you want each stored decision to be tied to a verifiable reference from your Consent Management Platform (CMP consent ID, IAB TC string hash, internal record ID, etc.). Required when the optional audit-trail persistence feature is enabled on the account.

```
id: "consent_record_abc123"
```

## Examples[​](#Examples "Direct link to Examples")

* Standard
* With consent id

```
{
  "analytics": true,
  "personalization": false,
  "marketing": true
}
```

The common shape — three required boolean categories. Use this when you do **not** need to persist a consent-record reference for audit purposes.

```
{
  "analytics": true,
  "personalization": false,
  "marketing": true,
  "id": "consent_record_abc123"
}
```

Add `id` when your account has [audit-trail persistence](/events/consent/overview.md#Audit-trail) enabled, or when you want each stored consent decision tied to a verifiable reference from your CMP (CMP consent ID, IAB TC string hash, internal record ID, etc.).


---

# Context API Object

## Overview[​](#Overview "Direct link to Overview")

The context object captures the server-side environment data for each event sent through the API. It preserves the original user interaction details (user agent, IP address, URLs) that are required for accurate attribution and analytics in server-to-server implementations.

## Properties[​](#Properties "Direct link to Properties")

* **environment** *(required)* — `prod` for live data, `dev` for testing. Events sent with `dev` are logged but not processed. Using the `/test` endpoint suffix forces `dev` regardless of this value.
* **data\_source** — identifies the origin system (e.g. `website`, `app`, `admin`, `phone`, `crm`). Free-form string, use consistent naming.
* **user\_agent** — the original browser user agent string, preserved from the user's session
* **override\_ip** — the original user's IP address. If not provided, the IP from the request headers is used automatically.
* **url** — the page URL where the action occurred. If not provided, a fallback is generated from your account configuration.
* **landing\_url** — the first page URL of the user's session
* **referrer\_url** — the external URL that brought the user to the site

## Complete Reference[​](#Complete-Reference "Direct link to Complete Reference")

expand all ▾collapse all ▸

**context** object

**environment** string required

info

Allowed values: prod, dev

```
environment: "prod"
```

**data\_source** string recommended

info

Identifies the origin system the event came from. If omitted, the worker falls back to a default value derived from your account configuration.

Recommended values:

* for website events: **website**
* for admin manual added orders events: **phone** or **admin**
* for app events: **app**
* for marketplace events: **marketplace** (you can replace "marketplace" with the real marketplace name)

```
data_source: "website"
```

**user\_agent** string recommended

info

User-Agent string from a browser when the event occurs

```
user_agent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/138.0.0.0 Safari/537.36"
```

**override\_ip** string recommended

info

Ip address. Support ipv4 or ipv6. Recommended ipv6 if exists.

```
override_ip: "203.0.113.1"
```

**url** string recommended

info

URL of the page where the event occurred

```
url:"https://example.com/thank-you"
```

**landing\_url** string recommended

info

URL of the first page visited in the session where the event occurred

```
landing_url:"https://example.com/landing-page?utm_source=example"
```

**referrer\_url** string recommended

info

URL of the external referring site

```
referrer_url:"https://example-search.com"
```

## Examples[​](#Examples "Direct link to Examples")

* E-commerce Order
* CRM / Phone Order
* Admin Manual Order
* Minimal

```
{
  "environment": "prod",
  "data_source": "website",
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/138.0.0.0 Safari/537.36",
  "override_ip": "203.0.113.1",
  "url": "https://example.com/checkout/confirmation",
  "landing_url": "https://example.com/products/prod_abc123?utm_source=example&utm_medium=cpc",
  "referrer_url": "https://example-search.com/search"
}
```

```
{
  "environment": "prod",
  "data_source": "phone",
  "url": "https://example.com/contact-us",
  "landing_url": "https://example.com/pricing?utm_campaign=example_campaign",
  "referrer_url": "https://example-social.com/company/example"
}
```

```
{
  "environment": "prod",
  "data_source": "admin",
  "override_ip": "203.0.113.2",
  "url": "https://admin.example.com/orders/create"
}
```

```
{
  "environment": "prod",
  "data_source": "website"
}
```

## Collecting Context Data (PHP)[​](#Collecting-Context-Data-PHP "Direct link to Collecting Context Data (PHP)")

Context data must be collected during the original user session and preserved for later webhook transmission:

```
// Collect during user session
$contextData = [
    'user_agent' => $_SERVER['HTTP_USER_AGENT'] ?? '',
    'override_ip' => $_SERVER['HTTP_X_FORWARDED_FOR'] ?? $_SERVER['REMOTE_ADDR'] ?? '',
    'url' => (isset($_SERVER['HTTPS']) ? 'https' : 'http') . '://' . $_SERVER['HTTP_HOST'] . $_SERVER['REQUEST_URI'],
    'landing_url' => $_SESSION['landing_url'] ?? '',
    'referrer_url' => $_SESSION['referrer_url'] ?? ''
];

// Store in session/database for later use in webhook payload
$_SESSION['tracking_context'] = $contextData;
```

```
// Later, when sending the webhook (e.g. on order completion)
$payload = [
    'event' => [ /* ... */ ],
    'context' => array_merge([
        'environment' => 'prod',
        'data_source' => 'website'
    ], $_SESSION['tracking_context']),
    // ...
];
```

## Best Practices[​](#Best-Practices "Direct link to Best Practices")

* **Preserve original context** — always use the original user's user agent and IP address, not the server's
* **Collect early** — capture context data at session start (landing URL, referring URL) and store for later use
* **Use `dev` for testing** — set `environment` to `dev` during integration to validate payloads without processing
* **Consistent data sources** — use a standardized naming convention for `data_source` across your implementations
* **HTTPS only** — always transmit context data over HTTPS


---

# Context Web Object

## Overview[​](#Overview "Direct link to Overview")

The context web object captures browser environment data for events collected through JavaScript implementations. Most context data (URL, environment) is collected automatically by the DATA Reshape script. Manual implementation is only needed for SPA applications or when you want to specify `page_type` for more granular analytics.

## Properties[​](#Properties "Direct link to Properties")

* **url** — collected automatically for standard websites. Required only for SPA applications where URL changes don't trigger automatic page context updates.
* **page\_type** — categorizes the current page for analytics (e.g. `product`, `category`, `cart`, `checkout`, `home`, `blog`, `contact`). Free-form string, use consistent naming across your site.
* **environment** — `prod` for live data, `dev` for testing. Events sent with `dev` are logged but not processed.

## Complete Reference[​](#Complete-Reference "Direct link to Complete Reference")

expand all ▾collapse all ▸

**context** object

**url** string required-if-applicable

info

Collected automatically for standard websites. Required only for SPA applications where URL changes don't trigger automatic page context updates.

```
url:"https://example.com/products/prod_abc123?utm_source=example"
```

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"
```

## Examples[​](#Examples "Direct link to Examples")

* Standard Website
* SPA Application
* Development

```
{
  "page_type": "product",
  "environment": "prod"
}
```

URL is collected automatically. Only `page_type` and `environment` need to be specified.

```
{
  "url": "https://example.com/dashboard/analytics?date_range=30d",
  "page_type": "dashboard",
  "environment": "prod"
}
```

For SPA applications, `url` must be provided manually on each route change since the browser URL doesn't update automatically.

```
{
  "page_type": "product",
  "environment": "dev"
}
```

Events with `dev` environment are logged for debugging but not processed or forwarded to destinations.

## SPA Implementation[​](#SPA-Implementation "Direct link to SPA Implementation")

For Single Page Applications, push a new event with updated context on each route change:

```
// On each SPA route change, push a new event with the current route URL
window.reshape = window.reshape || [];
reshape.push({
  event: {
    name: "page_viewed"
  },
  context: {
    url: currentRouteUrl, // Current route URL from your framework's router
    page_type: "dashboard",
    environment: "prod"
  }
});
```

## Best Practices[​](#Best-Practices "Direct link to Best Practices")

* **Consistent page types** — use a standardized naming convention for `page_type` across your site
* **SPA route tracking** — ensure context updates on every significant route change
* **Use `dev` for testing** — set `environment` to `dev` during integration to validate events without processing
* **URL sensitivity** — be mindful of sensitive information in URL parameters (session tokens, personal identifiers); consider filtering before tracking


---

# Cookies Object

## Overview[​](#Overview "Direct link to Overview")

The cookies object is a flat key-value map containing browser cookies required by tracking platforms and advertising destinations. This object is designed for server-side tracking where cookie values must be collected from the original user session and transmitted through the API to enable proper attribution across advertising platforms and analytics destinations.

Include only cookies required by the client's active destinations.

## Structure[​](#Structure "Direct link to Structure")

Cookies are transmitted as a flat object where each key is the cookie name and each value is the cookie value. Both must be strings.

```
{
  "_ga": "GA1.2.123456789.1640995200",
  "_gcl_aw": "GCL.1640995200.CjwKCAiA",
  "_fbp": "fb.1.1640995200.123456789"
}
```

If cookies are not available or the format is invalid, an empty object `{}` will be used.

## What Cookies Can You Send?[​](#What-Cookies-Can-You-Send "Direct link to What Cookies Can You Send?")

You can send any cookie that is relevant for tracking and attribution — this includes both platform-proprietary cookies (like `_ga`, `_fbp`, `_ttp`) and custom cookies specific to your implementation (like `custom_session_id`, `affiliate_ref`).

However, there is an important distinction: **a cookie is only processed and forwarded to a destination if it has been mapped by DATA Reshape with a defined purpose for that specific destination**. Any cookie that is not mapped will be accepted in the payload but silently ignored during processing.

This means you can safely send all tracking-related cookies you have available — DATA Reshape will pick up and use only the ones that are relevant for each active destination. There is no penalty for sending extra cookies, but sending cookies that have no tracking purpose (like session tokens, CSRF tokens, or UI preference cookies) adds unnecessary payload size.

info

The list of mapped cookies per destination is managed by DATA Reshape and evolves as new platform integrations are added. You do not need to know which cookies are mapped — just send all tracking-related cookies and DATA Reshape will handle the rest.

## Example[​](#Example "Direct link to Example")

```
{
  // Platform cookies — processed if destination is active and cookie is mapped
  "_ga": "GA1.2.123456789.1640995200",
  "_gcl_aw": "GCL.1640995200.CjwKCAiA",
  "_fbp": "fb.1.1640995200.123456789",
  "_fbc": "fb.1.1640995200.AbCdEfGhIjKlMnOp",
  "_ttp": "123456789.abcdefgh",

  // Custom cookies — processed only if mapped by DATA Reshape
  "affiliate_ref": "example_partner_ref",
  "landing_campaign": "example_campaign_2025"
}
```

## Cookie Collection (Server-Side)[​](#Cookie-Collection-Server-Side "Direct link to Cookie Collection (Server-Side)")

Since cookies are only available in API implementations, they must be collected during the user's browser session and sent via webhook:

```
// Collect cookies server-side for webhook transmission
$requiredCookies = ['_ga', '_gid', '_gcl_aw', '_fbp', '_fbc', '_ttp'];
$cookies = [];

foreach ($requiredCookies as $name) {
    if (isset($_COOKIE[$name]) && !empty($_COOKIE[$name])) {
        $cookies[$name] = $_COOKIE[$name];
    }
}
```

## Usage in Webhook Payload[​](#Usage-in-Webhook-Payload "Direct link to Usage in Webhook Payload")

```
$payload = [
    'event' => [
        'name' => 'checkout_completed',
        'value' => 299.99,
        'currency' => 'USD',
        'id' => 'ord_abc123'
    ],
    'context' => [
        'environment' => 'prod',
        'data_source' => 'website'
    ],
    'cookies' => [
        '_ga' => 'GA1.2.123456789.1640995200',
        '_gcl_aw' => 'GCL.1640995200.CjwKCAiA',
        '_fbp' => 'fb.1.1640995200.123456789'
    ],
    'user' => [
        'email' => 'example.customer@example.com'
    ]
];
```

## Best Practices[​](#Best-Practices "Direct link to Best Practices")

* **Required Cookies Only** — include only cookies needed by client's active platforms
* **Valid Values** — ensure cookie values are current and properly formatted
* **Consent Compliance** — respect user privacy preferences; include marketing cookies only with marketing consent
* **Session Preservation** — collect cookies during user session for later API use; store them in session or database for delayed order processing
* **HTTPS Only** — always use HTTPS for API calls containing cookie data


---

# Coupon Object

## Overview[​](#Overview "Direct link to Overview")

The coupon object represents a single discount code or promotional offer applied to an order or product. It captures the discount value, tax implications, and coupon classification for promotion tracking and marketing analytics.

Coupons can be applied at two levels:

* **Order-level** — in the top-level `coupons` array, applied to the entire order
* **Product-level** — inside a product's `coupons` array, applied to a specific product

## Complete Reference[​](#Complete-Reference "Direct link to Complete Reference")

expand all ▾collapse all ▸

**coupons\[0]** object

**name** string required

info

Coupon name or code.

```
name: "EXAMPLE_COUPON"
```

**value** number recommended

info

Coupon discount value.

```
value: 123.99
```

**tax\_included** boolean recommended

info

Whether coupon value includes taxes

```
tax_included: true
```

**tax\_percent** number recommended

info

Tax percentage for the coupon

```
tax_percent: 21
```

**id** string

info

Coupon internal identifier.

```
id: "cpn_abc123"
```

**type** string

info

Coupon type. Free-form string, use consistent naming (e.g. "LOYALTY", "SEASONAL", "FIRST\_ORDER", "SHIPPING").

```
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
```

## Examples[​](#Examples "Direct link to Examples")

* Percentage Discount
* Fixed Amount
* Free Shipping
* Multiple Coupons

```
{
  "name": "EXAMPLE_SEASONAL",
  "value": 29.99,
  "tax_included": true,
  "tax_percent": 19,
  "id": "cpn_seasonal_abc123",
  "type": "SEASONAL",
  "currency": "USD",
  "exchange_rate": 1
}
```

```
{
  "name": "EXAMPLE_FIXED",
  "value": 25.00,
  "tax_included": true,
  "tax_percent": 19,
  "id": "cpn_fixed_abc123",
  "type": "FIXED_AMOUNT",
  "currency": "USD",
  "exchange_rate": 1
}
```

```
{
  "name": "EXAMPLE_FREESHIP",
  "value": 15.99,
  "tax_included": true,
  "tax_percent": 0,
  "id": "cpn_freeship_abc123",
  "type": "SHIPPING"
}
```

```
[
  {
    "name": "EXAMPLE_FIRSTORDER",
    "value": 60.00,
    "tax_included": true,
    "tax_percent": 19,
    "id": "cpn_first_abc123",
    "type": "FIRST_ORDER"
  },
  {
    "name": "EXAMPLE_FREESHIP",
    "value": 12.99,
    "tax_included": true,
    "tax_percent": 0,
    "id": "cpn_freeship_xyz789",
    "type": "SHIPPING"
  }
]
```

## Order-Level vs Product-Level[​](#Order-Level-vs-Product-Level "Direct link to Order-Level vs Product-Level")

### Order-Level Coupons[​](#Order-Level-Coupons "Direct link to Order-Level Coupons")

Applied to the entire order in the top-level `coupons` array:

```
{
  "event": { "name": "checkout_completed", "id": "ord_abc123" },
  "coupons": [
    {
      "name": "EXAMPLE_ORDER_COUPON",
      "value": 45.00,
      "tax_included": true,
      "tax_percent": 19,
      "type": "PROMOTIONAL"
    }
  ]
}
```

### Product-Level Coupons[​](#Product-Level-Coupons "Direct link to Product-Level Coupons")

Applied to a specific product inside the product's `coupons` array:

```
{
  "products": [
    {
      "id": "prod_abc123",
      "name": "Example Product Name",
      "price": 999.99,
      "coupons": [
        {
          "name": "EXAMPLE_PRODUCT_COUPON",
          "value": 100.00,
          "tax_included": true,
          "tax_percent": 19,
          "type": "PRODUCT_SPECIFIC"
        }
      ]
    }
  ]
}
```

## Best Practices[​](#Best-Practices "Direct link to Best Practices")

* **Accurate values** — ensure coupon values reflect the actual discount amount applied, not the coupon's potential value
* **Consistent naming** — use standardized coupon code naming conventions
* **Tax information** — include accurate tax calculations; if `tax_percent` is not provided, the default from your account configuration is used
* **Currency** — only specify `currency` and `exchange_rate` when the coupon's currency differs from the event currency
* **Type classification** — use consistent `type` values for campaign analytics (e.g. "SEASONAL", "LOYALTY", "FIRST\_ORDER", "SHIPPING", "PROMOTIONAL")


---

# Event Object

## Overview[​](#Overview "Direct link to Overview")

The event object is the core structure for all tracked events. It captures the event type, monetary value, currency, unique identifier, and custom properties for tracking and analytics.

The `name` field determines how the event is processed and which destination APIs receive it. The `id` field is required for events that need deduplication (e.g. `checkout_completed`, `order_canceled`). Only events that are mapped in your account configuration will be accepted.

## Complete Reference[​](#Complete-Reference "Direct link to Complete Reference")

expand all ▾collapse all ▸

**event** object

<!-- -->

**name** string required

info

Name of the event to be sent.

```
name: "event_name"
```

**value** number required

info

Event value in decimal format. Represent the final total order amount, including all costs and discounts.

```
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 required-if-applicable

info

Event ID — required for transactions or any actions that require deduplication or uniqueness. Represents the unique identifier of a transaction, order, or lead. This can be the unique order, transaction, or action ID used in your system.

```
id: "ord_abc123"
```

**reason** string

info

Short human-readable reason associated with a lifecycle event — the cancellation reason for `order_canceled`, or the disqualification reason for `lead_disqualified`. Free-form string; keep it short and consistent across your implementations so it can be grouped for reporting.

```
reason: "out_of_stock"
```

**properties** object recommended

info

**Custom Event Properties Examples**

* Ecommerce Order
* B2B Lead
* Subscription Service

```
properties: {
  fulfillment_method: "delivery",
  gift_wrap: "true"
}
```

```
properties: {
  lead_status: "converted",
  sales_stage: "proposal"
}
```

```
properties: {
  subscription_tier: "premium",
  billing_cycle: "annual",
  trial_user: "false",
  renewal_date: "2025-06-30",
  support_level: "priority",
  usage_frequency: "daily"
}
```

## Examples[​](#Examples "Direct link to Examples")

* Checkout Completed
* Lead Created
* Product Viewed
* Order Canceled
* Minimal

```
{
  "name": "checkout_completed",
  "value": 299.99,
  "currency": "USD",
  "exchange_rate": 1,
  "id": "ord_abc123",
  "properties": {}
}
```

```
{
  "name": "lead_created",
  "value": 250.00,
  "currency": "USD",
  "id": "lead_abc123",
  "properties": {}
}
```

```
{
  "name": "product_viewed",
  "value": 149.99,
  "currency": "USD"
}
```

```
{
  "name": "order_canceled",
  "value": 0,
  "currency": "USD",
  "id": "ord_abc123",
  "reason": "customer_request"
}
```

```
{
  "name": "page_viewed",
  "value": 0,
  "currency": "USD"
}
```

## Event ID[​](#Event-ID "Direct link to Event ID")

The `id` field serves different purposes depending on the event type:

* **Transaction events** (`checkout_completed`, `order_canceled`) — `id` is required and used for deduplication. Events with duplicate IDs are not processed again per destination.
* **Non-transaction events** (`product_viewed`, `page_viewed`, etc.) — `id` is optional. If not provided, a unique ID is generated automatically.

## Event Value[​](#Event-Value "Direct link to Event Value")

The `value` field is the monetary impact of the event. For most events it is simply the amount involved (lead value, product price, etc.), but two events have a **strict, canonical composition** the framework depends on:

Canonical rule — event.value for checkout\_completed and order\_canceled

* **`checkout_completed`** — `value` MUST always equal **products + shipping + any other costs − order-level coupons, with tax INCLUDED**.
* **`order_canceled`** — `value` MUST always equal **only the value of the returned/canceled products, with tax INCLUDED** — no shipping, no other costs.

These compositions are a hard contract. The framework uses them to correctly derive tax-excluded and shipping-excluded values per destination (GA4 value overrides, Google Ads conversion values, refund adjustments). Sending anything else (net values, totals with shipping on refunds, tax-excluded amounts) produces wrong destination values — fix the integration, never expect the framework to compensate.

## Event Reason[​](#Event-Reason "Direct link to Event Reason")

The optional `reason` field is a short, human-readable string that captures the **why** behind a lifecycle event. Prefer it over a custom property so the value lands in a predictable, queryable place across destinations.

Common values:

* `order_canceled` → `"customer_request"`, `"out_of_stock"`, `"payment_declined"`
* `lead_disqualified` → `"out_of_icp"`, `"no_budget"`, `"no_authority"`, `"duplicate"`

Keep the value short (snake\_case recommended) and consistent across implementations so it can be grouped for reporting.

## Custom Properties[​](#Custom-Properties "Direct link to Custom Properties")

The `properties` object allows you to attach any custom key-value data to an event. Use it for business-specific attributes that enable segmentation and analytics in your destinations.

```
{
  "properties": {
    "payment_method": "credit_card",
    "customer_type": "returning",
    "coupon_code": "EXAMPLE_COUPON",
    "checkout_duration": 180
  }
}
```

Keep custom properties focused — limit to 5-10 key properties per event for optimal performance across destinations.

## Currency and Exchange Rate[​](#Currency-and-Exchange-Rate "Direct link to Currency and Exchange Rate")

The `currency` field applies to all monetary values in the event and its nested objects (products, shipping, coupons). Nested objects can override `currency` and `exchange_rate` individually when they use a different currency.

```
{
  "name": "checkout_completed",
  "value": 1299.99,
  "currency": "USD",
  "exchange_rate": 0.22
}
```

## Best Practices[​](#Best-Practices "Direct link to Best Practices")

* **Consistent event names** — use the same event names across all implementations for accurate tracking
* **Accurate values** — ensure `value` reflects the actual monetary impact (order total, lead value, etc.); for `checkout_completed` and `order_canceled` follow the canonical composition in [Event Value](#Event-Value)
* **Unique IDs for transactions** — always provide a unique `id` for `checkout_completed` and `order_canceled` to prevent duplicate processing
* **Focused properties** — include only properties that enable actionable insights in your destinations
* **Currency consistency** — use the same currency code across related events when possible


---

# Payment Object

## Overview[​](#Overview "Direct link to Overview")

The payment object represents a single payment method used in a transaction. An order can have multiple payment objects when the customer uses split payments (e.g. gift card + credit card).

Each payment captures the method name, amount paid, and payment classification. The sum of all payment values should match the order total.

## Complete Reference[​](#Complete-Reference "Direct link to Complete Reference")

expand all ▾collapse all ▸

**payments\[0]** object

**name** string required

info

Payment method name.

```
name: "Example Payment Method"
```

**value** number required

info

Amount paid with this payment method

```
value: 12.99
```

**id** string

info

Payment method internal identifier

```
id: "pay_abc123"
```

**type** string

info

Payment type. Free-form string, use consistent naming (e.g. "card", "paypal", "bank\_transfer", "gift\_card", "cash\_on\_delivery").

```
type: "card"
```

## Examples[​](#Examples "Direct link to Examples")

* Single Payment
* Split Payment
* Cash on Delivery
* Bank Transfer

```
{
  "name": "Example Card Payment",
  "value": 299.99,
  "id": "pay_abc123",
  "type": "card"
}
```

```
[
  {
    "name": "Example Gift Card",
    "value": 50.00,
    "id": "pay_gift_abc123",
    "type": "gift_card"
  },
  {
    "name": "Example Card Payment",
    "value": 249.99,
    "id": "pay_card_xyz789",
    "type": "card"
  }
]
```

```
{
  "name": "Example Cash on Delivery",
  "value": 149.99,
  "type": "cash_on_delivery"
}
```

```
{
  "name": "Example Bank Transfer",
  "value": 1299.99,
  "id": "pay_bank_abc123",
  "type": "bank_transfer"
}
```

## Best Practices[​](#Best-Practices "Direct link to Best Practices")

* **Accurate amounts** — ensure payment values reflect actual transaction amounts; the sum of all payments should equal the order total
* **Consistent naming** — use standardized payment method names across events
* **Type classification** — use consistent `type` values for reporting (e.g. "card", "paypal", "bank\_transfer", "gift\_card", "cash\_on\_delivery", "buy\_now\_pay\_later")
* **No sensitive data** — never include full card numbers, CVV, or other sensitive payment details; use last four digits or tokenized IDs only
* **Split payments** — when a customer pays with multiple methods, include each as a separate object in the `payments` array


---

# Product Object

## Overview[​](#Overview "Direct link to Overview")

The product object represents a single product or product variant in an e-commerce event. It captures identification, pricing, inventory, categorization, and custom properties for tracking and audience segmentation.

Required fields are `id`, `name`, `price`, `price_base`, `tax_included`, `tax_percent`, and `quantity`. Fields like `parent_id`, `parent_name`, and `parent_sku` default to their non-parent counterparts if not provided. `tax_included` defaults to `true`, `quantity` defaults to 1, `stock_status` defaults to `true`, and `tax_percent` defaults to the site's configured rate if not provided.

## Complete Reference[​](#Complete-Reference "Direct link to Complete Reference")

expand all ▾collapse all ▸

**products\[0]** object

**id** string required

info

Unique product identifier in your system.

```
id: "prod_abc123"
```

**parent\_id** string recommended

info

Parent product ID for variants or child products. Defaults to `id` if not provided.

```
parent_id: "prod_parent_xyz789"
```

**name** string required

info

Product name or title displayed to users.

```
name: "Example Product Name"
```

**parent\_name** string

info

Parent product name for variants or child products. Defaults to `name` if not provided.

```
parent_name: "Example Parent Product Name"
```

**price\_base** number required

info

Original or base price before discounts. Always equal to or greater than `price`.

```
price_base: 299.99
```

**price** number required

info

Current selling price after discounts. Always equal to or less than `price_base`.

```
price: 249.99
```

**tax\_included** boolean required

info

Whether the price includes taxes. Defaults to `true` if not provided.

```
tax_included: true
```

**tax\_percent** number required

info

Tax percentage applied to the product (0-50). If not provided, the site default tax rate will be used (generally the standard rate of the country).

```
tax_percent: 19
```

**quantity** number required

info

Quantity of this product in the context of the event. Defaults to 1 if not provided.

```
quantity: 2
```

**category** string recommended

info

Main product category name

```
category: "Example Category"
```

**sku** string

info

Product SKU (Stock Keeping Unit) for inventory tracking

```
sku: "sku_abc123"
```

**parent\_sku** string

info

Parent product SKU for variants or child products. Defaults to `sku` if not provided.

```
parent_sku: "sku_parent_xyz789"
```

**gtin** string

info

Global Trade Item Number for product identification

```
gtin: "1234567890123"
```

**mpn** string

info

Manufacturer Part Number assigned by the manufacturer

```
mpn: "MPN-EXAMPLE-001"
```

**ean** string

info

European Article Number for product barcoding

```
ean: "1234567890123"
```

**brand** string

info

Product brand or manufacturer name

```
brand: "Example Brand"
```

**type** string

info

Product type. Free-form string (e.g. "simple", "variable", "bundle", "subscription").

```
type: "simple"
```

**stock\_status** boolean | number | string recommended

info

Product availability, accepted in any of these forms:

* **boolean** — `true` (in stock) / `false` (out of stock)
* **number** — `> 0` = in stock, `0` or negative = out of stock
* **string** — the following (case-insensitive) are treated as **out of stock**: `0`, `no`, `nu`, `false`, `out of stock`, `sold out`, `unavailable`, `indisponibil`, `fara stoc`, `stoc epuizat`.

Any other value is treated as **in stock**. Defaults to `true` (in stock) if not provided.

```
stock_status: true
```

**stock\_location** string

info

Physical location or warehouse where product is stored

```
stock_location: "Example Warehouse"
```

**created\_at** number

info

Timestamp when product was added to inventory (milliseconds)

```
created_at: 1748505040077
```

**url** string

info

Direct URL to the product page

```
url: "https://example.com/products/prod_abc123"
```

**parent\_url** string

info

URL to the parent product page (for variants)

```
parent_url: "https://example.com/products/prod_parent_xyz789"
```

**image** string

info

Main product image URL

```
image: "https://example.com/cdn/prod_abc123-main.jpg"
```

**images** array

info

Array of additional product image URLs

```
images: [
  "https://example.com/cdn/prod_abc123-1.jpg",
  "https://example.com/cdn/prod_abc123-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: "Example Category", id: "cat_abc123" },
  { name: "Example Subcategory", id: "cat_xyz789" }
]
```

**coupons** array

info

Array of product-level coupons applied to this product. [**View complete Coupon Object documentation**](/objects/coupon.md)

**coupons\[0]** (object) - `required`

**name** string required

info

Coupon name or code.

```
name: "EXAMPLE_COUPON"
```

**value** number recommended

info

Coupon discount value.

```
value: 123.99
```

**tax\_included** boolean recommended

info

Whether coupon value includes taxes

```
tax_included: true
```

**tax\_percent** number recommended

info

Tax percentage for the coupon

```
tax_percent: 21
```

**id** string

info

Coupon internal identifier.

```
id: "cpn_abc123"
```

**type** string

info

Coupon type. Free-form string, use consistent naming (e.g. "LOYALTY", "SEASONAL", "FIRST\_ORDER", "SHIPPING").

```
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. Free-form key-value object. Use properties that match your product catalog and business needs.

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.

* IT & C
* Fashion
* Deco

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

```
properties: {
  color: ["black", "white"],
  size: "M",
  material: "cotton",
  fit: "regular", 
  season: "summer",
  collection: "2024_spring",
  care_instructions: "machine_wash"
}
```

```
properties: {
  color: ["natural", "oak"],
  dimensions: "120x80x75cm",
  material: ["wood", "metal"],
  style: "modern",
  room_type: ["living_room", "office"],
  assembly_required: "true"
}
```

**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
```

## Examples[​](#Examples "Direct link to Examples")

* Complete
* Variable Product
* Minimal

```
{
  "id": "prod_abc123",
  "parent_id": "prod_parent_xyz789",
  "name": "Example Product Name",
  "parent_name": "Example Parent Product Name",
  "price_base": 299.99,
  "price": 249.99,
  "tax_included": true,
  "tax_percent": 19,
  "quantity": 1,
  "category": "Example Category",
  "sku": "sku_abc123",
  "parent_sku": "sku_parent_xyz789",
  "gtin": "1234567890123",
  "mpn": "MPN-EXAMPLE-001",
  "ean": "1234567890123",
  "brand": "Example Brand",
  "type": "simple",
  "stock_status": true,
  "stock_location": "Example Warehouse",
  "created_at": 1748505040077,
  "url": "https://example.com/products/prod_abc123",
  "parent_url": "https://example.com/products/prod_parent_xyz789",
  "image": "https://example.com/cdn/prod_abc123-main.jpg",
  "images": [
    "https://example.com/cdn/prod_abc123-1.jpg",
    "https://example.com/cdn/prod_abc123-2.jpg"
  ],
  "categories": [
    { "name": "Example Category", "id": "cat_abc123" },
    { "name": "Example Subcategory", "id": "cat_xyz789" }
  ],
  "coupons": [
    {
      "name": "EXAMPLE_COUPON",
      "value": 50.00,
      "tax_included": true,
      "tax_percent": 19,
      "type": "AUTOMATED"
    }
  ],
  "properties": {
    "color": "example_color",
    "connectivity": ["example_option_a", "example_option_b"],
    "feature_a": "active",
    "feature_b": "30_hours"
  }
}
```

```
{
  "id": "prod_variant_abc123",
  "parent_id": "prod_parent_xyz789",
  "name": "Example Variant Name - Size M",
  "parent_name": "Example Parent Product Name",
  "price_base": 89.99,
  "price": 79.99,
  "tax_included": true,
  "tax_percent": 19,
  "quantity": 1,
  "category": "Example Category",
  "sku": "sku_variant_abc123",
  "parent_sku": "sku_parent_xyz789",
  "brand": "Example Brand",
  "type": "variable",
  "url": "https://example.com/products/prod_variant_abc123",
  "parent_url": "https://example.com/products/prod_parent_xyz789",
  "image": "https://example.com/cdn/prod_variant_abc123.jpg",
  "categories": [
    { "name": "Example Category", "id": "cat_abc123" },
    { "name": "Example Subcategory", "id": "cat_xyz789" }
  ],
  "properties": {
    "color": "example_color",
    "size": "M",
    "material": "example_material"
  }
}
```

```
{
  "id": "prod_abc123",
  "name": "Example Product Name",
  "price_base": 29.99,
  "price": 29.99,
  "tax_included": true,
  "tax_percent": 19,
  "quantity": 1
}
```

All required fields provided. Missing optional fields like `parent_id`, `parent_name`, `parent_sku` will default to their base counterparts.

## Price Logic[​](#Price-Logic "Direct link to Price Logic")

* `price` is the final selling price; `price_base` is the reference/list price (before any product-level discount).
* If `price_base` is not provided, it defaults to `price`.
* `price_base` is always kept equal to or greater than `price`. If a lower `price_base` is sent, it is raised to equal `price` — `price` itself is never changed.
* Negative prices are set to 0.

## Parent Fields[​](#Parent-Fields "Direct link to Parent Fields")

For variable products (variants), parent fields provide the connection to the main product:

* `parent_id` — defaults to `id` if not provided
* `parent_name` — defaults to `name` if not provided
* `parent_sku` — defaults to `sku` if not provided
* `parent_url` — not defaulted, omitted if empty

## Best Practices[​](#Best-Practices "Direct link to Best Practices")

* **Consistent IDs** — use the same product IDs across all events for accurate tracking
* **Accurate pricing** — ensure `price_base` and `price` reflect actual values; the system corrects inverted prices automatically
* **Custom properties** — use properties that enable meaningful audience segmentation (color, size, material, etc.); keep naming consistent across products
* **Categories** — provide hierarchical categories from broad to specific for better analytics
* **Currency** — only specify `currency` and `exchange_rate` when the product currency differs from the event currency
* **Product-level coupons** — use the `coupons` array for discounts applied to specific products; use the top-level `coupons` array for order-wide discounts


---

# Shipping Object

## Overview[​](#Overview "Direct link to Overview")

The shipping object represents a single shipping method or delivery option used in a transaction. An order can have multiple shipping objects when items are shipped separately (split shipments).

Each shipping captures the method name, cost, tax information, and delivery classification.

## Complete Reference[​](#Complete-Reference "Direct link to Complete Reference")

expand all ▾collapse all ▸

**shipping\[0]** object

**name** string required

info

Shipping method name

```
name: "Example Shipping Method"
```

**value** number required

info

Shipping cost value

```
value: 12.99
```

**tax\_included** boolean recommended

info

Whether shipping cost includes taxes

```
tax_included: true
```

**tax\_percent** number recommended

info

Tax percentage for shipping (0-50)

```
tax_percent: 19
```

**id** string

info

Shipping method identifier.

```
id: "shp_abc123"
```

**type** string

info

Shipping type. Free-form string, use consistent naming (e.g. "standard", "express", "next\_day", "pickup", "free").

```
type: "standard"
```

**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
```

## Examples[​](#Examples "Direct link to Examples")

* Standard Shipping
* Express Shipping
* Free Shipping
* Store Pickup
* Split Shipments

```
{
  "name": "Example Standard Shipping",
  "value": 15.99,
  "tax_included": true,
  "tax_percent": 19,
  "id": "shp_abc123",
  "type": "standard"
}
```

```
{
  "name": "Example Express Shipping",
  "value": 29.99,
  "tax_included": true,
  "tax_percent": 19,
  "id": "shp_express_abc123",
  "type": "express"
}
```

```
{
  "name": "Example Free Shipping",
  "value": 0.00,
  "tax_included": true,
  "tax_percent": 0,
  "type": "free"
}
```

```
{
  "name": "Example Store Pickup",
  "value": 0.00,
  "tax_included": true,
  "tax_percent": 0,
  "type": "pickup"
}
```

```
[
  {
    "name": "Example Shipping - Package 1",
    "value": 12.99,
    "tax_included": true,
    "tax_percent": 19,
    "id": "shp_pkg1_abc123",
    "type": "standard"
  },
  {
    "name": "Example Shipping - Package 2",
    "value": 24.99,
    "tax_included": true,
    "tax_percent": 19,
    "id": "shp_pkg2_xyz789",
    "type": "express"
  }
]
```

## Best Practices[​](#Best-Practices "Direct link to Best Practices")

* **Accurate costs** — ensure shipping values reflect real costs including taxes
* **Tax information** — include accurate tax calculations; if `tax_percent` is not provided, the default from your account configuration is used
* **Currency** — only specify `currency` and `exchange_rate` when the shipping currency differs from the event currency
* **Type classification** — use consistent `type` values for analytics (e.g. "standard", "express", "next\_day", "overnight", "free", "pickup")
* **Split shipments** — when items ship separately, include each shipment as a separate object in the `shipping` array


---

# User Object

## Overview[​](#Overview "Direct link to Overview")

The user object represents a customer or visitor interacting with your website or application. It captures identification, contact information, geographic data, order history, and custom properties for user segmentation and personalization across destinations.

No fields are strictly required — include as much data as available. The more complete the user data, the better the attribution and audience matching across advertising platforms.

Email and phone must be provided as plaintext only — do not send pre-hashed values. DATA Reshape automatically normalizes and hashes all PII before sending to destinations.

## Complete Reference[​](#Complete-Reference "Direct link to Complete Reference")

expand all ▾collapse all ▸

**user** object

**id** string recommended

info

Unique customer identifier in your system.

```
id: "cust_abc123"
```

**email** string recommended

info

Customer email address in plaintext. Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.

```
email: "example.customer@example.com"
```

**phone** string recommended

info

Customer phone number in E.164 format (plaintext). Do not send pre-hashed values — DATA Reshape automatically normalizes and hashes before sending to destinations.

```
phone: "+10000000000"
```

**first\_name** string recommended

info

Customer first name

```
first_name: "Example First Name"
```

**last\_name** string recommended

info

Customer last name

```
last_name: "Example Last Name"
```

**country** string

info

Country name or ISO country code

```
country: "US"
```

**region** string recommended

info

State, province, or region name

```
region: "Example Region"
```

**city** string recommended

info

City or locality name

```
city: "Example City"
```

**street** string

info

Street address including number

```
street: "123 Sample Street"
```

**postal\_code** string

info

Postal code or ZIP code

```
postal_code: "00000"
```

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

* E-commerce Customer
* B2B Lead/Customer
* Subscription Service
* Content Platform

```
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"
}
```

```
properties: {
  company_size: "enterprise",
  industry: "fintech",
  job_title: "marketing_director",
  decision_maker: "true",
  budget_range: "50000-100000",
  lead_source: ["linkedin", "webinar"],
  qualification_status: "qualified",
  sales_stage: "proposal"
}
```

```
properties: {
  subscription_tier: "premium",
  billing_cycle: "annual",
  feature_usage: ["analytics", "reporting", "api"],
  trial_user: "false",
  renewal_date: "2025-06-30",
  support_level: "priority",
  usage_frequency: "daily"
}
```

```
properties: {
  content_preferences: ["technology", "business"],
  engagement_level: "high",
  newsletter_subscriber: "true",
  social_media_follower: "true",
  content_consumption: "premium",
  device_preference: ["mobile", "desktop"],
  timezone: "Example/Timezone"
}
```

## Examples[​](#Examples "Direct link to Examples")

* Complete
* Lead
* Minimal

```
{
  "id": "cust_abc123",
  "email": "example.customer@example.com",
  "phone": "+10000000000",
  "first_name": "Example First Name",
  "last_name": "Example Last Name",
  "country": "US",
  "region": "Example Region",
  "city": "Example City",
  "street": "123 Sample Street",
  "postal_code": "00000",
  "orders_total_number": 8,
  "orders_canceled_number": 1,
  "orders_total_value": 2156.75,
  "orders_refunded_value": 299.99,
  "predicted_value": 3500.00,
  "created_at": 1640995200000,
  "properties": {
    "customer_segment": "loyal",
    "acquisition_channel": "paid_search",
    "loyalty_tier": "gold"
  }
}
```

```
{
  "email": "example.lead@example.com",
  "phone": "+10000000001",
  "first_name": "Example Lead First Name",
  "last_name": "Example Lead Last Name",
  "country": "US",
  "region": "Example Region",
  "city": "Example City",
  "predicted_value": 15000.00,
  "created_at": 1704067200000,
  "properties": {
    "company": "Example Company Inc.",
    "job_title": "Example Job Title",
    "lead_source": "webinar"
  }
}
```

```
{
  "email": "example.customer@example.com"
}
```

Even a single email enables audience matching across most advertising platforms.

## Order History Fields[​](#Order-History-Fields "Direct link to Order History Fields")

The order history fields provide lifetime metrics for customer value analysis and segmentation:

* **orders\_total\_number** — cumulative number of orders placed
* **orders\_canceled\_number** — cumulative number of canceled orders
* **orders\_total\_value** — cumulative lifetime order value
* **orders\_refunded\_value** — cumulative refunded value
* **predicted\_value** — predicted lifetime value for your business
* **created\_at** — timestamp (milliseconds) when the user was first recorded

These values should reflect the user's complete history, not just the current event.

## Custom Properties[​](#Custom-Properties "Direct link to Custom Properties")

The `properties` object allows you to attach any custom key-value data for segmentation:

```
{
  "properties": {
    "customer_segment": "loyal",
    "acquisition_channel": "paid_search",
    "loyalty_tier": "gold",
    "preferred_categories": ["electronics", "home_garden"]
  }
}
```

Use properties that enable meaningful audience segmentation in your advertising destinations.

## Best Practices[​](#Best-Practices "Direct link to Best Practices")

* **Consistent IDs** — use stable user IDs across all events and sessions
* **Multiple contact methods** — provide both email and phone when available for better audience matching
* **Accurate order history** — keep lifetime metrics up to date for proper customer value segmentation
* **Plaintext only** — send email and phone as plaintext; DATA Reshape normalizes and hashes automatically before sending to destinations
* **Focused properties** — include only properties that enable actionable segmentation in your destinations
* **Privacy compliance** — respect user consent preferences; omit personal data when consent is not granted


---