Creating your first campaign

This guide walks you through creating effective campaigns using Karla's API. You'll learn how to set up different campaign types, configure targeting, and launch your first promotion.

Before you start

Required information

• Shop slug - Your unique shop identifier in Karla
• API credentials - See Authentication for setup instructions
• Campaign goal - What you want to achieve (sales, engagement, brand awareness)
• Target segment - Which customer segment to target

Understanding segments

Segments follow different naming patterns based on their source:

• Karla: Karla.name (e.g., Karla.vip_customers)
• Shopify: Shopify.category.name (e.g., Shopify.tag.wholesale)
• Klaviyo: Klaviyo.category.name (e.g., Klaviyo.list.high_value)
• Shopware: Shopware.category.name (e.g., Shopware.segment.b2b_buyers)
• Default: default (includes all customers that do not have a matching segment)

Check Segmentation for more details.

Step 1: Choose your campaign type

🎯 Basic Campaigns

Perfect for simple promotional messages and general offers.

POST /v1/shops/{slug}/campaigns - Basic Campaign

{
  "name": "Welcome Back Offer",
  "segment": "Shopify.tag.returning_customers",
  "promotion_type": "basic",
  "promotion_properties": {
    "title": "Thanks for Your Order!",
    "subtitle": "We hope you love your purchase. Here's 10% off your next order.",
    "cta_label": "Shop Again",
    "cta_url": "https://yourstore.com/collections/all",
    "image_url": "https://cdn.yourstore.com/welcome-back.jpg"
  },
  "enabled": true,
  "start_date": "2024-03-15T00:00:00+00:00",
  "end_date": "2024-06-15T23:59:59+00:00"
}

Response:

Campaign Created Response

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Welcome Back Offer",
  "shop_slug": "your-shop",
  "segment": "Shopify.tag.returning_customers",
  "promotion_type": "basic",
  "promotion_properties": {
    "title": "Thanks for Your Order!",
    "subtitle": "We hope you love your purchase. Here's 10% off your next order.",
    "cta_label": "Shop Again",
    "cta_url": "https://yourstore.com/collections/all",
    "image_url": "https://cdn.yourstore.com/welcome-back.jpg"
  },
  "enabled": true,
  "status": "active",
  "start_date": "2024-03-15T00:00:00+00:00",
  "end_date": "2024-06-15T23:59:59+00:00"
}

🎪 Product Campaigns

Showcase specific products to drive cross-sales and upsells.

POST /v1/shops/{slug}/campaigns - Product Campaign

{
  "name": "Recommended Products",
  "segment": "Klaviyo.list.high_value_customers",
  "promotion_type": "product",
  "promotion_properties": {
    "title": "You Might Also Like",
    "cta_label": "View Collection",
    "cta_url": "https://yourstore.com/collections/recommended",
    "products": [
      {
        "title": "Wireless Earbuds",
        "price": 79.99,
        "currency": "USD",
        "product_url": "https://yourstore.com/products/wireless-earbuds",
        "image_url": "https://cdn.yourstore.com/earbuds.jpg",
        "category": "new"
      },
      {
        "title": "Phone Case",
        "price": 24.99,
        "currency": "USD",
        "product_url": "https://yourstore.com/products/phone-case",
        "image_url": "https://cdn.yourstore.com/case.jpg",
        "category": "sale"
      }
    ]
  },
  "enabled": true
}

🎪 Banner Campaigns

Create eye-catching promotional banners for major sales and events.

POST /v1/shops/{slug}/campaigns - Banner Campaign

{
  "name": "Black Friday Sale",
  "segment": "segment",
  "promotion_type": "banner",
  "promotion_properties": {
    "title": "BLACK FRIDAY MEGA SALE",
    "subtitle": "Up to 70% off everything!",
    "cta_label": "Shop Now",
    "cta_url": "https://yourstore.com/collections/sale"
  },
  "enabled": true,
  "start_date": "2024-11-24T00:00:00+00:00",
  "end_date": "2024-11-30T23:59:59+00:00"
}

Step 2: List your campaigns

Check all campaigns for your shop:

GET /v1/shops/{slug}/campaigns

curl https://api.gokarla.io/v1/shops/your-shop-slug/campaigns \
  -u your-username:your-private-api-key

Response:

List Campaigns Response

[
  {
    uuid: "550e8400-e29b-41d4-a716-446655440000",
    name: "Welcome Back Offer",
    shop_slug: "your-shop",
    segment: "Shopify.tag.returning_customers",
    promotion_type: "basic",
    enabled: true,
    status: "active",
    start_date: "2024-03-15T00:00:00+00:00",
  },
  {
    uuid: "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    name: "Black Friday Sale",
    shop_slug: "your-shop",
    segment: "segment",
    promotion_type: "banner",
    enabled: true,
    status: "scheduled",
    start_date: "2024-11-24T00:00:00+00:00",
  },
];

Step 3: Update your campaign

Modify an existing campaign as needed:

PUT /v1/shops/{slug}/campaigns/{uuid}

{
  "name": "Extended Black Friday Sale",
  "segment": "segment",
  "promotion_type": "banner",
  "promotion_properties": {
    "title": "EXTENDED BLACK FRIDAY SALE",
    "subtitle": "Weekend extension - up to 70% off!",
    "cta_label": "Shop Final Hours",
    "cta_url": "https://yourstore.com/collections/sale"
  },
  "enabled": true,
  "start_date": "2024-11-24T00:00:00+00:00",
  "end_date": "2024-12-01T23:59:59+00:00"
}

Step 4: Monitor performance

Keep track of your campaigns by segment or status:

List Campaigns by Segment

curl https://api.gokarla.io/v1/shops/your-shop-slug/campaigns?segment=Klaviyo.list.vip \
  -u your-username:your-private-api-key

Advanced configuration

Multi-Product setup

For product campaigns with multiple items:

Advanced Product Campaign

{
  "name": "Summer Collection",
  "segment": "Karla.fashion_buyers",
  "promotion_type": "product",
  "promotion_properties": {
    "title": "Complete Your Summer Look",
    "cta_label": "Shop Collection",
    "cta_url": "https://yourstore.com/collections/summer",
    "products": [
      {
        "title": "Summer Dress",
        "price": 89.99,
        "currency": "USD",
        "product_url": "https://yourstore.com/products/summer-dress",
        "image_url": "https://cdn.yourstore.com/dress.jpg",
        "category": "new",
        "sku": "DRESS-001"
      },
      {
        "title": "Sandals",
        "price": 45.99,
        "currency": "USD",
        "product_url": "https://yourstore.com/products/sandals",
        "image_url": "https://cdn.yourstore.com/sandals.jpg",
        "category": "sale",
        "sku": "SANDALS-001"
      },
      {
        "title": "Sun Hat",
        "price": 29.99,
        "currency": "USD",
        "product_url": "https://yourstore.com/products/sun-hat",
        "image_url": "https://cdn.yourstore.com/hat.jpg",
        "sku": "HAT-001"
      }
    ]
  },
  "enabled": true,
  "start_date": "2024-06-01T00:00:00+00:00",
  "end_date": "2024-08-31T23:59:59+00:00"
}

Multi-Language support

Add translations for international customers:

Campaign with Translations

{
  "name": "Welcome Campaign",
  "segment": "Shopify.tag.new_customers",
  "promotion_type": "basic",
  "promotion_properties": {
    "title": "Welcome to Our Store!",
    "subtitle": "Enjoy 10% off your first order",
    "cta_label": "Shop Now",
    "cta_url": "https://yourstore.com",
    "translations": [
      {
        "language": "de",
        "values": {
          "title": "Willkommen in unserem Shop!",
          "subtitle": "Genießen Sie 10% Rabatt auf Ihre erste Bestellung",
          "cta_label": "Jetzt einkaufen",
          "cta_url": "https://yourstore.com/de"
        }
      }
    ]
  },
  "enabled": true
}

Working with different segment sources

Segment Examples by Source

{
  // Default segment (all customers)
  "segment": "default",

  // Karla internal segments (no category)
  "segment": "Karla.vip_customers",
  "segment": "Karla.repeat_buyers",
  "segment": "Karla.at_risk_customers",

  // Shopify customer tags
  "segment": "Shopify.tag.wholesale",
  "segment": "Shopify.tag.newsletter_subscribers",
  "segment": "Shopify.tag.first_time_buyers",

  // Klaviyo email lists
  "segment": "Klaviyo.list.abandoned_cart",
  "segment": "Klaviyo.list.high_value_customers",
  "segment": "Klaviyo.list.win_back_campaign",

  // Shopware customer segments
  "segment": "Shopware.segment.b2b_buyers",
  "segment": "Shopware.segment.premium_members"
}

Deactivating campaigns

When you need to stop a campaign:

DELETE /v1/shops/{slug}/campaigns/{uuid}

curl -X DELETE https://api.gokarla.io/v1/shops/your-shop-slug/campaigns/550e8400-e29b-41d4-a716-446655440000 \
  -u your-username:your-private-api-key

Best practices

✅ Do's

• Test campaigns with a small segment first
• Use compelling CTAs that create urgency
• Match campaign content to your brand voice
• Set appropriate start/end dates for time-sensitive offers
• Monitor segment exclusivity - only one campaign per segment
• Use meaningful segment names that clearly identify the target audience

❌ Don'ts

• Don't overwhelm customers with too many products in one campaign
• Don't forget to set proper segments for targeting
• Don't ignore campaign performance metrics
• Don't create overlapping campaigns for the same segment
• Don't use generic segments when specific targeting would be more effective

Troubleshooting

Common issues

Campaign not appearing?

• Verify enabled: true is set
• Check that campaign status is active not scheduled
• Confirm start_date is in the past
• Verify the segment exists and has customers

Campaign shows as scheduled?

• Check that start_date is not in the future
• Verify timezone formatting in ISO 8601 format

Segment conflicts?

• Occurs when a customer is in multiple segments, each targeted by an active campaign.
• Karla automatically resolves this by displaying one of the eligible campaigns.
• Best practice: Use mutually exclusive segments to ensure predictable campaign display.

Invalid segment format?

• Ensure Karla segments follow Karla.name format (no category needed)
• For external sources, use source.category.name format
• Use segment for the default segment (all customers)
• Verify the segment exists in your connected platform (Shopify, Klaviyo, etc.)
• Check that the source matches your integrated platforms

Next steps

Once you've mastered basic campaign creation:

1. Campaign types - Deep dive into each type
2. Campaign Entity API - Complete API documentation

Ready to create campaigns that drive real results? Start with a simple banner campaign and gradually experiment with more complex product recommendations!

---

Need Help?

If you encounter issues or have questions about campaign setup, contact our support team for assistance.