Skip to main content

Promotions API

Event and competition promotion configuration.

List Promotions​

GET /promotions

Query Parameters

ParameterTypeDescription
tenantIdstringRequired
clubIdstringFilter by club
sourceTypestringCOMPETITION, CLUB_EVENT, SPECIAL
isActivebooleanFilter active

Response: 200 OK

{
  "data": [{
    "id": "promo_123",
    "tenantId": "tenant_123",
    "clubId": "club_456",
    "sourceType": "COMPETITION",
    "sourceId": "competition_789",
    "sourceName": "Summer Championship 2025",
    "autoPromote": true,
    "channels": ["EMAIL", "SMS", "SOCIAL"],
    "announceAt": "2025-12-15T09:00:00Z",
    "reminderDays": [7, 3, 1],
    "segmentId": "segment_123",
    "segmentName": "Active Golfers",
    "lastPromotedAt": "2025-12-15T09:00:00Z",
    "isActive": true,
    "createdAt": "2025-12-01T00:00:00Z"
  }]
}

Get Promotion​

GET /promotions/:id

Response: 200 OK

{
  "id": "promo_123",
  "tenantId": "tenant_123",
  "clubId": "club_456",
  "sourceType": "COMPETITION",
  "sourceId": "competition_789",
  "sourceName": "Summer Championship 2025",
  "sourceDate": "2025-12-28T07:00:00Z",
  "autoPromote": true,
  "channels": ["EMAIL", "SMS", "SOCIAL"],
  "announceAt": "2025-12-15T09:00:00Z",
  "reminderDays": [7, 3, 1],
  "segmentId": "segment_123",
  "emailTemplateId": "tournament_invite",
  "smsTemplateId": "tournament_sms",
  "socialContent": "Join us for the Championship Tournament!",
  "lastPromotedAt": "2025-12-15T09:00:00Z",
  "isActive": true,
  "promotionHistory": [
    {
      "type": "ANNOUNCEMENT",
      "sentAt": "2025-12-15T09:00:00Z",
      "channels": ["EMAIL", "SMS", "SOCIAL"],
      "recipientCount": 450
    }
  ],
  "createdBy": "user_123",
  "createdAt": "2025-12-01T00:00:00Z",
  "updatedAt": "2025-12-15T09:00:00Z"
}

Create Promotion​

POST /promotions

Request Body

{
  "tenantId": "tenant_123",
  "clubId": "club_456",
  "sourceType": "COMPETITION",
  "sourceId": "competition_789",
  "autoPromote": true,
  "channels": ["EMAIL", "SMS", "SOCIAL"],
  "announceAt": "2025-12-15T09:00:00Z",
  "reminderDays": [7, 3, 1],
  "segmentId": "segment_active_golfers",
  "emailTemplateId": "tournament_invite",
  "smsTemplateId": "tournament_sms",
  "socialContent": "Join us for the Championship Tournament!"
}

Response: 201 Created

Update Promotion​

PATCH /promotions/:id

Request Body

{
  "autoPromote": false,
  "channels": ["EMAIL"],
  "reminderDays": [7, 1]
}

Response: 200 OK

Delete Promotion​

DELETE /promotions/:id

Response: 204 No Content

Execute Promotion Now​

Manually triggers the promotion campaign.

POST /promotions/:id/execute

Request Body (optional)

{
  "channels": ["EMAIL"],
  "type": "REMINDER"
}

Response: 200 OK

{
  "id": "promo_123",
  "executedAt": "2025-12-14T10:00:00Z",
  "channels": ["EMAIL"],
  "type": "REMINDER",
  "recipientCount": 450,
  "campaignId": "campaign_auto_123"
}

Preview Promotion​

Preview the promotion content and recipient count.

POST /promotions/:id/preview

Response: 200 OK

{
  "id": "promo_123",
  "recipientCount": 450,
  "channels": {
    "EMAIL": {
      "recipientCount": 420,
      "subject": "You're Invited: Summer Championship 2025",
      "previewHtml": "<html>..."
    },
    "SMS": {
      "recipientCount": 380,
      "previewText": "Randpark GC: Join us for Summer Championship on Dec 28..."
    },
    "SOCIAL": {
      "platforms": ["FACEBOOK", "INSTAGRAM"],
      "previewContent": "Join us for the Championship Tournament!"
    }
  }
}

Promotion Source Types​

COMPETITION​

Promotes a golf competition from the TeeTime system.

{
  "sourceType": "COMPETITION",
  "sourceId": "competition_uuid"
}

Auto-trigger: When competition is published in TeeTime.

CLUB_EVENT​

Promotes a club event (social events, dinners, etc.).

{
  "sourceType": "CLUB_EVENT",
  "sourceId": "event_uuid"
}

SPECIAL​

Custom promotional campaign not tied to an event.

{
  "sourceType": "SPECIAL",
  "sourceId": "custom_reference"
}

Promotion Channels​

ChannelDescription
EMAILEmail campaign via Messaging service
SMSSMS campaign via Messaging service
PUSHPush notification via Messaging service
SOCIALSocial media posts to connected accounts

Auto-Promote Configuration​

When autoPromote is enabled, promotions are automatically triggered:

  1. Announcement: Sent at announceAt time
  2. Reminders: Sent at each reminderDays before event date
{
  "autoPromote": true,
  "announceAt": "2025-12-15T09:00:00Z",
  "reminderDays": [7, 3, 1]
}

This creates:

  • Announcement on Dec 15
  • Reminder 7 days before (Dec 21)
  • Reminder 3 days before (Dec 25)
  • Reminder 1 day before (Dec 27)

Promotion Templates​

Email Template Variables​

VariableDescription
{{eventName}}Event/competition name
{{eventDate}}Formatted event date
{{eventTime}}Event start time
{{clubName}}Club name
{{registrationUrl}}Registration link
{{daysUntil}}Days until event

SMS Template Variables​

Same as email, but content should be kept brief (160 chars).