For developers

Quick guide to integrating Flow Retail's Campaign API into your applications, like for example syncing campaigns from a 3rd party system directly into Flow Retail so that one do not need to add and manage the campaign(s) in Flow Retail.

Full API reference: Campaign API Documentation

Quick Start

1. Create a campaign

POST /v2/tenants/{tenantUid}/campaigns
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json

{
  "name": "3 for 2 T-shirts - Summer 2025",
  "displayName": "3 for 2",
  "type": "CAMPAIGN",
  "discountType": "CHEAPEST_PRODUCT",
  "validFrom": "2025-06-01T00:00:00Z",
  "validTo": "2025-06-30T23:59:59Z",
  "quantityThreshold": 3,
  "discountPercent": 100
}

Campaign is created with status: "NEW" (not yet active).

2. Add products

POST /v2/tenants/{tenantUid}/campaigns/{campaignUid}/selections

{
  "create": {
    "include": {
      "categoryUids": ["cat_tshirts"]
    }
  }
}

3. Activate

PUT /v2/tenants/{tenantUid}/campaigns/{campaignUid}

{
  "status": "ACTIVE"
}

Done! Campaign is now live.

Key Concepts

Campaign Types

CAMPAIGN - Standard discounts with rules

• Choose discount type: CHEAPEST_PRODUCT, QUALIFIED_PRODUCT, or ORDER_DISCOUNT

• Set conditions: quantity threshold, amount threshold, customer groups

• Most flexible option

PRICELIST - Fixed prices from a price list

• Reference an existing price list

• No discount rules, just fixed prices

• Simpler but less flexible

Common Patterns

Quantity Discount (3 for 2)

{
  "type": "CAMPAIGN",
  "discountType": "CHEAPEST_PRODUCT",
  "quantityThreshold": 3,
  "discountPercent": 100
}

Add products → Activate

Member Discount (15% for VIP)

{
  "type": "CAMPAIGN",
  "discountType": "QUALIFIED_PRODUCT",
  "discountPercent": 15,
  "customerGroupUid": "group_vip"
}

Leave products empty (applies to all) → Activate

Spend & Save ($100+ = 10% off)

{
  "type": "CAMPAIGN",
  "discountType": "ORDER_DISCOUNT",
  "amountThreshold": 100.00,
  "discountPercent": 10
}

Don't add products (order-level) → Activate

Important Rules

✅ Valid Combinations

• CHEAPEST_PRODUCT + quantityThreshold ✅

• QUALIFIED_PRODUCT + quantityThreshold ✅

• ORDER_DISCOUNT + amountThreshold ✅

• Any discount type + customerGroupUid ✅

• Any discount type + maxUsage ✅

❌ Invalid Combinations

• ORDER_DISCOUNT + product selections ❌ (order-level discount applies to everything)

• discountAmount + discountPercent ❌ (choose one)

• Using quantityThreshold and amountThreshold together ⚠️ (both must be met)

Critical Behaviors

1. Confirmed Order Lines

Problem: Confirmed order lines cannot receive campaigns.

Solution: Don't confirm orders until finalizing the order

2. Scanning Order (for CHEAPEST_PRODUCT)

Problem: Discount is calculated based on scanning order.

Solution:

• Allow staff to remove and re-scan items if needed

• System will recalculate with optimal discount

3. Product Selection Timing

Products are resolved when you activate the campaign. If you add new products to an included category/brand/product group after activation, they won't be included until you deactivate and reactivate the campaign.

4. Updating Campaigns

When updating, include ALL fields that should remain:

PUT /campaigns/{uid}
{
  "storeUids": ["store_1", "store_2"]  // Must include ALL stores
}

Missing fields may be removed.

---

Common Issues

Campaign does not apply?

Check:

• Status is ACTIVE

• Current date/time is between validFrom and validTo

• Products are in selections (or selections empty for all products)

• Customer is in customerGroup if specified

• Order lines are not confirmed

Best Practices

Handle large catalogs efficiently

For 1000+ products with few exceptions, use exclude instead of include:

{
  "create": {
    "exclude": {
      "productUids": ["prod_1", "prod_2"]  // Just exclude sale items
    }
  }
}

Much faster than adding thousands of products to include.

Don't confirm lines early

Keep order lines unconfirmed while the customer is shopping. Confirmed lines cannot receive campaigns and must be deleted and re-added.

// ❌ Bad: Confirming during shopping
order.addProduct(product);
order.confirmLine(lineId);  // Too early!

// ✅ Good: Confirm at checkout
order.addProduct(product1);
order.addProduct(product2);
// ... customer continues shopping ...
order.confirmAllLines();  // At final checkout

Need more details?

Full API Documentation

• Campaign API Reference - Complete endpoint documentation

• Product API - Managing products

• Order API - How campaigns apply to orders

• Customer Groups API - Managing customer segments

Support

• [email protected]