Campaign types

This reference guide provides a comprehensive overview of all campaign types, their properties, and when to use each one.

Campaign type comparison

Feature	Basic	Product	Banner
Best For	General promotions	Product showcase	Discount offers
Visual Style	Simple card	Product grid	Large banner
Product Support	❌	✅ Multiple	❌
Discount Display	Basic code	Per-product	Prominent
Complexity	Low	Medium	Low
Use Cases	Brand awareness	Cross-sell/upsell	Sales events

Overall campaign required fields

All campaigns must include these fields regardless of type:

{
  "name": "string", // Required
  "segment": "string", // Required
  "promotion_type": "basic|product|banner", // Required
  "promotion_properties": {} // Required (object, type-specific)
}

Basic Campaigns

Overview

Simple promotional content with custom messaging and call-to-action buttons. Perfect for general brand messaging, service announcements, or simple offers.

Required fields

{
  "promotion_type": "basic",
  "promotion_properties": {} // No required fields within properties
}

Note: Basic campaigns have no required fields within promotion_properties. All properties are optional.

All available properties

{
  "promotion_properties": {
    "title": "Welcome back!",
    "subtitle": "Thanks for being a loyal customer",
    "cta_label": "Shop Now",
    "cta_url": "https://shop.com/featured",
    "image_url": "https://shop.com/banner.jpg",
    "discount_code": "WELCOME10", // Deprecated: use discount object
    "translations": [
      {
        "language": "de",
        "values": {
          "title": "Willkommen zurück!",
          "subtitle": "Danke für Ihre Treue",
          "cta_label": "Jetzt einkaufen",
          "cta_url": "https://shop.com/de/featured",
          "image_url": "https://shop.com/de/banner.jpg"
        }
      }
    ]
  }
}

Best use cases

• Welcome messages for new customers
• Thank you campaigns after delivery
• Service announcements (shipping delays, policy changes)
• Brand storytelling and engagement
• Simple promotional offers

Example

{
  "name": "Customer Appreciation",
  "promotion_type": "basic",
  "segment": "Karla.loyal_customers",
  "promotion_properties": {
    "title": "Thank you for your loyalty!",
    "subtitle": "Enjoy 15% off your next order as our way of saying thanks",
    "cta_label": "Claim Offer",
    "cta_url": "https://shop.com/loyalty-discount",
    "image_url": "https://shop.com/images/thank-you.jpg"
  }
}

---

Product Campaigns

Overview

Showcase specific products with rich product information and recommendations. Ideal for cross-selling, upselling, and product discovery.

Required fields

{
  "promotion_type": "product",
  "promotion_properties": {
    "products": [
      // At least one product required, each product needs:
      {
        "product_url": "string", // Required
        "currency": "string" // Required
      }
    ]
  }
}

Note: The products array itself is not required in the schema, but if you include products, each product must have product_url and currency.

All available properties

{
  "promotion_properties": {
    "title": "You might also like",
    "cta_label": "View Collection",
    "cta_url": "https://shop.com/collections/recommended",
    "products": [
      {
        "title": "Premium Headphones",
        "image_url": "https://shop.com/headphones.jpg",
        "product_url": "https://shop.com/products/headphones", // Required
        "price": 99.99,
        "currency": "EUR", // Required
        "category": "new", // "sale" or "new"
        "sku": "HEADPHONES-001",
        "discount": {
          "value": 15,
          "value_type": "percentage" // or "fixed"
        },
        "translations": [
          {
            "language": "de",
            "values": {
              "title": "Premium Kopfhörer",
              "image_url": "https://shop.com/de/headphones.jpg",
              "product_url": "https://shop.com/de/products/headphones"
            }
          }
        ]
      }
    ],
    "translations": [
      {
        "language": "de",
        "values": {
          "title": "Das könnte Ihnen auch gefallen",
          "cta_label": "Kollektion ansehen",
          "cta_url": "https://shop.com/de/collections/recommended"
        }
      }
    ]
  }
}

Product categories

• "new" - Highlight new arrivals and fresh inventory
• "sale" - Feature discounted or promotional items

Best use cases

• Cross-selling complementary products
• Upselling premium alternatives
• Product discovery for new items
• Inventory promotion for slow-moving stock
• Personalized recommendations based on purchase history

Example

{
  "name": "Complete Your Kitchen Setup",
  "promotion_type": "product",
  "segment": "Shopify.tag.kitchen_buyers",
  "promotion_properties": {
    "title": "Complete your kitchen setup",
    "products": [
      {
        "title": "Chef's Knife Set",
        "image_url": "https://shop.com/knife-set.jpg",
        "product_url": "https://shop.com/products/chef-knife-set",
        "price": 149.99,
        "currency": "USD",
        "category": "new",
        "sku": "KNIFE-SET-001"
      },
      {
        "title": "Cutting Board",
        "image_url": "https://shop.com/cutting-board.jpg",
        "product_url": "https://shop.com/products/cutting-board",
        "price": 39.99,
        "currency": "USD",
        "category": "sale",
        "sku": "BOARD-001",
        "discount": {
          "value": 20,
          "value_type": "percentage"
        }
      }
    ]
  }
}

---

Banner Campaigns

Overview

Eye-catching banner-style promotions with prominent discount information. Perfect for time-sensitive offers, seasonal promotions, and major sales events.

Required fields

{
  "promotion_type": "banner",
  "promotion_properties": {} // No required fields within properties
}

Note: Banner campaigns have no required fields within promotion_properties. All properties are optional.

All available properties

{
  "promotion_properties": {
    "title": "BLACK FRIDAY SALE",
    "subtitle": "Up to 50% off everything!",
    "cta_label": "Shop Sale",
    "cta_url": "https://shop.com/collections/sale",
    "discount": {
      "value": 25,
      "value_type": "percentage" // or "fixed"
    },
    "translations": [
      {
        "language": "de",
        "values": {
          "title": "BLACK FRIDAY SALE",
          "subtitle": "Bis zu 50% Rabatt auf alles!",
          "cta_label": "Sale einkaufen",
          "cta_url": "https://shop.com/de/collections/sale"
        }
      }
    ]
  },
  "discount_id": "uuid-of-existing-discount" // Optional: link to discount system
}

Discount types

• "percentage" - Show percentage off (e.g., "25% OFF")
• "fixed" - Show fixed amount off (e.g., "$10 OFF")

Best use cases

• Seasonal sales (Black Friday, Christmas, Summer Sale)
• Flash sales with time pressure
• Clearance events for inventory
• Holiday promotions with themes
• Welcome offers for new customers

Example

{
  "name": "Summer Clearance Event",
  "promotion_type": "banner",
  "segment": "default",
  "start_date": "2024-07-01T00:00:00+00:00",
  "end_date": "2024-07-31T23:59:59+00:00",
  "promotion_properties": {
    "title": "SUMMER CLEARANCE",
    "subtitle": "Everything must go! Up to 70% off",
    "cta_label": "Shop Clearance",
    "cta_url": "https://shop.com/collections/clearance",
    "discount": {
      "value": 40,
      "value_type": "percentage"
    }
  }
}

---

Common Properties

Multi-language support

All campaign types support translations for international stores:

{
  "translations": [
    {
      "language": "de", // ISO language code (required)
      "values": {
        // Required
        // Translated versions of text fields
        "title": "German title",
        "subtitle": "German subtitle",
        "cta_label": "German CTA",
        "cta_url": "https://shop.com/de/page"
      }
    },
    {
      "language": "es",
      "values": {
        "title": "Spanish title",
        "subtitle": "Spanish subtitle"
      }
    }
  ]
}

Discount integration

Campaigns can integrate with your discount system:

{
  "discount_id": "12345678-1234-1234-1234-123456789012", // UUID of existing discount
  "promotion_properties": {
    "discount": {
      // Discount display information
      "value": 25,
      "value_type": "percentage"
    }
  }
}

Image guidelines

• Minimum resolution: 800x800px recommended
• Format: JPEG, PNG, WebP supported
• Aspect ratio: Square (1:1) or landscape (16:9) work best
• File size: Keep under 500KB for fast loading
• Content: High contrast text, clear product visibility

---

Selection guide

Choose Basic when

• ✅ You have a simple message to communicate
• ✅ You want to drive traffic to a specific page
• ✅ You're doing brand awareness campaigns
• ✅ You need quick setup with minimal complexity

Choose Product when

• ✅ You want to showcase specific items
• ✅ You're doing cross-sell or upsell campaigns
• ✅ You have rich product data to display
• ✅ You want to drive direct product sales

Choose Banner when

• ✅ You have a prominent discount to highlight
• ✅ You're running time-sensitive sales
• ✅ You want maximum visual impact
• ✅ You're doing seasonal or event-based promotions

---

Quick Reference

Campaign Status values

• "scheduled" - Not yet started
• "active" - Currently running
• "inactive" - Ended or disabled
• "paused" - Temporarily disabled

Product Categories

• "new" - New arrivals
• "sale" - Discounted items

Discount value types

• "percentage" - Percentage discount (e.g., 25%)
• "fixed" - Fixed amount discount (e.g., $10)

Required API Fields

For all campaigns:

• name - Campaign name (string)
• segment - Target segment (string)
• promotion_type - Type of campaign (basic/product/banner)
• promotion_properties - Campaign-specific properties (object)

For product campaigns with products:

• Each product requires: product_url (string) and currency (string)

For translations (if used):

• Each translation requires: language (string) and values (object)

---

Need more details? Check the Campaign API Reference for complete technical specifications.