Product & Promotions Data

Product & Promotions data is a specialized data source format designed for the Nudge and Exit-Offer agents. Unlike traditional text-based data sources, this format uses structured CSV or JSON to store product catalogs with promotional information, enabling targeted promotional content on product and category pages.

Upload Options

There are two ways to upload product & promotions data: Standard Upload (requires data in the exact schema format) and AI-Assisted Upload (automatically maps your fields).

Standard Upload (Recommended)

For maximum accuracy and full control over your data, use the Upload Product Data tab with data pre-formatted to match the schema documented below. Standard upload is recommended when:

• You need precise control over how your data is structured
• You want to include custom metadata fields at product or promotion levels
• You've already formatted your data to match our schema
• You need guaranteed accuracy for production use

AI-Assisted Upload

The AI-Assisted Upload option allows you to upload product feeds and catalog exports as-is from most e-commerce platforms. Our AI analyzes your file structure and automatically maps your fields to the required schema format. This is useful for quickly importing data without manual formatting.

Correcting AI-Mapped Data

If you notice systematic errors in your AI-processed data (e.g., incorrect URL patterns or missing promotional info), you have several options:

• Fix Source Data: Correct your original export file and re-upload using AI-Assisted Upload again
• Use Find & Replace: In spreadsheet software, use find and replace to fix URL patterns before uploading (e.g., replace https://yoursite.com with empty string to get relative paths, or fix /p/ to /products/)
• Standard Upload: Pre-format your data to match the exact schema documented below and use the standard Upload tab

Import with Integration

If you have a connected integration (Shopify, BigCommerce, or WooCommerce), you can import product and promotion data directly from your store using the Import Data tab. This pulls your product catalog directly from the platform API and automatically converts it to the required schema format.

• Shopify: Imports products, variants, and active discounts
• BigCommerce: Imports products with pricing and sale information
• WooCommerce: Imports products, variations, and sale prices

Integration imports are processed in the background. Once complete, you can preview the data, download it for review, and confirm the upload. This is the easiest way to populate your product catalog if you have a supported e-commerce platform.

See the Integrations documentation for setup instructions for each platform.

Supported File Formats

Product & Promotions data sources accept CSV and JSON files. CSV files are automatically converted to JSON when uploaded. For standard uploads, your data must match the required schema format documented below.

CSV Format

CSV files work well when each row represents a variant (SKU) or product-promotion combination. Rows with the same productPath and productCodeare grouped into one product record, with variant rows merged into a variantsarray and promotion rows into a promotions array.

productPath,productName,category,productCode,highPrice,lowPrice,variantName,variantPath,variantPrice,sku,promotionType,promotionValue,promotionText,discountPrice,discountCode,thumbUrl
/products/wireless-headphones,Wireless Headphones,Electronics,WH-1000,99.99,99.99,Wireless Headphones - Black,/products/wireless-headphones?variant=blk,99.99,WH-1000-BLK,percent,20,20% OFF Summer Sale!,79.99,SUMMER20,https://example.com/headphones.jpg
/products/wireless-headphones,Wireless Headphones,Electronics,WH-1000,99.99,99.99,Wireless Headphones - Black,/products/wireless-headphones?variant=blk,99.99,WH-1000-BLK,shipping,,Free Shipping!,,,https://example.com/headphones.jpg
/products/pro-laptop-15,Pro Laptop 15",Computers,LP-500,1299.99,1299.99,Pro Laptop 15" - 256GB,/products/pro-laptop-15,1299.99,LP-500-256,dollar,200,Save $200 - Limited Time!,1099.99,,https://example.com/laptop.jpg
/products/ultra-runner,Ultra Runner,Footwear,RS-300,129.99,129.99,Ultra Runner - Blue,/products/ultra-runner?variant=blu,129.99,RS-300-BLU,percent,25,25% Off All Running Shoes,97.49,RUN25,https://example.com/shoes.jpg

Tip: Rows with the same productPath and productCodeare grouped into one product; each unique sku becomes a variant, and promotion columns populate the product's promotions array.

JSON Format

JSON uses one record per product. Each record has a variants array (at least one variant per product) and an optional promotions array. Do not flatten variants into separate records—all SKUs for a product belong in that product's variants array.

[
  {
    "productPath": "/products/wireless-headphones",
    "productName": "Wireless Headphones",
    "category": "Electronics",
    "productCode": "WH-1000",
    "highPrice": "99.99",
    "lowPrice": "99.99",
    "productThumbUrl": "https://example.com/headphones.jpg",
    "metadata": { "brand": "TechAudio" },
    "variants": [
      {
        "variantName": "Wireless Headphones - Black",
        "variantPath": "/products/wireless-headphones?variant=blk",
        "variantPrice": "99.99",
        "sku": "WH-1000-BLK"
      }
    ],
    "promotions": [
      {
        "promotionType": "percent",
        "promotionValue": 20,
        "promotionText": "20% OFF Summer Sale!",
        "discountPrice": "79.99",
        "discountCode": "SUMMER20",
        "validFrom": "2026-06-01",
        "validUntil": "2026-08-31",
        "metadata": { "campaign": "summer-2026" }
      },
      {
        "promotionType": "shipping",
        "promotionText": "Free Shipping on Orders $50+",
        "ctaLink": "/shipping-policy",
        "ctaText": "Learn More"
      }
    ]
  },
  {
    "productPath": "/products/pro-laptop-15",
    "productName": "Pro Laptop 15\"",
    "category": "Computers",
    "productCode": "LP-500",
    "highPrice": "1299.99",
    "lowPrice": "1299.99",
    "productThumbUrl": "https://example.com/laptop.jpg",
    "variants": [
      {
        "variantName": "Pro Laptop 15\" - 256GB",
        "variantPath": "/products/pro-laptop-15",
        "variantPrice": "1299.99",
        "sku": "LP-500-256"
      }
    ],
    "promotions": [
      {
        "promotionType": "dollar",
        "promotionValue": 200,
        "promotionText": "Save $200 - Limited Time!",
        "discountPrice": "1099.99",
        "ctaText": "Shop Now",
        "ctaLink": "/products/laptop?promo=save200"
      }
    ]
  }
]

Schema Reference

Each record represents one product. All SKUs/variations for that product go in the variants array—do not create separate records per variant.

Required Fields

Every product record must include the following fields:

Product Level

• productPath — URL path to product page (e.g., "/products/wireless-headphones", "/product/my-item")
• productName — Base product name only (no variant attributes)
• category — Product category for organization
• productCode — Parent/main SKU identifier tying variants together
• highPrice — Highest variant price as a string (e.g., "1299.99")
• lowPrice — Lowest variant price as a string (e.g., "99.99")
• variants — Array of at least one variant object (see Variant Level below)

Variant Level (each item in variants)

• variantName — Product name plus variant attributes (e.g., "Wireless Headphones - Black / Large")
• variantPath — Full path to the specific variant (e.g., product path + query params)
• variantPrice — Price for this variant as a string (e.g., "99.99")
• sku — Variant SKU identifier (required per variant)

Optional Fields

These fields enhance your promotional content but are not required:

Product Level

• productThumbUrl — URL to product thumbnail image
• description — Short product description (plain text, up to 300 characters)
• promotions — Array of promotion objects
• metadata — Custom key-value data for your use

Variant Level

• variantThumbUrl — Thumbnail URL for this variant
• metadata — Variant-specific options (e.g., color, size)—do not put sku here; it belongs at variant root

Promotion Level

• promotionType — Type of promotion: "percent", "dollar", "shipping", "bundle", "bogo", "sale", etc.
• promotionValue — Numeric discount value (e.g., 20 for 20% off, or 50 for $50 off)
• promotionText — Human-readable promotion message displayed to users
• discountPrice — Final price after the discount as a string (e.g., "79.99")
• discountCode — Coupon code customers can use at checkout
• ctaLink — Call-to-action link URL (e.g., product page, promo landing page)
• ctaText — Call-to-action button text (e.g., "Shop Now", "Learn More")
• validFrom — Promotion start date in ISO format (YYYY-MM-DD)
• validUntil — Promotion end date in ISO format (YYYY-MM-DD)
• metadata — Custom key-value data (campaign info, etc.)

Promotion Types

The promotionType field categorizes your promotion for display purposes:

• percent — Percentage discount (e.g., "20% off")
• dollar — Fixed dollar amount discount (e.g., "$50 off")
• shipping — Free or discounted shipping
• bundle — Bundle deals
• bogo — Buy one, get one promotions
• quantity — Quantity-based discounts
• gift — Free gift with purchase
• sale — General sale pricing
• clearance — Clearance items
• flash — Limited-time flash sales
• coupon — Coupon-based discounts
• other — Any other promotion type

Data Requirements

For optimal nudge and exit-offer targeting, ensure your product-promo data meets these guidelines:

• Accurate Product Paths: The productPath must match your actual product URL paths for targeting to work correctly
• Multiple Promotions: Include multiple promotions per product when available—the system randomly selects from available options for variety
• Consistent Categories: Use standardized category names across all products for better organization
• Valid URLs: Ensure all thumbnail and link URLs are accessible
• Promotion Dates: Include validFrom andvalidUntil to automatically expire time-sensitive promotions

URL Matching Behavior

When a visitor views a product page, Badgerfy automatically matches the page URL to your product data. Understanding how this works helps ensure your promotions display on the right pages.

How Matching Works

The system matches the current page URL path against productPath and each variant's variantPath. It also checks productCode and variant sku for segment matching as fallback.

URL: /products/wireless-headphones
✅ Matches if productPath = "/products/wireless-headphones"

URL: /mens-boots/C41371.html
✅ Matches if productPath = "/mens-boots/C41371.html" OR productCode = "C41371"

URL: /laptop-gaming/p/N82E16834156740R
✅ Matches if productPath matches OR sku = "N82E16834156740R"

Common E-Commerce URL Patterns

Set your productPath to match your URL structure:

• Shopify: productPath: "/products/product-handle"
• WooCommerce: productPath: "/product/product-slug"
• Magento: productPath: "/product-url-key.html"
• BigCommerce: productPath: "/product-name"
• Newegg-style: productPath: "/seo-slug/p/ITEM_NUMBER"
• Cole Haan-style: productPath: "/product-slug/STYLE_CODE.html"

Custom URL Structures

For best results, set productPath and each variant's variantPathto match your exact URLs. As fallback, the system checks productCode and variant sku against URL segments:

• productPath — Base product URL path (e.g., "/category/my-product")
• variantPath — Full path to the specific variant (e.g., with query params)
• productCode — Internal product code or style number
• sku — Variant SKU (inside each variant object)

Consumer API

For automated data pipelines, Pro and Business plan users can upload product-promo data programmatically using the Consumer API. This is ideal for keeping your promotions synchronized with your e-commerce platform.

The API supports both creating new product-promo data and updating existing datasets with zero downtime—your nudges continue using the current data until new uploads are fully processed.

See the Consumer API documentation for complete endpoint details, authentication, and example automation scripts.

Storage Management

Product & Promotions data counts toward your plan's storage limits. As your catalog grows, you may need to manage storage to stay within your plan's allocation.

Plan Storage Limits

• Basic Plan: 50MB maximum total storage
• Pro Plan: 100MB maximum total storage
• Business Plan: 500MB maximum total storage

Updating Your Data

When your promotions change, you can update your product-promo data using the Update button on each file in your data source. The update process:

• Uploads the new file while keeping the old data active
• Validates the data against the required schema
• Automatically replaces the old data once processing completes
• Maintains the same file reference name for consistency

Best Practices

• Match Product Paths Exactly: The productPath field should match your website's actual product URL paths
• Include Multiple Promotions: Adding variety keeps your nudges fresh—the system randomly selects from available promotions
• Use Clear Promotion Text: Write compelling, action-oriented messages that encourage clicks
• Set Expiration Dates: Use validUntil to automatically disable expired promotions
• Test Your Pages: After uploading, visit your product pages to verify nudges appear correctly
• Automate Updates: Pro and Business users should consider using the Consumer API to keep data synchronized with their e-commerce platform