Skip to main content

Promotion System API - CRM App

The Promotion System in the CRM GraphQL API provides comprehensive content management functionality for creating, updating, and organizing promotional content. This system enables CRM users to manage promotions, sliders, popups, and video sliders with full lifecycle control, sorting capabilities, and bulk operations.

Overview​

The CRM promotion system is built around a unified Promotion entity that supports multiple content types within a single promotional campaign:

  • Promotions: Core promotional offers with comprehensive metadata
  • Sliders: Image-based promotional content for carousel displays
  • Popups: Modal promotional content with configurable layouts
  • Video Sliders: Video-based promotional content for multimedia experiences

Key Features​

🔧 Content Management​

  • Create small and big promotions with different feature sets
  • Add, update, and remove slider, popup, and video slider components
  • Bulk operations for efficient content management
  • Duplicate promotions for rapid content creation

📊 Lifecycle Management​

  • Draft → Staging Active → Active → Inactive status progression
  • Scheduled activation and deactivation
  • Content versioning and rollback capabilities
  • Translation status tracking

🎯 Organization & Sorting​

  • Category-based organization (Casino, Sports, General)
  • Content-specific sorting for sliders, popups, and video sliders
  • Index-based positioning for precise content ordering
  • Bulk sorting operations for efficient management

🌍 Multilingual Support​

  • Full multilingual content creation and editing
  • Translation workflow integration
  • Language-specific content validation
  • Bulk translation operations

🔍 Advanced Filtering​

  • Multi-criteria filtering for content discovery
  • Status-based filtering for workflow management
  • Category and type-based organization
  • Date range filtering for scheduled content

Authentication & Authorization​

All CRM operations require authentication with appropriate role permissions:

# All mutations require CMS role
mutation {
  createSmallPromotion(input: { ... }) {
    id
    name
    status
  }
}

Required Role: CMS (Content Management System)

Content Creation Workflow​

1. Create Base Promotion​

mutation {
  createSmallPromotion(input: {
    promotion: { ... }
    promotionSlider: { ... }    # Optional
    promotionPopup: { ... }     # Optional
    promotionVideoSlider: { ... } # Optional
  }) {
    id
    status
  }
}

2. Add Additional Components​

mutation {
  addSliderToPromotion(input: {
    promotionId: "..."
    category: HOME_PAGE
    promotionSlider: { ... }
  })
}

3. Activate Content​

mutation {
  changePromotionStatus(id: "...", status: STAGING_ACTIVE)
}

4. Sort for Visibility​

mutation {
  sortSliders(
    input: {
      sort: [{ promotionId: "...", index: 0 }, { promotionId: "...", index: 1 }]
      category: HOME_PAGE
    }
  )
}

Content Types​

Small Promotions​

Lightweight promotional content optimized for quick creation and display:

  • Basic metadata and SEO information
  • Single primary button configuration
  • Optional slider, popup, or video slider components
  • Streamlined creation process

Big Promotions​

Comprehensive promotional campaigns with advanced features:

  • Extended metadata and rich content
  • Primary and secondary button configurations
  • Icon button groups with positioning
  • "How it works" step-by-step guides
  • Badge and highlight configurations

Sorting System​

The promotion system uses a sophisticated sorting mechanism where each content type maintains its own sort order:

General Promotions​

  • Sorted by indexInPromotions.PROMOTION
  • Affects visibility in main promotion queries

Sliders​

  • Sorted by indexInSliderCategory.{CATEGORY}
  • Each slider category maintains independent sort order
  • Categories: HOME_PAGE, CASINO_LOBBY, SPORTS_LOBBY, etc.

Popups​

  • Sorted by indexInPopupCategory.{CATEGORY}
  • Independent sort order per popup category
  • Categories: POPUP, NOTIFICATION, BANNER, etc.

Video Sliders​

  • Sorted by indexInVideoSliderCategory.{CATEGORY}
  • Independent sort order per video category
  • Categories: CASINO_EXPLORE, SPORTS_HIGHLIGHT, etc.

Bulk Operations​

Bulk Updates​

mutation {
  bulkUpdatePromotion(
    input: {
      id: "..."
      bulkUpdate: {
        name: { EN: "Updated Name" }
        description: { EN: "Updated Description" }
      }
    }
  )
}

Bulk Deletion​

mutation {
  deletePromotions(ids: ["id1", "id2", "id3"])
}

Bulk Sorting​

mutation {
  sortPromotions(
    input: {
      sort: [
        { promotionId: "id1", index: 0 }
        { promotionId: "id2", index: 1 }
        { promotionId: "id3", index: 2 }
      ]
      category: PROMOTION
    }
  )
}

Query Categories​

Content Queries​

  • promotion(id: ID!) - Get single promotion by ID
  • promotions(...) - Get paginated list of promotions with filtering
  • sliders(...) - Get paginated list of slider content
  • popups(...) - Get paginated list of popup content
  • videoSliders(...) - Get paginated list of video slider content

Management Operations​

  • createSmallPromotion(...) - Create lightweight promotion
  • createBigPromotion(...) - Create comprehensive promotion
  • updatePromotion(...) - Update promotion metadata
  • duplicatePromotion(...) - Clone existing promotion
  • changePromotionStatus(...) - Modify promotion lifecycle status

Component Operations​

  • addSliderToPromotion(...) - Add slider component
  • addPopupToPromotion(...) - Add popup component
  • addVideoSliderToPromotion(...) - Add video slider component
  • updateSliderOnPromotion(...) - Modify slider component
  • updatePopupOnPromotion(...) - Modify popup component
  • updateVideoSliderOnPromotion(...) - Modify video slider component

Sorting Operations​

  • sortPromotions(...) - Sort general promotions
  • sortSliders(...) - Sort slider content by category
  • sortPopups(...) - Sort popup content by category
  • sortVideoSliders(...) - Sort video slider content by category

Error Handling​

The API provides detailed error messages for common scenarios:

Validation Errors​

  • Invalid input data format
  • Missing required fields
  • Constraint violations

Business Logic Errors​

  • Invalid status transitions
  • Duplicate slug conflicts
  • Access policy violations

System Errors​

  • Database connectivity issues
  • External service failures
  • Cache invalidation problems

Performance Considerations​

Caching Strategy​

  • Promotion lists cached for 5 minutes
  • Individual promotions cached for 15 minutes
  • Sort operations invalidate related caches
  • Translation data cached for 1 hour

Rate Limiting​

  • Bulk operations limited to 100 items per request
  • Sort operations limited to 50 items per request
  • Create operations limited to 10 per minute per user

Next Steps​

  • Operations - Detailed mutation and query documentation