# DATA Reshape — server-side tracking documentation > DATA Reshape collects events from a website under the shop's own domain (first-party), processes them server-side, and delivers them to advertising and analytics destinations or to an endpoint the customer owns. This documentation covers installing the tracking code, the events and data objects an integrator can send, the inbound webhook API, and the payload contract for each destination. ## general Start here: what DATA Reshape does, how first-party server-side tracking works, and how to install the global code on any website or e-commerce platform. - [DATA Reshape Documentation](/general.md): Start here: what DATA Reshape does, how first-party server-side tracking works, and how to install the global code on any website or e-commerce platform. ### 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. ## events Every event DATA Reshape can capture, when each one fires, and the payload to push from your own code. Covers e-commerce, forms, interactions, SPA navigation and consent. - [Events Overview](/events.md): Every event DATA Reshape can capture, when each one fires, and the payload to push from your own code. Covers e-commerce, forms, interactions, SPA navigation and consent. ### 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. ## objects Reference for every data object you can send: event, user, product, coupon, payment, shipping, context, cookies and consent. Field names, types and validation rules. - [Objects Overview](/objects.md): Reference for every data object you can send: event, user, product, coupon, payment, shipping, context, cookies and consent. Field names, types and validation rules. ### actor The actor object states who placed the order when it was not the customer — an agent, a back-office user, or an automation of yours. - [Actor Object](/objects/actor.md): The actor object states who placed the order when it was not the customer — an agent, a back-office user, or an automation of yours. ### 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. ## destinations Where processed events are delivered: advertising and analytics platforms, or your own HTTPS endpoint. Per-destination setup and the parameters each one receives. - [Destinations](/destinations.md): Where processed events are delivered: advertising and analytics platforms, or your own HTTPS endpoint. Per-destination setup and the parameters each one receives. ### google-ads Recommended Google Ads configuration for use with DATA Reshape server-side conversions. - [Google Ads Platform Recommended Setup](/destinations/google-ads.md): Recommended Google Ads configuration for use with DATA Reshape server-side conversions. - [Google Ads Parameters](/destinations/google-ads/parameters.md): Default and custom parameters sent by DATA Reshape to Google Ads conversions. ### 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. ### stream Receive every tracked event in your own system, server-to-server, with a payload shape that does not change between platforms. - [Your Endpoint](/destinations/stream.md): Receive every tracked event in your own system, server-to-server, with a payload shape that does not change between platforms. - [Changelog](/destinations/stream/changelog.md): Dated changes to the payload we deliver to your endpoint. - [Payload Reference](/destinations/stream/payload.md): Every container and key we send, with types, examples and the rules behind them. ### 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. ## api Send events to DATA Reshape from your backend over HTTPS. Endpoint, authentication, payload schema and validation, with a test endpoint that returns full error feedback. - [API Overview](/api.md): Send events to DATA Reshape from your backend over HTTPS. Endpoint, authentication, payload schema and validation, with a test endpoint that returns full error feedback. ### 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 --- # Full Documentation Content # API Overview **Webhooks send us events from your backend**, without browser dependencies. Ideal for e-commerce platforms, CRM systems, and any scenario where server-side tracking is required. Looking for the other direction? To receive every processed event in your own system, that is a destination, not an API: see **[Your Endpoint](/destinations/stream.md)**. ## 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** — requests go to your own tracking subdomain, the same first-party host that serves the tracking script (e.g. `https://dre2.YOUR_DOMAIN.TLD`). Any other host is rejected. ## 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**: * **Portal**: --- # 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**: * **Portal**: --- # 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") ### **Host**[​](#Host "Direct link to Host") Requests go to **your own tracking subdomain** — the same first-party host that serves the tracking script, for example `dre2.YOUR_DOMAIN.TLD`. Calls arriving on any other host are rejected, so this is not interchangeable with a shared DATA Reshape address. Your domainexample.comTracking subdomaindre2 Enter your domain and everything below is written with it. | | | | ---------- | ---------------------------------------------------------------------------- | | Production | `https://dre2.YOUR_DOMAIN.TLD/webhooks/reshape/event?id=YOUR_SCRIPT_ID` | | Testing | `https://dre2.YOUR_DOMAIN.TLD/webhooks/reshape/event/test?id=YOUR_SCRIPT_ID` | If your account was set up with a different endpoint host, use the one we gave you; it is the only other host that will be accepted. ### **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 */ ], "actor": { /* Who placed the order — only when it was NOT the customer */ }, "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" ``` **page\_title** string optional info Title of the page where the event occurred, as the browser showed it. ``` page_title:"Thank you for your order | Example Store" ``` **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 ``` **actor** object optional info Who placed the order, when it was **not** the customer — a call-centre agent, a back-office user, or a program of yours. Optional fields: `name`, `id`, `location`. Leave it out on ordinary customer orders. [**View complete Actor Object documentation**](/objects/actor.md) **name** string recommended info Which actor, as you call them: a person (`ana.maria`), a team (`callcenter`) or a process (`sync_erp`). Never the customer. Lowercase, `a-z 0-9 . _ + -`, up to 64 characters. ``` name: "ana.maria" ``` **id** string recommended info The actor's identifier in your system — an operator id, a staff account id. Never the customer's id; that belongs in `user`. Up to 128 characters. ``` id: "AG-7742" ``` **location** string optional info The physical place the actor worked from: `depozit`, `showroom`, or a branch name. Use the same spelling every time. Lowercase, `a-z 0-9 . _ + -`, up to 64 characters. ``` location: "showroom" ``` **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" ``` **timestamp** number info Optional. The moment the visitor granted consent, as a Unix timestamp in **milliseconds** (seconds are accepted and converted). DATA Reshape uses it as the visitor's first-seen time, keeping the oldest value it has. If you don't send it, the event `timestamp` is used instead. Send it on **server-to-server webhooks**. In the **browser**, DATA Reshape sets this value itself and ignores any `timestamp` sent through `reshape.push`. ``` timestamp: 1759651200000 ``` **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" }, "actor": { "name": "ana.maria", "id": "AG-7742", "location": "showroom" }, "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://dre2.YOUR_DOMAIN.TLD/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**: --- # Destinations Destinations are where DATA Reshape sends your tracking data — analytics and advertising platforms, or your own systems. 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 | | ------------------------------------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | [Your Endpoint](/destinations/stream.md) | Server-to-server | [Overview](/destinations/stream.md), [Payload Reference](/destinations/stream/payload.md), [Changelog](/destinations/stream/changelog.md) | | [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") Most destinations have 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 **Your Endpoint** is the exception: the destination is a URL you own, so there is nothing to configure on a third-party platform. It is documented as an Overview, a full Payload Reference, and a Changelog. ## 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. Please also send us the payment processor and 3D Secure domains you use, so we can exclude them on our side too. ## 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) | | `actor_type` | Who performed the event: `visitor` (a customer) or `staff` (a member of your team, detected in the browser session) | | `actor_surface` | Where the actor performed it: `website` or `app` (your own app, when declared) | | `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_` | 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_` | 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 | | `` | 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. Separate your team's activity from customers' Register `actor_type` and `actor_surface` as **Custom Dimensions** with **Event** scope (for example "Actor type" → `actor_type`, "Actor surface" → `actor_surface`). You can then filter reports, explorations and audiences to `actor_type = visitor` to exclude sessions where your team browsed or ordered on the website, or look at `staff` on its own. Both are closed lists — no other values are sent. ### 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.` | event param `event_prop_` | `event.properties.campaign_id` → `event_prop_campaign_id` | | `products[*].properties.` | item param `item_` | `properties.color` → `item_color` | | `user.properties.` | user property `` | `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. * GA4 accepts at most 25 parameters per event. `event_prop_` parameters are added **last**, only while there is room: on events that already carry many standard parameters (a complete `purchase`, for example) the extra ones are left out, so the standard parameters are never displaced. * 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. ## Test Events[​](#Test-Events "Direct link to Test Events") Use Meta's **Test events** to check what DATA Reshape sends before relying on it in reports. **Events Manager → Data sources → \[your Pixel] → Test events → Confirm your server events** Copy the **test code** shown there (it looks like `TEST12345`), fill it in below with the page you want to start from, and open the link. From that page on, for the rest of the browser session, the events sent through the Conversions API carry the test code and appear in the **Test events** tab. Close the browser (or open a private window) to go back to normal tracking. Page to openhttps\://www\.example.com/Meta test codeTEST12345 Fill in the page and the test code to get the link. ## 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.` | `event_prop_` | | `products[*].properties.` | aggregated across items into `product_` | 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) --- # Your Endpoint We send each tracked event to **your own endpoint**, server-to-server, as it is processed. You provide the URL; there is no third-party platform to configure. A real-time feed with a standardised structure: the same fields and the same shape whatever platform the shop runs on, so one integration covers all of them. Every container and key is in the [Payload Reference](/destinations/stream/payload.md). You receive the event after processing — one delivery per action, with identifiers, attribution and totals already resolved. ## When you would use it[​](#When-you-would-use-it "Direct link to When you would use it") You already have a system that should know what happens on the site — a CRM, a data warehouse, a lead scoring service, an internal dashboard. Instead of querying us, you receive each event as it happens, in a shape that stays the same regardless of which e-commerce platform the shop runs on. Typical uses: feeding a warehouse, matching leads against an internal customer base, triggering a workflow on a purchase, or keeping an order table in sync with cancellations. ## Transport[​](#Transport "Direct link to Transport") | | | | -------------- | --------------------------------------------------------------------------------------------------- | | Method | `POST` | | Content-Type | `application/json` | | Body | one event, as a JSON object — not an array, not batched | | Endpoint | yours — any HTTPS URL you provide | | Authentication | one static header — you choose the name and the secret value, we send exactly that on every request | | Timeout | 5 seconds by default, set per account | | Retries | none | There is no signature to verify Authentication is the header and nothing more. We do not sign the body, do not send a timestamp, and there is no token to exchange or refresh — so HMAC verification, replay windows or an OAuth flow would have no input to work with. Compare the header in constant time, keep the secret out of your code, and serve over HTTPS. Requests arrive with `User-Agent: DataReshapeStream/1.0`. If a WAF or bot protection sits in front of your endpoint, allow-list it — a blocked request is a lost event, not a retried one. **One event per request, and the body is a JSON object — never an array.** There is no batching: each event is its own POST, with the event at the top level of the body. A receiver that expects a list, or a wrapper around a list, will not parse it. Delivery is **best effort**: we send once and do not retry. If your endpoint is down or slow, that event is not redelivered. Two consequences worth designing for: Acknowledge fast. Return `2xx` as soon as you have the payload and process it asynchronously — the timeout covers the whole round trip, not just your first byte. Treat gaps as normal. If your system must be complete, reconcile periodically against your own source of truth rather than assuming the stream never misses anything. ## Duplicates and idempotency[​](#Duplicates-and-idempotency "Direct link to Duplicates and idempotency") The same event may arrive more than once — for example when an order is seen both by the browser and by the shop platform's webhook. Use the identifiers to deduplicate on your side: **`event.deduplication_id`** is present on every event and is the general-purpose idempotency key. **`event.unique_id`** is the identifier from the source platform — the order number, the lead id. It is present on orders and leads, empty elsewhere. Use it when you need to correlate with a record you already hold, such as applying a cancellation to the order it belongs to. ## Which events you receive[​](#Which-events-you-receive "Direct link to Which events you receive") **Only the events enabled for your account.** Delivery is configured per account, so you can take the full funnel or just the few events your system acts on — orders and cancellations for an order table, leads for a CRM. An event you never receive is not necessarily lost; it may not be enabled. Agree the list with us, rather than inferring it from what arrives. **`event.name` is a standard DATA Reshape event name** — `checkout_completed`, `product_viewed`, `lead_created`, `order_canceled` and the rest of the [Events Reference](/events.md). **It can be renamed for you.** If your system already has its own vocabulary, a name can be mapped to yours at setup, and that is what arrives instead of the standard one. Write your handler to switch on `event.name` against the list you agreed, with a default branch for anything unrecognised — the list can grow later without notice. ## What the payload guarantees[​](#What-the-payload-guarantees "Direct link to What the payload guarantees") **The key list is fixed.** The same keys arrive on every event, in the same shape, whatever platform the shop runs. A new key appears only through an announced change — see the [Changelog](/destinations/stream/changelog.md). **Declared keys are always present.** Inside `event`, `user`, `attribution`, `context`, `consent` and `values`, a key that does not apply arrives empty (`""`, `0`, `[]`, `{}`, or `null`) rather than missing. You can read them without existence checks. The exception is the order lines — `products`, `coupons`, `shipping`, `payments` — where a few keys may be absent entirely. Those are marked as such in the reference. **Personal data leaves only as fingerprints.** Email addresses, phone numbers and names are sent as SHA-256 hashes of the normalised value. Plain values never leave our system. **Consent decides what is in the payload.** A visitor grants consent per category. Anything that depends on a category they declined **may be absent, empty, or anonymised**, and what is restricted can widen over time as privacy rules and platform requirements change. Build for that from the start rather than assuming today's payload is the maximum you will ever get. The `consent` container arrives on every event and states what the visitor granted, so an empty identifier is explainable rather than mysterious: read the consent state before concluding that data is missing. Two things follow for a receiver: An empty identifier is a normal, legitimate event — not a validation error, and not a different person. Do not reject the event and do not create a second record. The same visitor can produce events with different levels of detail over time, because consent can change. Design the store to enrich a record when more arrives, rather than assuming the first version was complete. ## Building the receiver with an AI assistant[​](#Building-the-receiver-with-an-AI-assistant "Direct link to Building the receiver with an AI assistant") If you use an AI assistant while integrating, give it **[prompt-your-endpoint.txt](https://kb.datareshape.ro/prompt-your-endpoint.txt)** as context. It covers the handler shape, idempotency, ordering, matching people on hashes, and the mistakes receivers make most often — and it points the assistant at the reference below rather than letting it guess field names. Every page here also exists as Markdown: append `.md` to the path, for example [payload.md](https://kb.datareshape.ro/destinations/stream/payload.md). ## Next[​](#Next "Direct link to Next") The [Payload Reference](/destinations/stream/payload.md) documents every container and key, with types and examples. The [Changelog](/destinations/stream/changelog.md) lists dated changes, and explains which kinds of change we announce in advance and which can appear at any time. --- # Changelog Every change to the payload is listed here, newest first. The payload itself is described in the [Payload Reference](/destinations/stream/payload.md). ## 2026-09-28[​](#2026-09-28 "Direct link to 2026-09-28") **Added `actor`** — a new container, sent on every event: who placed the order (`type`: `visitor`, `staff`, `automation`, `bot`), which one (`name`, `id`), where (`surface`: `website`, `app`, `admin`, `pos`, `marketplace`, `crm`) and from which place (`location`). Additive — nothing else changes. See [actor](/destinations/stream/payload.md). ## How changes work[​](#How-changes-work "Direct link to How changes work") **Additive changes ship without notice.** A new key, or a new value in an existing list, can appear at any time. Read the payload tolerantly: ignore keys you do not know, and treat an unfamiliar value — a new channel, for instance — as data rather than as an error. **Removals and shape changes are announced.** A key you rely on will not disappear or change type without us telling you first, and without a transition period in which both the old and the new form arrive. **The exception is `properties`.** The free-form containers — `event.properties`, `user.properties`, `products[].properties` — carry whatever the shop sends. Keys there may come and go without notice, because the decision is the shop's, not ours. --- # Payload Reference The payload has the same shape for every event and every platform. Keys marked always sent arrive on every event — when they do not apply they come empty (`""`, `0`, `[]`, `{}`, `null`) rather than missing, so you can read them without existence checks. The only exception is the order lines, where a few keys may be absent entirely; those are marked in place. ## Complete Reference[​](#Complete-Reference "Direct link to Complete Reference") **event** object always sent info What happened, when, and what it was worth. **name** string info What happened. A standard DATA Reshape event name — `checkout_completed`, `product_viewed`, `lead_created`, `order_canceled` and so on. The full vocabulary is the [Events Reference](/events.md). ``` name: "checkout_completed" ``` Two things to settle before you switch on this field **You receive only the events enabled for your account, not all of them.** Which ones are delivered is configured per account. An event you never see is not necessarily missing — it may simply not be enabled. Agree the list with us rather than inferring it from traffic. **The name can be customised.** By default it is the standard name above, but it can be mapped to a name of your choosing, agreed at setup — useful when your system already has its own vocabulary. If a custom name was agreed, that is what arrives. So: switch on `event.name`, but write the switch against the list you agreed, and let an unrecognised name fall through to a default branch instead of throwing. The list can grow. **id** string info Id from the source platform — order number, lead id. `""` when there is none. ``` id: "13195238211910" ``` **unique\_id** string info Unique id of this instance, and the recommended idempotency key. Present on orders and leads, `""` elsewhere. When the platform provides no id, we send a generated one, unique per page load — it does not guarantee deduplication. Use `deduplication_id` in that case. ``` unique_id: "13195238211910" ``` **deduplication\_id** string info Present on **every** event, so it is the idempotency key for those without a `unique_id`. It is derived: on orders and leads it contains `unique_id`, so the two are not independent — do not treat them as separate keys. Elsewhere it is built from the event time and the page load, so it is stable for the same event resent, and different between two visits. ``` deduplication_id: "idx13195238211910" ``` tip Both identifiers are **opaque**: compare them, do not parse them. The format may change. **timestamp** int info When the event happened, ms Unix UTC. ``` timestamp: 1786202400000 ``` **value** number info Total value including tax, in `currency`. Includes shipping and other components as the shop declares them. `0` on events without a value. ``` value: 164.99 ``` **currency** string info ISO 4217, three letters. ``` currency: "RON" ``` **exchange\_rate** number info Rate declared by the platform when the order currency differs from the base one. `1` otherwise. ``` exchange_rate: 1 ``` **reason** string | null info Why the event happened — a cancellation or disqualification reason. Webhook routes only; `null` elsewhere. ``` reason: "out_of_stock" ``` **properties** object info The shop's own attributes, exactly as the source sends them. See [properties](#properties). ``` properties: { gift_wrap: ["yes"] } ``` **context** object always sent info The page, the device and the route the event arrived on. **url** string info The page where the event happened. ``` url: "https://shop.example/checkout" ``` **referrer\_url** string info The referring page. `""` on direct access, or when the referrer is not relevant for attribution. ``` referrer_url: "https://www.google.com/" ``` **landing\_url** string info First page of the current visit, with its campaign parameters. ``` landing_url: "https://shop.example/lp?utm_source=facebook" ``` **timestamp** int info Page load time, ms Unix UTC. Shared by every event from the same load, unlike `event.timestamp`. ``` timestamp: 1786202390000 ``` **last\_ad\_source** string info The most recent paid source. `""` when there is none. ``` last_ad_source: "facebook" ``` **integration** string info The route the data arrived on: `browser`, `webhook `, or both joined by `|` when the same event was seen on both and merged. ``` integration: "browser|webhook merchantpro" ``` **data\_source** string info Business origin: `website`, `admin`, `phone`, `app`, or a label of the shop's own. ``` data_source: "website" ``` **script\_id** string info Identifier of the shop configuration, 8 characters. ``` script_id: "YOURSCR1" ``` **page\_type** string info Page type: `home`, `product`, `category`, `checkout`. ``` page_type: "checkout" ``` **page\_title** string info Title of the page: `context.page_title` when sent, otherwise `document.title` read when the event was processed. Empty when unknown (e.g. webhook orders without a title). ``` page_title: "Checkout | Example Shop" ``` **has\_adblocker** int info `1` if an ad blocker was detected, `0` otherwise. ``` has_adblocker: 0 ``` **nav\_type** string info How the visitor got to this page. | value | meaning | | -------------- | -------------------------------------------------------- | | `navigate` | a normal navigation — a link, or the address typed | | `reload` | the page was reloaded | | `back_forward` | the browser's back or forward button | | `prerender` | the page was preloaded by the browser before being shown | | `other` | a navigation type the browser reports but we do not name | | `unavailable` | the browser did not report one | | `error` | the browser API failed when we asked | The first four are the [Performance API navigation types](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceNavigationTiming/type), reported as the browser names them. ``` nav_type: "navigate" ``` **screen** string info Screen resolution, `"width x height"`. ``` screen: "360x780" ``` **user\_agent** string info The raw browser User-Agent. ``` user_agent: "Mozilla/5.0 (Linux; Android 14) Chrome/151.0.0.0 Mobile" ``` **device\_type** string info `mobile`, `desktop`, `tablet`, `unknown`. ``` device_type: "mobile" ``` **browser\_name** string info Browser parsed from the User-Agent. `other` when it cannot be determined. ``` browser_name: "chrome" ``` **browser\_version** string info Browser version. `""` when it cannot be determined. ``` browser_version: "151.0.0.0" ``` **operating\_system** string info Operating system parsed from the User-Agent. ``` operating_system: "android" ``` **operating\_system\_version** string info Operating system version. ``` operating_system_version: "14" ``` **browser\_app** string info The app the page opened in, when that is certain — `facebook`, `instagram`. `no_app` otherwise. ``` browser_app: "no_app" ``` **browser\_language** string info Browser language. ``` browser_language: "ro-RO" ``` **visitor\_ip\_address** string info The visitor IP address. ``` visitor_ip_address: "86.122.24.187" ``` **visitor\_ip\_country** string info Country derived from the IP, ISO 3166-1 alpha-2. Describes **where the request came from**, which can differ from the address on the order in `user.country`. ``` visitor_ip_country: "RO" ``` **visitor\_ip\_city** string info City derived from the IP. ``` visitor_ip_city: "Brașov" ``` **visitor\_ip\_region** string info Region derived from the IP. Code or name, depending on the source. ``` visitor_ip_region: "BV" ``` **visitor\_ip\_postal\_code** string info Postal code derived from the IP. An approximation of the area, **not** the customer address. ``` visitor_ip_postal_code: "500001" ``` **products** array info Order lines, in a unified shape — the same keys whatever platform the shop runs. Present on events that have them. **products\[0]** object **id** string info Id of the variant sold. ``` id: "SKU-1024-BLACK" ``` **parent\_id** string info Id of the parent product. `= id` when there are no variants. ``` parent_id: "1024" ``` **name** string info Variant name. ``` name: "Urban backpack 20L black" ``` **parent\_name** string info Parent product name. `= name` when missing. ``` parent_name: "Urban backpack 20L" ``` **sku** string info Stock code. ``` sku: "SKU-1024-BLACK" ``` **parent\_sku** string info Parent stock code. `= sku` when missing. ``` parent_sku: "SKU-1024" ``` **ean** string info Standard product code. `""` when missing. ``` ean: "5901234123457" ``` **gtin** string info Standard product code. `""` when missing. ``` gtin: "5901234123457" ``` **mpn** string info Manufacturer part number. `""` when missing. ``` mpn: "NM-1024-BK" ``` **brand** string info Brand. ``` brand: "Nomad" ``` **type** string info Product type, as the shop declares it. ``` type: "simple" ``` **category** string info Main category. ``` category: "backpacks" ``` **categories** array info Every category, as `{name}` objects. ``` categories: [{ name: "backpacks" }, { name: "accessories" }] ``` **quantity** int info Units on the line. Minimum `1`. ``` quantity: 2 ``` **price** number info **Final** unit price, with tax, after the product discount. ``` price: 82.5 ``` tip `price × quantity` is the line value, already net. Discounts in `coupons` below are **already subtracted from `price`** — do not subtract them again. **price\_without\_tax** number info The same final unit price, excluding tax. ``` price_without_tax: 69.33 ``` **price\_base** number info **List** unit price, with tax, before the product discount. `= price` when there is no discount; the difference `price_base − price` is the discount per unit. ``` price_base: 87.5 ``` **price\_base\_without\_tax** number info List unit price, excluding tax. ``` price_base_without_tax: 73.53 ``` **coupons** array info Discounts applied **to this line**. `value` is the line total, not per unit. **Key absent** when there are none. These are distinct from the order-level `coupons` container: those apply across the whole order, are not reflected in product prices, and *are* subtracted from the aggregate value. ``` coupons: [{ name: "PROMO5", value: 10, type: "fixed", tax_included: true, tax_percent: 19 }] ``` Worked example List price `87.5`, a `10` coupon across the whole line (`5` per unit at `quantity: 2`), final price `82.5`. Line value = `82.5 × 2 = 165` — exactly what `values.products_value_with_tax` shows. **currency** string info Line currency. ``` currency: "RON" ``` **exchange\_rate** number info Line exchange rate. `1` by default. ``` exchange_rate: 1 ``` **tax\_percent** number info Tax rate applied to the line. ``` tax_percent: 19 ``` **tax\_included** bool info Whether the prices above include tax. ``` tax_included: true ``` **url** string info Address of the variant. **Key absent** when the address is invalid. ``` url: "https://shop.example/backpack-black" ``` **parent\_url** string info Address of the parent product. **Key absent** when the address is invalid. ``` parent_url: "https://shop.example/backpack" ``` **image** string info Main image. **Key absent** when no valid address exists. ``` image: "https://shop.example/img/1024.jpg" ``` **images** array info Every image. **Key absent** when no valid address exists. ``` images: ["https://shop.example/img/1024.jpg"] ``` **stock\_status** string info Stock state, as the shop declares it. ``` stock_status: "1" ``` **stock\_exists** bool info Availability, derived from `stock_status`. ``` stock_exists: true ``` **stock\_location** string info Warehouse, when the shop declares it. ``` stock_location: "main-warehouse" ``` **created\_at** int info When the product was added to the catalogue, ms Unix UTC. `0` when missing. ``` created_at: 1690000000000 ``` **properties** object info The shop's own attributes for this line. **Key absent** when empty. See [properties](#properties). ``` properties: { variant: ["black / M"] } ``` caution Keys marked **key absent** really are missing from the object in the situations described — unlike `event`, `user`, `attribution`, `context`, `consent` and `values`, where every key always arrives. **shipping** array info Shipping methods on the order. Present only on events that have them. **shipping\[0]** object **id** string info Shipping method id. ``` id: "courier" ``` **name** string info Shipping method name. ``` name: "Express courier" ``` **type** string info Method type, as the shop declares it. ``` type: "courier" ``` **currency** string info Currency of the shipping cost. ``` currency: "RON" ``` **value** number info Shipping cost, including tax. ``` value: 19.99 ``` **value\_without\_tax** number info Shipping cost, excluding tax. ``` value_without_tax: 16.8 ``` **exchange\_rate** number info Exchange rate for this line. `1` by default. ``` exchange_rate: 1 ``` **payments** array info Payment methods on the order. Present only on events that have them. **payments\[0]** object **id** string info Payment method id. ``` id: "card" ``` **name** string info Payment method name. ``` name: "Card" ``` **type** string info Method type: `card`, `cash`, `transfer`, as the shop declares it. ``` type: "card" ``` **value** number info Amount paid with this method. ``` value: 164.99 ``` **coupons** array info Order-level discounts. Product-level ones are in `products[].coupons`. Present only on events that have them. **coupons\[0]** object **id** string info Coupon id or code. ``` id: "SUMMER10" ``` **name** string info Coupon name, as shown to the customer. ``` name: "SUMMER10" ``` **type** string info `percent` or `fixed`, as the shop declares it. ``` type: "percent" ``` **value** number info Discount value, including tax. ``` value: 20 ``` **value\_without\_tax** number info Discount value, excluding tax. ``` value_without_tax: 16.81 ``` **actor** object always sent info Who placed the order: the customer, someone from the shop's team, or a program. `user` describes the customer; `actor` describes whoever acted. **type** string info What kind of actor. Always one of: * `visitor` — the customer, wherever they bought: the website, the shop's app, a marketplace * `staff` — a person from the shop's team: call centre, back office, physical store * `automation` — a program of the shop: subscription renewals, imports, ERP sync * `bot` — an automated agent from outside the shop (reserved) ``` type: "staff" ``` **name** string info Which actor, as the shop calls them: a person (`ana.maria`), a team (`callcenter`) or a process (`subscription`). Empty when not known. Always empty for `visitor` — the customer's identity is in `user`. ``` name: "callcenter" ``` **id** string info The actor's identifier in the shop's system — a staff account id, an operator id. Empty when not known. ``` id: "87490429102" ``` **surface** string info Where the actor placed the order. One of: * `website` — the shop's online store * `app` — the shop's own mobile app * `admin` — the platform's back office * `pos` — a physical point of sale * `marketplace` — someone else's storefront (eMAG, TikTok Shop, Shop app) * `crm` — an external system the team works in * `""` — not known, and always empty for `automation` ``` surface: "admin" ``` **location** string info The physical place the actor worked from, in the shop's own words: `depozit`, `showroom`, a branch name. Empty when not known, and always empty for `visitor`. ``` location: "showroom" ``` **user** object always sent info Who the visitor is, as far as we know. Personal values leave only as SHA-256 fingerprints of the normalised value — plain values never leave our system. **id** string info Customer id in the shop platform. `""` for orders without an account. ``` id: "7" ``` **emails\_sha256** array info Email fingerprints, at most 5. Normalisation before hashing: lowercase. **The order is guaranteed** — most recently discovered first. If you want a visitor's current address, it is the first in the list. ``` emails_sha256: ["34d338…206f", "9b7f21…41ac"] ``` tip All four fingerprint keys are **always arrays**, even where only one value can exist today. The type never changes, so you can iterate without checks. An empty list means we do not have the value. **phones\_sha256** array info Phone fingerprints, same rules and same ordering. Normalisation before hashing: E.164 format. ``` phones_sha256: ["9f2a41…7b3c"] ``` **first\_name\_sha256** array info Fingerprint of the first name. Normalisation: lowercase, trimmed, punctuation and inner spaces removed, diacritics and digits kept — `Ștefan-Ion` becomes `ștefanion`. ``` first_name_sha256: ["aa34d338…9e206"] ``` **last\_name\_sha256** array info Fingerprint of the last name, same normalisation as the first name. ``` last_name_sha256: ["cc91f2a4…e4d3c"] ``` **country** string info Country from the order address, ISO 3166-1 alpha-2, lowercase. May differ from `context.visitor_ip_country`, which is derived from the IP. ``` country: "ro" ``` **region** string info County or region from the address. Free text, no fixed vocabulary. ``` region: "BV" ``` **city** string info City from the address. Free text. ``` city: "Brașov" ``` **created\_at** int | null info When the account was created, ms Unix UTC. `null` for orders without an account. ``` created_at: 1690000000000 ``` **first\_seen** int info Earliest known interaction with the shop, ms Unix UTC. It may **decrease** over time for the same visitor, as we learn about earlier interactions. When aggregating, take the minimum. ``` first_seen: 1785164079095 ``` **properties** object info The shop's own attributes about this customer. See [properties](#properties). ``` properties: { account_status: ["active"] } ``` **cookies** object info A `{ name: value }` object with the cookies available from the visitor's browser on the shop domain. Some cookies are not available for security reasons — they are neither collected nor altered. Cookies can also be excluded on request. ``` cookies: { _fbp: "fb.1.1785929520000.916422363983203244", _ga: "GA1.1.8296324256672419.1785542401" } ``` **consent** object always sent info What the visitor agreed to. When they have not chosen, the values reflect the shop's default setting. **analytics** int info `1` granted, `0` not granted. ``` analytics: 1 ``` **marketing** int info `1` granted, `0` not granted. ``` marketing: 0 ``` **id** string info Id of the consent decision, when the consent platform provides one. `""` otherwise. ``` id: "a1b2c3d4-…" ``` **attribution** object always sent info Where the visitor came from. The two lists are different readings of the same data: `channels` covers every channel, `paid_sources` only the paid platforms. Every entry carries the days we saw it, so you can apply whatever window your own model uses. **channels** array info The channels the visitor arrived through, **in order of first touch**. Each channel appears once, however many times it was touched, with the span over which it was seen. Order is information, not decoration: two visits with the same channels in a different order arrive as different lists. To compare *which* channels were touched, sort both lists first; to compare the *journey*, compare them as they are. ``` channels: [ { channel: "paid", first_day: "2026-08-23", last_day: "2026-09-09", days_seen: 4 }, { channel: "newsletter", first_day: "2026-09-03", last_day: "2026-09-03", days_seen: 1 } ] ``` | field | meaning | | ----------- | ---------------------------------------------------------------------------------------- | | `channel` | one of the values below | | `first_day` | the first day we have a record of this channel bringing the visitor, `YYYY-MM-DD` in UTC | | `last_day` | the last day it brought them; equal to `first_day` for a single touch | | `days_seen` | how many **distinct days** it brought them, `first_day` and `last_day` included | Days, not moments `first_day` and `last_day` are **days**, deliberately. They are exact as days and cannot be narrowed to an hour, so do not build "hours since last touch" logic on them. `days_seen` counts days the same way: two visits from the same channel on the same day count once. It measures how persistent a source was, not traffic volume, and it is never a click count. The day is the **UTC** day, like every timestamp we send. For a shop east of UTC this means a late-night visit can be dated one day earlier than the shop's own reports show it — a visit at 01:00 in Bucharest is `2026-09-11` here and the 12th there. Convert to your timezone if you compare the two. Nothing is cut by a window Every channel we still have a record of is listed, with its own days, so you apply whatever window your model uses. Cutting the lists made the payload contradict itself: a channel and the platform that started it would report different histories, or a returning visitor would arrive with a first touch dated to their return. With the days on every entry there is nothing to cut for. `first_day` is the first day we have, not the first day it happened We do not keep the journey forever. For a visitor who has been coming back for a long time, `first_day` is where our record begins, not where the relationship did. | value | what it covers | | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `paid` | advertising bought on a platform: Google, Meta, TikTok, Bing, X, Snapchat, Pinterest, LinkedIn, OpenAI, Biano, Favi | | `retargeting` | remarketing platforms — Criteo, RTB House | | `affiliate` | affiliate networks, paid on commission — 2Performant, Profitshare, Awin, Admitad, TradeDoubler, CJ, Impact, Rakuten, Webgains, Flip | | `ai` | AI assistants, organic — ChatGPT, Perplexity, Gemini, Claude, Copilot, DeepSeek, Grok, You.com, Poe, Mistral, Meta AI, Phind. An ad inside ChatGPT is `paid`, not `ai` | | `newsletter` | your own email | | `organic` | a search engine, with no ad click on it — **Google, Bing, Yahoo, Yandex, DuckDuckGo, Baidu, Ecosia, Startpage, Qwant, Seznam** | | `social` | a social network, with no advertising — Facebook, Instagram, TikTok, X, Snapchat, Pinterest, LinkedIn, Reddit, YouTube | | `others` | another site sent the visitor — any domain not named above | `others` is ordinary referral traffic, not an error It is where a plain domain lands: a blog, a marketplace, a price comparison site, a partner's page. There is no separate `referral` value — a domain we do not map specially is simply `others`. That also covers a search engine or a social network outside the lists above, because all we can tell is that some site sent the visitor. If a market you sell in leans on an engine or a network we are missing, tell us and we add it — until then that traffic is real, and it sits in `others`. tip `paid` means **advertising**, not "everything that cost money": `retargeting` and `affiliate` are paid too, but appear separately because they are budgeted separately. For the paid total, take the union of the three. info **An empty list** — no source was identified: the visitor arrived directly, typed address or bookmark, or the signal was lost. There is no `direct` value; the absence is the answer. info **Which platform, not just which channel.** Named platforms arrive only for paid traffic, in `paid_sources`. For `organic`, `social`, `others` and `newsletter` you get the channel alone — not the search engine, the social network or the referring site. That is deliberate: platform names matter for budget attribution, which is a paid concern. Everywhere else the channel is the useful unit, and sending the full source taxonomy would tie your integration to our internal classification. If you need the specific source, tell us — it is a configuration question, not a limitation of the format. caution The list may grow. Treat an unknown value as a new channel, not as an error. **paid\_sources** array info Platform names rather than channel names, ordered by first touch like `channels`. `[]` means no paid source is on record for this visitor. ``` paid_sources: [ { source: "google", type: "ads", first_day: "2026-08-23", last_day: "2026-09-09", days_seen: 4 }, { source: "2performant", type: "affiliate", first_day: "2026-09-07", last_day: "2026-09-07", days_seen: 1 }, { source: "criteo", type: "retargeting", first_day: "2026-09-10", last_day: "2026-09-10", days_seen: 1 } ] ``` | field | meaning | | ----------- | ----------------------------------------------------------------------------------------- | | `source` | the platform name | | `type` | `ads`, `affiliate`, `retargeting`, or `other` | | `first_day` | the first day we have a record of this platform bringing the visitor, `YYYY-MM-DD` in UTC | | `last_day` | the last day it brought them | | `days_seen` | how many **distinct days** it brought them, `first_day` and `last_day` included | `days_seen` does not add up across the two lists A channel's `days_seen` is its own distinct days, not the sum of its platforms'. Google and Meta both bringing the visitor on the same day is one day for the channel `paid` and one day for each of them — so the platforms can add up to more than the channel. That is what "distinct days" means, not a discrepancy. Like `channels`, this list is not cut — every paid platform we still have a record of is here, with its own days. Read `type` before you sum anything This list is everything acquired for money, which is not the same as everything you bought as advertising. An affiliate network is billed on a sale, a retargeting DSP from a separate budget, and search ads per click — grouping them under one total answers no real question. `type` is what lets you separate them. **values** object always sent info Order totals, in `event.currency`, at most four decimals. The event value itself is in `event.value`. **products\_count** int info Distinct product lines. ``` products_count: 1 ``` **products\_total\_quantity** int info Units in total, across every line. ``` products_total_quantity: 2 ``` **products\_value\_with\_tax** number info Sum of the lines — unit price × quantity — including tax. ``` products_value_with_tax: 165 ``` **products\_value\_without\_tax** number info The same sum, excluding tax. ``` products_value_without_tax: 138.66 ``` **shipping\_count** int info Shipping methods on the order. ``` shipping_count: 1 ``` **shipping\_value\_with\_tax** number info Shipping cost, including tax. ``` shipping_value_with_tax: 19.99 ``` **shipping\_value\_without\_tax** number info Shipping cost, excluding tax. ``` shipping_value_without_tax: 16.8 ``` **coupons\_count** int info Order-level discounts applied. Product-level discounts are already reflected in product prices and are not counted here. ``` coupons_count: 1 ``` **coupons\_value\_with\_tax** number info Value of the order-level discounts, including tax. ``` coupons_value_with_tax: 20 ``` **coupons\_value\_without\_tax** number info Value of the order-level discounts, excluding tax. ``` coupons_value_without_tax: 16.81 ``` **payments\_count** int info Payment methods used. ``` payments_count: 1 ``` **payments\_total\_value** number info Sum of the payments. ``` payments_total_value: 164.99 ``` tip The net is `products_value_without_tax + shipping_value_without_tax - coupons_value_without_tax`. **queries** array info Marketing parameters from the addresses visited: `utm_campaign`, `utm_source`, `utm_medium`, `utm_content`, `utm_term`, and the click identifiers of the active advertising platforms — `fbclid`, `gclid`, `ttclid` and so on, once configured for the shop. One entry **per parameter**, with the last value seen — not a history of every value. The list includes parameters from earlier visits, not only the current one. How far back this list goes Unlike the attribution lists, this one **is** cut — a click id kept forever would grow without bound. The window is **at least 30 days**, and wider when the shop's attribution window is wider than that. It is measured against `event.timestamp`, so a webhook that arrives late carries the same list it would have carried at the time of the event. You do not need the exact number to use the data: every entry carries its own `added_at`, so what is in the list tells you what was in the window. **queries\[0]** object **name** string info Parameter name. ``` name: "utm_source" ``` **value** string info Parameter value. ``` value: "facebook" ``` **added\_at** int info When we last saw this value, ms Unix UTC. ``` added_at: 1785929520000 ``` ## properties[​](#properties "Direct link to properties") `event.properties`, `user.properties` and `products[].properties` are **free-form**: the content is exactly what the source — the shop or its platform — sends. We do not add keys, translate them, filter them by meaning, or interpret them. The only thing we do is bring them to a predictable shape, so they do not differ from platform to platform: | in | out | | ------------------------- | ------------------------------------------------------- | | `"Color Variant"` | `"color_variant"` — keys become `snake_case` | | `"black"` | `["black"]` — values are always arrays | | `42`, `true` | `["42"]`, `["true"]` — numbers and booleans become text | | `["red", "red", "blue"]` | `["red", "blue"]` — duplicates removed | | `""`, `null`, `undefined` | *ignored* | | `{ "nested": "obj" }` | *ignored* — if it is the only value, the key disappears | So the keys and values are the source's; the shape is ours. A key reaches you only if it has at least one value left after the cleanup — you will never receive an empty array. caution There is no fixed key list here and there cannot be: every shop sends something different. Nothing in this container is guaranteed — a key may appear or disappear without notice, because the decision is the shop's, not ours. Read it as data, not as something you can build a schema on. ## Time windows[​](#Time-windows "Direct link to Time windows") Three containers carry history; everything else describes the current event. | container | how far back | | -------------------------- | ----------------------------------------------------------- | | `attribution.channels` | everything we still have, each entry dated | | `attribution.paid_sources` | the same, it is the same data read differently | | `queries` | at least 30 days, wider if the shop's attribution window is | The two attribution lists are not cut: they carry their days per entry, so you apply the window your model needs. `queries` is cut, because a click id kept without a window would grow without bound, and it is measured against `event.timestamp`, not delivery time — a webhook that arrives late produces the same payload it would have produced at the time of the event. One limit applies to all three: we do not keep a visitor's history forever, so the oldest day you can see is bounded by how long we hold it, not by any window. ## Full example[​](#Full-example "Direct link to Full example") A single `checkout_completed`, with every container populated. ``` { "event": { "name": "checkout_completed", "id": "13195238211910", "unique_id": "13195238211910", "deduplication_id": "idx13195238211910", "timestamp": 1786202400000, "value": 164.99, "currency": "RON", "exchange_rate": 1, "reason": null, "properties": {} }, "context": { "url": "https://shop.example/checkout", "referrer_url": "", "landing_url": "https://shop.example/lp?utm_source=facebook", "timestamp": 1786202390000, "last_ad_source": "facebook", "integration": "browser|webhook merchantpro", "data_source": "website", "script_id": "YOURSCR1", "page_type": "checkout", "page_title": "Checkout | Example Shop", "has_adblocker": 0, "nav_type": "navigate", "screen": "360x780", "user_agent": "Mozilla/5.0 (Linux; Android 14) Chrome/151.0.0.0 Mobile", "device_type": "mobile", "browser_name": "chrome", "browser_version": "151.0.0.0", "operating_system": "android", "operating_system_version": "14", "browser_app": "no_app", "browser_language": "ro-RO", "visitor_ip_address": "86.122.24.187", "visitor_ip_country": "RO", "visitor_ip_city": "Brașov", "visitor_ip_region": "BV", "visitor_ip_postal_code": "500001" }, "products": [ { "id": "SKU-1024-BLACK", "quantity": 2, "price": 82.5, "price_base": 87.5 } ], "shipping": [ { "id": "courier", "value": 19.99 } ], "payments": [ { "id": "card", "type": "card", "value": 164.99 } ], "coupons": [ { "id": "SUMMER10", "type": "percent", "value": 20 } ], "actor": { "type": "visitor", "name": "", "id": "", "surface": "website", "location": "" }, "user": { "id": "7", "first_name_sha256": [ "aa34d338…9e206" ], "last_name_sha256": [ "cc91f2a4…e4d3c" ], "emails_sha256": [ "34d338…206f" ], "phones_sha256": [ "9f2a41…7b3c" ], "country": "ro", "region": "BV", "city": "Brașov", "created_at": 1690000000000, "first_seen": 1785164079095, "properties": { "account_status": [ "active" ] } }, "cookies": { "_fbp": "fb.1.1785929520000.916422363983203244" }, "consent": { "analytics": 1, "marketing": 0, "id": "" }, "attribution": { "channels": [ { "channel": "paid", "first_day": "2026-08-23", "last_day": "2026-09-11", "days_seen": 6 }, { "channel": "newsletter", "first_day": "2026-09-03", "last_day": "2026-09-03", "days_seen": 1 }, { "channel": "organic", "first_day": "2026-09-06", "last_day": "2026-09-08", "days_seen": 2 }, { "channel": "retargeting", "first_day": "2026-09-10", "last_day": "2026-09-10", "days_seen": 1 }, { "channel": "affiliate", "first_day": "2026-09-11", "last_day": "2026-09-11", "days_seen": 1 } ], "paid_sources": [ { "source": "facebook", "type": "ads", "first_day": "2026-08-23", "last_day": "2026-09-09", "days_seen": 4 }, { "source": "google", "type": "ads", "first_day": "2026-08-30", "last_day": "2026-09-11", "days_seen": 3 }, { "source": "criteo", "type": "retargeting", "first_day": "2026-09-10", "last_day": "2026-09-10", "days_seen": 1 }, { "source": "2performant", "type": "affiliate", "first_day": "2026-09-11", "last_day": "2026-09-11", "days_seen": 1 } ] }, "values": { "products_count": 1, "products_total_quantity": 2, "products_value_with_tax": 165, "products_value_without_tax": 138.66, "shipping_count": 1, "shipping_value_with_tax": 19.99, "shipping_value_without_tax": 16.8, "coupons_count": 1, "coupons_value_with_tax": 20, "coupons_value_without_tax": 16.81, "payments_count": 1, "payments_total_value": 164.99 }, "queries": [ { "name": "utm_source", "value": "facebook", "added_at": 1785929520000 } ] } ``` --- # 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. ## Test Events[​](#Test-Events "Direct link to Test Events") Use TikTok's **Test events** to check what DATA Reshape sends before relying on it in reports. **Events Manager → \[your Pixel] → Test events → Server** (Events API) Copy the **test event code** shown there (it looks like `TEST12345`), fill it in below with the page you want to start from, and open the link. From that page on, for the rest of the browser session, the events sent through the Events API carry the test code and appear in **Test events**. Close the browser (or open a private window) to go back to normal tracking. Page to openhttps\://www\.example.com/TikTok test event codeTEST12345 Fill in the page and the test code to get the link. ## 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_` (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 held **in the browser**, complete, and nothing leaves it 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. The complete event is held in the browser, for the current page only. * **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 modes 1 and 2, where events are held only for the current page, here they **survive 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" ``` **page\_title** string optional info Title of the current page. Collected automatically from `document.title` when missing. Send it on SPA route changes when the event is pushed before your framework updates `document.title`, otherwise the event carries the title of the previous route. ``` page_title: "Sony RM-IP500 Remote Control | Example Store" ``` **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" ``` **page\_title** string optional info Title of the current page. Collected automatically from `document.title` when missing. Send it on SPA route changes when the event is pushed before your framework updates `document.title`, otherwise the event carries the title of the previous route. ``` page_title: "Sony RM-IP500 Remote Control | Example Store" ``` **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" ``` **page\_title** string optional info Title of the current page. Collected automatically from `document.title` when missing. Send it on SPA route changes when the event is pushed before your framework updates `document.title`, otherwise the event carries the title of the previous route. ``` page_title: "Sony RM-IP500 Remote Control | Example Store" ``` **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" ``` **timestamp** number info Optional. The moment the visitor granted consent, as a Unix timestamp in **milliseconds** (seconds are accepted and converted). DATA Reshape uses it as the visitor's first-seen time, keeping the oldest value it has. If you don't send it, the event `timestamp` is used instead. Send it on **server-to-server webhooks**. In the **browser**, DATA Reshape sets this value itself and ignores any `timestamp` sent through `reshape.push`. ``` timestamp: 1759651200000 ``` ## 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" ``` **page\_title** string optional info Title of the current page. Collected automatically from `document.title` when missing. Send it on SPA route changes when the event is pushed before your framework updates `document.title`, otherwise the event carries the title of the previous route. ``` page_title: "Sony RM-IP500 Remote Control | Example Store" ``` **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" ``` **page\_title** string optional info Title of the current page. Collected automatically from `document.title` when missing. Send it on SPA route changes when the event is pushed before your framework updates `document.title`, otherwise the event carries the title of the previous route. ``` page_title: "Sony RM-IP500 Remote Control | Example Store" ``` **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" ``` **timestamp** number info Optional. The moment the visitor granted consent, as a Unix timestamp in **milliseconds** (seconds are accepted and converted). DATA Reshape uses it as the visitor's first-seen time, keeping the oldest value it has. If you don't send it, the event `timestamp` is used instead. Send it on **server-to-server webhooks**. In the **browser**, DATA Reshape sets this value itself and ignores any `timestamp` sent through `reshape.push`. ``` timestamp: 1759651200000 ``` ## 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" ``` **page\_title** string optional info Title of the current page. Collected automatically from `document.title` when missing. Send it on SPA route changes when the event is pushed before your framework updates `document.title`, otherwise the event carries the title of the previous route. ``` page_title: "Sony RM-IP500 Remote Control | Example Store" ``` **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" ``` **page\_title** string optional info Title of the current page. Collected automatically from `document.title` when missing. Send it on SPA route changes when the event is pushed before your framework updates `document.title`, otherwise the event carries the title of the previous route. ``` page_title: "Sony RM-IP500 Remote Control | Example Store" ``` **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" ``` **page\_title** string optional info Title of the current page. Collected automatically from `document.title` when missing. Send it on SPA route changes when the event is pushed before your framework updates `document.title`, otherwise the event carries the title of the previous route. ``` page_title: "Sony RM-IP500 Remote Control | Example Store" ``` **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" ``` **page\_title** string optional info Title of the current page. Collected automatically from `document.title` when missing. Send it on SPA route changes when the event is pushed before your framework updates `document.title`, otherwise the event carries the title of the previous route. ``` page_title: "Sony RM-IP500 Remote Control | Example Store" ``` **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" ``` **page\_title** string optional info Title of the current page. Collected automatically from `document.title` when missing. Send it on SPA route changes when the event is pushed before your framework updates `document.title`, otherwise the event carries the title of the previous route. ``` page_title: "Sony RM-IP500 Remote Control | Example Store" ``` **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" ``` **page\_title** string optional info Title of the current page. Collected automatically from `document.title` when missing. Send it on SPA route changes when the event is pushed before your framework updates `document.title`, otherwise the event carries the title of the previous route. ``` page_title: "Sony RM-IP500 Remote Control | Example Store" ``` **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" ``` **page\_title** string optional info Title of the current page. Collected automatically from `document.title` when missing. Send it on SPA route changes when the event is pushed before your framework updates `document.title`, otherwise the event carries the title of the previous route. ``` page_title: "Sony RM-IP500 Remote Control | Example Store" ``` **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" ``` **page\_title** string optional info Title of the current page. Collected automatically from `document.title` when missing. Send it on SPA route changes when the event is pushed before your framework updates `document.title`, otherwise the event carries the title of the previous route. ``` page_title: "Sony RM-IP500 Remote Control | Example Store" ``` **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" ``` **page\_title** string optional info Title of the current page. Collected automatically from `document.title` when missing. Send it on SPA route changes when the event is pushed before your framework updates `document.title`, otherwise the event carries the title of the previous route. ``` page_title: "Sony RM-IP500 Remote Control | Example Store" ``` **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" ``` **page\_title** string optional info Title of the current page. Collected automatically from `document.title` when missing. Send it on SPA route changes when the event is pushed before your framework updates `document.title`, otherwise the event carries the title of the previous route. ``` page_title: "Sony RM-IP500 Remote Control | Example Store" ``` **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" ``` **page\_title** string optional info Title of the current page. Collected automatically from `document.title` when missing. Send it on SPA route changes when the event is pushed before your framework updates `document.title`, otherwise the event carries the title of the previous route. ``` page_title: "Sony RM-IP500 Remote Control | Example Store" ``` **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" ``` **page\_title** string optional info Title of the current page. Collected automatically from `document.title` when missing. Send it on SPA route changes when the event is pushed before your framework updates `document.title`, otherwise the event carries the title of the previous route. ``` page_title: "Sony RM-IP500 Remote Control | Example Store" ``` **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" ``` **page\_title** string optional info Title of the current page. Collected automatically from `document.title` when missing. Send it on SPA route changes when the event is pushed before your framework updates `document.title`, otherwise the event carries the title of the previous route. ``` page_title: "Sony RM-IP500 Remote Control | Example Store" ``` **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" ``` **page\_title** string optional info Title of the current page. Collected automatically from `document.title` when missing. Send it on SPA route changes when the event is pushed before your framework updates `document.title`, otherwise the event carries the title of the previous route. ``` page_title: "Sony RM-IP500 Remote Control | Example Store" ``` **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" ``` **page\_title** string optional info Title of the current page. Collected automatically from `document.title` when missing. Send it on SPA route changes when the event is pushed before your framework updates `document.title`, otherwise the event carries the title of the previous route. ``` page_title: "Sony RM-IP500 Remote Control | Example Store" ``` **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" ``` **page\_title** string optional info Title of the current page. Collected automatically from `document.title` when missing. Send it on SPA route changes when the event is pushed before your framework updates `document.title`, otherwise the event carries the title of the previous route. ``` page_title: "Sony RM-IP500 Remote Control | Example Store" ``` **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" ``` **page\_title** string optional info Title of the current page. Collected automatically from `document.title` when missing. Send it on SPA route changes when the event is pushed before your framework updates `document.title`, otherwise the event carries the title of the previous route. ``` page_title: "Sony RM-IP500 Remote Control | Example Store" ``` **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" ``` **page\_title** string optional info Title of the current page. Collected automatically from `document.title` when missing. Send it on SPA route changes when the event is pushed before your framework updates `document.title`, otherwise the event carries the title of the previous route. ``` page_title: "Sony RM-IP500 Remote Control | Example Store" ``` **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` from `context.url` and `page_title` from `context.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" ``` **page\_title** string optional info Title of the current page. Collected automatically from `document.title` when missing. Send it on SPA route changes when the event is pushed before your framework updates `document.title`, otherwise the event carries the title of the previous route. ``` page_title: "Sony RM-IP500 Remote Control | Example Store" ``` **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: **** --- # 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 ## Install[​](#Install "Direct link to Install") Fill in your domain and tick what runs on your account — the snippet is built as you type. Your domainexample.comRoot domain, without www\.Tracking subdomain dre2. YOUR\_DOMAIN.TLD Agreed with our team, together with the SSL certificate. Enter your domain and everything below is written with it. DNS records for dre2.YOUR\_DOMAIN.TLD | Type | Name | Target | TTL | | ----- | ---------------------- | ---------------------------------------------------------- | ---- | | CNAME | `dre2` | `app.datareshape.net` | Auto | | CNAME | `_acme-challenge.dre2` | `dre2.YOUR_DOMAIN.TLD.5c7e7c9aba529dca.dcv.cloudflare.com` | Auto | The first record routes the tracking requests. The second one lets the SSL certificate issue and renew on its own. Some providers want the full name instead of the short one — `dre2.YOUR_DOMAIN.TLD` rather than `dre2`; try the short form first. Full walkthrough, per provider, in [Custom Domain Setup](/general/subdomain.md). Content Security Policy Most sites do not send one. If you are not sure, leave this alone — nothing below changes. \[ ]My site sends a `Content-Security-Policy` header or meta tag Replace `YOUR_SCRIPT_ID` with the Script ID provided by the DATA Reshape team, then add this to the `` of every page. Global code ``` ``` Add the result to the `` of **every page**, as early as possible. ### Example[​](#Example "Direct link to Example") The snippet goes in ``, before your own scripts: ``` Your Website ``` ## 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. ``` ``` ## Content Security Policy (CSP)[​](#Content-Security-Policy-CSP "Direct link to Content Security Policy (CSP)") **Only if your website sends a `Content-Security-Policy` header or meta tag.** Most sites do not. If yours does not, skip this section — nothing needs to change. If it does, tick the CSP box in the [generator above](#Install) and it writes the directives for you. This section explains what they are and why, for when you have to merge them into a policy by hand. A restrictive policy fails silently CSP does not break your site and does not stop the snippet from appearing in the page. It blocks individual requests, so tracking looks installed while parts of it never run. Missing `img-src` costs you remarketing signals, missing `style-src` shows the consent banner unstyled, and a missing destination host disables that destination entirely — all without a single visible error for your visitors. Merge the directives below into your existing policy. Do not replace it — CSP directives are not additive across headers, and the last one wins. ### In every policy[​](#In-every-policy "Direct link to In every policy") Replace `YOUR_DOMAIN` with your root domain (for example `example.com`). ``` script-src 'self' 'unsafe-inline' https://*.YOUR_DOMAIN; connect-src 'self' https://*.YOUR_DOMAIN; ``` The wildcard covers any subdomain we serve from, so your policy keeps working if the tracking subdomain or the CDN host changes later. Note that `https://*.YOUR_DOMAIN` does **not** include the bare `YOUR_DOMAIN` — add it separately if your site serves assets from the apex. `'unsafe-inline'` is needed because the global code is an inline script. If your policy uses nonces, drop `'unsafe-inline'` and add your nonce attribute to the ` {%- if customer -%} {%- endif -%} {%- comment -%} PRODUCT PAGE ENRICHMENT (OPTIONAL) {%- endcomment -%} {%- if template contains 'product' -%} {% liquid assign active_currency = cart.currency.iso_code | default: shop.currency 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 %} {%- endif -%} ``` Replace `YOUR_SCRIPT_ID` with the Script ID provided to you — and the tracking subdomain too, if you did not fill it in above — then save. ### 1b. Include it in every layout[​](#1b-Include-it-in-every-layout "Direct link to 1b. Include it in every layout") Open `layout/theme.liquid` 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. `theme.liquid` is the default layout, but it is not always the only one. A template can ask for a different layout with `{% layout 'name' %}` — page builders such as PageFly, Shogun or GemPages often add their own for landing pages, and a page rendered by one of those layouts would load nothing. Open the **Layout** folder in the code editor and add the same three lines to every file that serves pages you want tracked, in the same position. In practice that is `theme.liquid` plus any custom layout an app or your developer added; `password.liquid` and `gift_card.liquid` can be skipped unless you have a reason to track them. Templates that render without a layout A template starting with `{% layout none %}` has no layout at all, so nothing you put in the Layout folder reaches it. If such a page matters to you, the snippet has to be rendered from the template itself. Position matters The snippet must run **after** `{{ content_for_header }}` so Shopify-injected scripts initialize first. Placing it inside the `` 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: '', 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 `YOUR_SCRIPT_ID` with the Script ID provided to you — and the tracking subdomain too, if you did not fill it in above. Leave `shopify.id` as the empty string unless we tell you otherwise. **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, set the **Customer privacy** block exactly like this: | Field | Value | | -------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | **Permission** | `Not required` *(The pixel will always run)* | | **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)* | Consent is read from the Shopify-native signal and enforced per destination further down the line, so it is not ignored — it is applied where it can be applied per destination rather than by switching the pixel off. See [Consent Overview](/events/consent/overview.md). ## Step 3 — Add the webhooks[​](#Step-3--Add-the-webhooks "Direct link to Step 3 — Add the webhooks") Some events never reach a browser. Webhooks bring them over from Shopify. Go to **Shopify Admin → Settings → Notifications → Webhooks → Create webhook** and add: | Event | Format | URL | | ---------------------- | ------ | ----------------------------------------------------------------------- | | **Order creation** | JSON | `https://dre2.YOUR_DOMAIN.TLD/webhooks/shopify/event?id=YOUR_SCRIPT_ID` | | **Order cancellation** | JSON | `https://dre2.YOUR_DOMAIN.TLD/webhooks/shopify/event?id=YOUR_SCRIPT_ID` | The URL is the same for every one of them. Use the same tracking subdomain and Script ID as in the snippet, and leave the API version at the one Shopify offers by default. Your account may need further events — we will tell you which. If we installed the app for you When the DATA Reshape team connects your store through the Shopify app, the webhooks are registered automatically. Check the Webhooks list first — if the entries are already there, skip this step. Multi-currency, Shopify Markets or several domains The setup above describes a single shop with one currency and one storefront domain. If Shopify Markets is active, prices are presented in more than one currency, or the same shop serves several country domains, the settings can differ — contact **** before you create the webhooks and we will tell you what to enter. ## 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, the last part of the snippet you pasted in [Step 1a](#1a-Create-the-snippet-file) — under the `PRODUCT PAGE ENRICHMENT` comment — pushes a **richer `product_viewed`** from the storefront, so destinations receive variant images, categories and parent SKU — fields the Custom Pixel does not surface on its own. It is already installed if you copied the whole file. Nothing else to paste. **What it adds to `product_viewed`:** every variant of the product with price, base price, SKU and parent SKU, barcode as `gtin`, up to five images at 1024px, product type as `category`, up to five collections as `categories`, and the variant options as `properties.variant`. **It only runs on product templates.** On every other page the block renders nothing. **Safe to remove.** Delete everything from the `PRODUCT PAGE ENRICHMENT` comment to the end of the snippet file. Tracking keeps working from the Custom Pixel alone, with a lighter `product_viewed` payload. Do not delete the `{% if customer %}` part above it: that one is not part of this feature and runs on every page. ## 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. One channel only The methods below are the only way to feed DATA Reshape from your own code. Anything else on the page 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. ## Verification[​](#Verification "Direct link to Verification") End-to-end verification is performed by the DATA Reshape team. Reach out at **** 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. ## 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 else — events that don't seem to arrive, discrepancies in a destination, any doubt about data quality — write to **** and we will check it. ## 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 ****. * **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. Your domainexample.comTracking subdomaindre2 Enter your domain and everything below is written with it. ## 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 `` tag: ``` ``` 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 = 'dre2.YOUR_DOMAIN.TLD'; $script_id = 'YOUR_SCRIPT_ID'; if (!is_admin()) { ?> (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","dre2.YOUR_DOMAIN.TLD","YOUR_SCRIPT_ID"); ``` 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`: ``` ` tag: `