Promotions

This section covers the API endpoints for managing promotions in the admin panel.

List Promotions

GET /v1/admin/promotions

Returns a list of promotions with pagination support.

Query Parameters

Parameter	Type	Description	Validation Rules
`search_text`	string	Search in promotion names	Optional
`filter[type]`	string	Filter by promotion type	Optional, values: marketing, guide_me
`filter[platform_name]`	string	Filter by platform name	Optional
`filter[duration]`	integer	Filter by duration	Optional
`filter[visits]`	integer	Filter by number of visits	Optional
`filter[created_at]`	string	Filter by creation date range	Optional
`filter[course_id]`	string	Filter by course UUID	Optional
`filter[bundle_id]`	string	Filter by bundle UUID	Optional
`filter[productable]`	string	Filter by product type	Optional
`per_page`	integer	Number of items per page	Optional, default: 10

Response

{
    "success": true,
    "message": "تم جلب البيانات بنجاح.",
    "data": {
        "current_page": 1,
        "first_page_url": "http://testing-api.sumaya369.net/v1/admin/promotions?page=1",
        "from": 1,
        "last_page": 120,
        "last_page_url": "http://testing-api.sumaya369.net/v1/admin/promotions?page=120",
        "links": [
            {
                "url": null,
                "label": "&laquo; السابق",
                "active": false
            },
            {
                "url": "http://testing-api.sumaya369.net/v1/admin/promotions?page=1",
                "label": "1",
                "active": true
            },
            {
                "url": "http://testing-api.sumaya369.net/v1/admin/promotions?page=2",
                "label": "2",
                "active": false
            },
            {
                "url": "http://testing-api.sumaya369.net/v1/admin/promotions?page=3",
                "label": "3",
                "active": false
            },
            
            {
                "url": null,
                "label": "...",
                "active": false
            },
            {
                "url": "http://testing-api.sumaya369.net/v1/admin/promotions?page=119",
                "label": "119",
                "active": false
            },
            {
                "url": "http://testing-api.sumaya369.net/v1/admin/promotions?page=120",
                "label": "120",
                "active": false
            },
            {
                "url": "http://testing-api.sumaya369.net/v1/admin/promotions?page=2",
                "label": "التالي &raquo;",
                "active": false
            }
        ],
        "next_page_url": "http://testing-api.sumaya369.net/v1/admin/promotions?page=2",
        "path": "http://testing-api.sumaya369.net/v1/admin/promotions",
        "per_page": 10,
        "prev_page_url": null,
        "to": 10,
        "total": 1200,
        "promotions": [
            {
                "id": "7afaa4b0-c912-11ef-9870-29f6482eeae0",
                "name": "باقة xxx",
                "platform_name": "sss",
                "duration": 5,
                "type": "marketing",
                "link": "https://testing-storefront.sumaya369.net/?promo=9r34pfazxbOrhKKelfXc",
                "special_link": null,
                "orders": 4,
                "sales": 400,
                "visits": 10,
                "created_at": "2025-01-02"
            },
            {
                "id": "4f929670-c912-11ef-921c-1d1f5819e88e",
                "name": "أسرار روحية",
                "platform_name": "yyy",
                "duration": 7,
                "type": "marketing",
                "link": "https://testing-storefront.sumaya369.net/materials/644c9940-d6d5-11ee-9bcd-37caa6e58047?promo=lCPgFkSBJj7uR1qRV0Uw",
                "special_link": "https://testing-storefront.sumaya369.net/materials/oX4Smt5xBM?promo=lCPgFkSBJj7uR1qRV0Uw",
                "orders": 4,
                "sales": 3713,
                "visits": 6,
                "created_at": "2025-01-02"
            },
            {
                "id": "79c874c0-c909-11ef-90f4-f30b80e318e1",
                "name": "الشغف2",
                "platform_name": "انستقرام",
                "duration": 100,
                "type": "marketing",
                "link": "https://testing-storefront.sumaya369.net/materials/6b52aa00-8dc9-11ee-a210-1983c8a1e1af?promo=khEolP7cZEFO76hl5rEA",
                "special_link": null,
                "orders": 4,
                "sales": 720,
                "visits": 6,
                "created_at": "2025-01-02"
            }
        ]
    },
    "status_code": 200
}

Get Promotion Details

GET /v1/admin/promotions/{id}

Returns details of a specific promotion.

Response

{
    "success": true,
    "message": "تم جلب البيانات بنجاح.",
    "data": {
        "id": "4f929670-c912-11ef-921c-1d1f5819e88e",
        "name": "أسرار روحية",
        "platform_name": "yyy",
        "cost": "70",
        "notes": null,
        "code": "lCPgFkSBJj7uR1qRV0Uw",
        "type": "marketing",
        "duration": 7,
        "courses": [
            {
                "id": "644c9940-d6d5-11ee-9bcd-37caa6e58047",
                "name": "أسرار روحية",
                "poster": "https://sumaya369-testing-media.s3.us-east-2.amazonaws.com/21600/3--%D8%A7%D8%B3%D8%B1%D8%A7%D8%B1-%D8%B1%D9%88%D8%AD%D9%8A%D8%A9_%D9%85%D9%82%D8%A7%D8%B3-%D8%A7%D9%84%D9%85%D9%88%D9%82%D8%B9-min.png"
            }
        ],
        "bundles": [],
        "statistics": {
            "visits": "6",
            "added_to_cart": "4",
            "sales": "3713.32",
            "orders": "4",
            "completed_orders": "4"
        },
        "created_at": "2025-01-02"
    },
    "status_code": 200
}

Create Promotion

POST /v1/admin/promotions

Creates a new promotion.

Request Body

Parameter	Type	Description	Validation Rules
`type`	string	Promotion type	Required, values: marketing, guide_me
`name`	string	Promotion name	Required, min: 3, max: 255
`platform_name`	string	Platform name	Required, min: 3, max: 255
`duration`	integer	Duration in days	Optional, min: 0
`cost`	number	Promotion cost	Optional, min: 0
`notes`	string	Additional notes	Optional, min: 3, max: 255
`code`	string	Promotion code	Optional, auto-generated if not provided
`course_ids`	array	Array of course UUIDs	Required without bundle_ids
`bundle_ids`	array	Array of bundle UUIDs	Required without course_ids

Response

{
    "success": true,
    "message": "تم حفظ البيانات بنجاح.",
    "data": {
        "name": "الحملة المحملة22",
        "platform_name": "instagram",
        "cost": "2000",
        "notes": "ملاحظةdfgdfgdfgd",
        "type": "marketing",
        "duration": "15",
        "code": "iUzZbLkb5FdbznzNsla4",
        "id": "96b90350-07e8-11f0-ac78-9d89b9da08ca",
        "updated_at": "2025-03-23 13:13:19",
        "created_at": "2025-03-23 13:13:19"
    },
    "status_code": 200
}

Update Promotion

PATCH /v1/admin/promotions/{id}

Updates an existing promotion.

Request Body

Parameter	Type	Description	Validation Rules
`type`	string	Promotion type	Optional, values: marketing, guide_me
`name`	string	Promotion name	Optional, min: 3, max: 255
`platform_name`	string	Platform name	Optional, min: 3, max: 255
`duration`	integer	Duration in days	Optional, min: 0
`cost`	number	Promotion cost	Optional, min: 0
`notes`	string	Additional notes	Optional, min: 3, max: 255
`course_ids`	array	Array of course UUIDs	Optional
`bundle_ids`	array	Array of bundle UUIDs	Optional

Response

{
    "success": true,
    "message": "تم تحديث البيانات بنجاح.",
    "data": {
        "id": "96b90350-07e8-11f0-ac78-9d89b9da08ca",
        "name": "الحملة المحملة22",
        "platform_name": "instagram",
        "code": "iUzZbLkb5FdbznzNsla4",
        "cost": "0",
        "notes": "ملاحظةdfgdfgdfgd",
        "duration": "0",
        "created_at": "2025-03-23 13:13:19",
        "updated_at": "2025-03-23 13:13:48",
        "type": "marketing"
    },
    "status_code": 200
}

Delete Promotions

DELETE /v1/admin/promotion

Deletes multiple promotions by their IDs.

Request Body

Parameter	Type	Description	Validation Rules
`ids`	array	Array of promotion IDs to delete	Required
`ids.*`	string	Promotion UUID	Required, UUID format

Response

{
    "success": true,
    "message": "تم حذف البيانات بنجاح.",
    "data": null,
    "status_code": 200
}

Get Promotion Statistics

GET /v1/admin/statistics/promotion

Returns aggregated statistics for marketing and guide-me promotions.

Response

{
    "success": true,
    "message": "تم جلب البيانات بنجاح.",
    "data": {
        "total_discounts": "20.7K",
        "discounts_count": "133/16",
        "most_used_discounts": [
            {
                "id": "5cd34b80-b2f9-11ef-be0b-51cf0a48dcf9",
                "name": "كود خصم المؤثرة شهد محمد",
                "uses": "50M"
            },
            {
                "id": "b237a820-4fa6-11ee-b893-fb237d93468e",
                "name": "sumaya_gift",
                "uses": "10M"
            },
            {
                "id": "1461f0e0-99c0-11ef-ab55-918807ddcf30",
                "name": "كود خصم الين سليمان شهر نوفمبر",
                "uses": "500K"
            },
            {
                "id": "9243f3e0-7f1f-11ef-a532-2ff92193929b",
                "name": "خصم ذوي الاحتياجات الخاصة",
                "uses": "200K"
            }
        ],
        "best_used_products": [
            {
                "name": "none",
                "price": 0
            }
        ]
    },
    "status_code": 200
}

Notes

The list endpoint supports filtering by various parameters including type, platform name, and creation date
Results are sorted by creation date in descending order by default
Promotion types:
- marketing: For marketing campaigns
- guide_me: For guided promotional activities
When creating or updating a promotion:
- At least one of course_ids or bundle_ids must be provided
- If code is not provided during creation, a random 20-character code will be generated
- Removing all course_ids or bundle_ids will detach all associated courses or bundles
Statistics include total orders, sales amount, and visit counts per promotion

List Promotions​

Query Parameters​

Response​

Get Promotion Details​

Response​

Create Promotion​

Request Body​

Response​

Update Promotion​

Request Body​

Response​

Delete Promotions​

Request Body​

Response​

Get Promotion Statistics​

Response​

Notes​

List Promotions

Query Parameters

Response

Get Promotion Details

Response

Create Promotion

Request Body

Response

Update Promotion

Request Body

Response

Delete Promotions

Request Body

Response

Get Promotion Statistics

Response

Notes