Ad Campaigns & Marketing API

Paid marketing campaigns management and promotion endpoints

1. Purpose

This API manages paid marketing campaigns created by providers or admins to promote trips.

Creating ad campaigns linked to specific trips
Setting budget, duration, and scheduling
Processing upfront payments
Tracking spend vs budget
Managing status (نشطة / مجدولة / متوقفة / منتهية)
Listing and filtering campaigns

This API powers the full UI of إدارة الإعلانات in the Provider Portal & Admin Panel.

2. Ad Campaign Lifecycle

UI Arabic Label → Enum mapping:

Arabic UI Label	Internal Enum	Description
نشطة	ACTIVE	Campaign is running during the date range
مجدولة	SCHEDULED	Campaign created but start date is in the future
متوقفة	PAUSED	Manually paused by admin/provider
منتهية	ENDED	Campaign reached end date or budget is fully consumed

Allowed transitions:

SCHEDULED → ACTIVE (automatically when start_date arrives)
ACTIVE → ENDED (automatically when end_date passes or budget is fully spent)
ACTIVE → PAUSED (manual)
PAUSED → ACTIVE (manual)
Any → ENDED (forced by admin)

3. Endpoints

All endpoints follow the general rules in api-principles-and-versioning.md (pagination, errors, auth).

3.1 List Ad Campaigns (Provider)

GET/api/v1/provider/ad-campaigns

Auth: Provider Admin / Provider Staff

Parameter	Description
search	Optional free-text search (trip name, campaign name)
status	One of: ACTIVE, SCHEDULED, PAUSED, ENDED
trip_id	Filter by specific trip

3.1.1 List Ad Campaigns (Admin)

GET/api/v1/admin/ad-campaigns

Same filters and response shape as the provider endpoint, but across all providers.

3.2 Create Ad Campaign (Provider)

POST/api/v1/provider/ad-campaigns

Matches UI modal "إنشاء حملة إعلانية".

Payment is always upfront.
VAT is shown as 20% in the UI; this conflicts with the general 15% VAT assumption and is explicitly tracked in open-questions-and-assumptions.md.

3.3 Update Campaign (Provider)

PUT/api/v1/provider/ad-campaigns/{id}

Updates are allowed only before the campaign starts (i.e. while status = SCHEDULED).

If status != SCHEDULED → returns CAMPAIGN_NOT_EDITABLE error.

3.4 Change Campaign Status

POST/api/v1/provider/ad-campaigns/{id}/pause

Pause

POST/api/v1/provider/ad-campaigns/{id}/resume

Activate (Resume)

POST/api/v1/admin/ad-campaigns/{id}/end

Force End (Admin only)

3.5 Delete Campaign (Provider)

DELETE/api/v1/provider/ad-campaigns/{id}

Matches UI modal "حذف الحملة الإعلانية!".

Rules:

Only allowed if status IN (SCHEDULED, PAUSED)
Campaign must not have started or spent any money

4. Billing & Payment API (for Ad Campaigns)

Actual payment integrations are described in integrations-hyperpay-stcpay-mada-applepay-maps-sms-email.md. This section focuses on the campaign-specific payment flows.

4.1 Initiate Payment Session

POST/api/v1/payments/ad-campaigns/session

Used internally when creating a paid campaign.

4.2 Payment Callback

POST/api/v1/payments/ad-campaigns/callback

Payment provider → system notification.

System must update:

Payment status
Campaign record
Financial reports (see payments-and-financials-api.md)

5. Spend Tracking API (Internal)

Triggered by periodic cron (Node.js scheduled jobs).

POST/api/v1/internal/ad-campaigns/update-spend

Logic (current phase):

Pull spend data (manually simulated for now)
Update spent amount
If spent ≥ budget → auto-end campaign (status = ENDED)

6. Validation Rules

VR-1Date Range

start_date < end_date. Duration must be a positive number of days.

VR-2Trip Ownership

Provider can only create campaigns for their own trips.

VR-3Budget Minimum

UI slider minimum must match backend: minimum 100 SAR.

VR-4Payment Required

Campaign cannot be saved/activated unless payment succeeds.

7. Error Cases

EC-1Overlapping Campaign

TRIP_ALREADY_HAS_ACTIVE_CAMPAIGN

EC-2Invalid Payment Method

UNSUPPORTED_PAYMENT_METHOD

EC-3VAT Mismatch

VAT_RATE_INCONSISTENT_WITH_SYSTEM

VAT discrepancy is flagged but allowed (pending final business decision)

8. Permissions Summary (High-Level)

Action	Provider Admin	Provider Staff	Admin	Super Admin
Create campaign	✔️	✔️	✔️	✔️
Update campaign	✔️	✔️	✔️	✔️
Pause/resume campaign	✔️	✔️	✔️	✔️
Delete campaign	✔️	✔️	✔️	✔️
Force end campaign	❌	❌	✔️	✔️
View all providers' campaigns	❌	❌	✔️	✔️

Full details in 08-rbac/roles-and-permissions-matrix.md