Authenticated API

This endpoint requires a valid JWT Bearer token. Accessible via the API gateway at /v1/commerce/*.

Marketing & CRM API

Manage marketing campaigns, customer segments, webhook integrations, and CRM operations.

Overview

Attribute	Value
Base Path	/api/v1/marketing
Authentication	Bearer Token
Required Roles	marketing, marketing_manager, manager, restaurant_manager, tenant_admin, platform_admin, system_admin, super_admin

Campaign Endpoints

List Campaigns

Retrieve marketing campaigns.

GET /api/v1/marketing/campaigns

Query Parameters

Parameter	Type	Description
status	string	draft, scheduled, active, paused, completed
type	string	Campaign type filter
start_date	date	Filter by start date
page	integer	Page number
limit	integer	Results per page

Response

{
  "data": [
    {
      "id": "camp_001",
      "name": "Summer Promo 2026",
      "type": "promotion",
      "status": "active",
      "channels": ["email", "push", "sms"],
      "segment_id": "seg_loyalty_gold",
      "start_date": "2026-06-01T00:00:00Z",
      "end_date": "2026-08-31T23:59:59Z",
      "metrics": {
        "sent": 5420,
        "opened": 2180,
        "clicked": 845,
        "converted": 156
      }
    }
  ]
}

Campaign Types

Type	Description
onboarding	New customer welcome series
reengagement	Win-back inactive customers
promotion	Promotional offers
newsletter	Regular newsletter
transactional	Order confirmations, receipts
loyalty	Loyalty program communications

---

Create Campaign

Create a new marketing campaign.

POST /api/v1/marketing/campaigns

Request Body

{
  "name": "Flash Sale Friday",
  "type": "promotion",
  "channels": ["push", "email"],
  "segment_id": "seg_all_customers",
  "content": {
    "subject": "Flash Sale - 25% Off Today Only!",
    "body": "Don't miss our biggest sale of the season...",
    "cta_text": "Shop Now",
    "cta_url": "https://order.example.com?promo=FLASH25"
  },
  "schedule": {
    "start_date": "2026-01-31T12:00:00Z",
    "end_date": "2026-01-31T23:59:59Z"
  },
  "promo_code": "FLASH25",
  "promo_discount_percent": 25
}

---

Get Campaign

Retrieve campaign details with full metrics.

GET /api/v1/marketing/campaigns/{campaign_id}

Response

{
  "id": "camp_001",
  "name": "Flash Sale Friday",
  "type": "promotion",
  "status": "completed",
  "channels": ["push", "email"],
  "segment": {
    "id": "seg_all_customers",
    "name": "All Customers",
    "size": 5420
  },
  "content": {...},
  "metrics": {
    "sent": 5420,
    "delivered": 5380,
    "opened": 2180,
    "open_rate": 40.5,
    "clicked": 845,
    "click_rate": 15.7,
    "converted": 156,
    "conversion_rate": 2.9,
    "revenue_attributed": 4680.00,
    "unsubscribed": 12
  },
  "created_at": "2026-01-25T10:00:00Z"
}

---

Customer Segments

List Segments

GET /api/v1/marketing/segments

Response

{
  "data": [
    {
      "id": "seg_loyalty_gold",
      "name": "Gold Loyalty Members",
      "type": "dynamic",
      "size": 1250,
      "criteria": {
        "loyalty_tier": "gold"
      },
      "last_updated": "2026-01-24T00:00:00Z"
    },
    {
      "id": "seg_inactive_30",
      "name": "Inactive 30+ Days",
      "type": "dynamic",
      "size": 890,
      "criteria": {
        "last_order_days_ago": {"gte": 30}
      }
    }
  ]
}

Segment Types

Type	Description
static	Manually defined customer list
dynamic	Auto-updated based on criteria
imported	Imported from external source

---

Create Segment

POST /api/v1/marketing/segments

Request Body

{
  "name": "High Value Customers",
  "type": "dynamic",
  "criteria": {
    "total_spent": {"gte": 500},
    "order_count": {"gte": 10},
    "loyalty_tier": {"in": ["gold", "platinum"]}
  }
}

---

Webhook Integrations

List Webhook Providers

GET /api/v1/marketing/webhooks

Response

{
  "providers": [
    {
      "id": "sendgrid",
      "name": "SendGrid",
      "status": "connected",
      "events_received": 15420,
      "last_event": "2026-01-24T18:30:00Z"
    },
    {
      "id": "twilio",
      "name": "Twilio",
      "status": "connected",
      "events_received": 8920
    },
    {
      "id": "mailchimp",
      "name": "Mailchimp",
      "status": "disconnected"
    }
  ]
}

Supported Providers

Provider	Events Supported
sendgrid	delivered, opened, clicked, bounced, unsubscribed
twilio	delivered, failed
mailchimp	subscribed, unsubscribed, campaign_sent
hubspot	contact_created, form_submitted

---

Receive Webhook

Endpoint for external providers to send events.

POST /api/v1/marketing/webhooks/{provider}

Headers

Header	Description
X-Webhook-Signature	HMAC signature for verification
X-Webhook-Timestamp	Event timestamp

Request Body (varies by provider)

{
  "event_type": "email.opened",
  "email": "customer@example.com",
  "campaign_id": "camp_001",
  "timestamp": "2026-01-24T18:30:00Z"
}

---

Funnel Analytics

Get Funnel Metrics

GET /api/v1/marketing/funnels

Query Parameters

Parameter	Type	Description
funnel_type	string	onboarding, purchase, retention
start_date	date	Analysis start
end_date	date	Analysis end

Response

{
  "funnel_type": "onboarding",
  "period": {
    "start": "2026-01-01",
    "end": "2026-01-24"
  },
  "stages": [
    {
      "stage": "awareness",
      "count": 10000,
      "percentage": 100
    },
    {
      "stage": "interest",
      "count": 6500,
      "percentage": 65,
      "drop_off": 35
    },
    {
      "stage": "consideration",
      "count": 3200,
      "percentage": 32,
      "drop_off": 33
    },
    {
      "stage": "purchase",
      "count": 1200,
      "percentage": 12,
      "drop_off": 20
    },
    {
      "stage": "activation",
      "count": 980,
      "percentage": 9.8,
      "drop_off": 2.2
    }
  ],
  "overall_conversion": 9.8
}

Funnel Stages

Stage	Description
awareness	First touchpoint
interest	Browsed menu/website
consideration	Added items to cart
intent	Started checkout
evaluation	Compared options
purchase	Completed order
onboarding	First-time experience
activation	Second order
retention	Regular customer
advocacy	Referred others

---

Promo Codes

List Promo Codes

GET /api/v1/marketing/promos

Create Promo Code

POST /api/v1/marketing/promos

Request Body

{
  "code": "WELCOME20",
  "type": "percentage",
  "value": 20,
  "min_order_amount": 25.00,
  "max_discount": 50.00,
  "usage_limit": 1000,
  "per_customer_limit": 1,
  "valid_from": "2026-01-01T00:00:00Z",
  "valid_until": "2026-12-31T23:59:59Z",
  "applies_to": {
    "all_items": true
  },
  "customer_segment_id": "seg_new_customers"
}

---

Error Responses

Status	Code	Description
400	invalid_segment_criteria	Segment criteria malformed
400	invalid_promo_code	Promo code format invalid
404	campaign_not_found	Campaign ID not found
409	promo_code_exists	Promo code already in use
422	segment_too_large	Segment exceeds max size for channel

---

Related Documentation

• Marketing CRM Guide - Manager guide
• Customers API - Customer management
• Loyalty API - Loyalty program