Advertisement Management

6 API calls in this section.

List Advertisements

Storefront & Commerce / Advertisement Management

GET/storefront/advertisements?page=1&limit=20&placement=banner&is_active=true&search=summer sale&include_expired=false

Retrieves advertisements for the tenant's market with advanced filtering and pagination. Only accessible by tenant administrators for advertisement management. Authentication: - Required: Valid Bearer token with tenant admin permissions Query Parameters: - page (optional): Page number for pagination (default: 1) - limit (optional): Items per page (default: 20, max: 100) - placement (optional): Filter by ad placement location (banner, sidebar, popup, etc.) - is_active (optional): Filter by active status (true/false) - search (optional): Search advertisements by title or description content - include_expired (optional): Include expired advertisements (default: false) Search & Filter Features: - Content Search: Find advertisements by title or description text - Placement Filtering: Filter by specific ad placement locations - Status Filtering: Filter by active/inactive status - Expiration Filtering: Include or exclude expired advertisements - Combination Filters: Use multiple filters together for precise results Features: - Admin-only access for advertisement management - Advanced search and filtering capabilities - Placement-based filtering for targeted management - Status-based filtering for workflow management - Content-based search for quick finding - Expiration filtering for cleanup workflows - Paginated results for large advertisement volumes - Complete advertisement details with targeting info Response Data: - Complete advertisement details with content - Placement and targeting information - Active status and expiration dates - Performance metrics and analytics - Creation and modification timestamps Use Cases: - Advertisement management dashboard - Campaign management workflows - Content moderation and review - Performance analysis and optimization - Bulk advertisement operations - Placement-specific management - Expired advertisement cleanup

Send a bearer token in the Authorization header for an authenticated OnDi user session.

Request

curl

1curl --request GET "$ONDI_BASE_URL/storefront/advertisements?page=1&limit=20&placement=banner&is_active=true&search=summer sale&include_expired=false" \2  --header "Authorization: Bearer {{access_token}}"

Query parameters

pageOptional

query string

1

Page number for pagination (default: 1)

limitOptional

query string

20

Items per page (default: 20, max: 100)

placementOptional

query string

banner

Filter by ad placement location

is_activeOptional

query string

true

Filter by active status (true/false)

searchOptional

query string

summer sale

Search advertisements by title or description

include_expiredOptional

query string

false

Include expired advertisements (default: false)

Headers

AuthorizationOptional

header string

Bearer {{access_token}}

JWT token for tenant admin users (required)

Responses

Success - Advertisements List200OK

Response body

json

1{2  "success": true,3  "data": {4    "advertisements": [5      {6        "id": "ad-uuid-1",7        "market_id": "market-uuid",8        "title": {9          "en": "Summer Sale 2024",10          "ar": "تخفيضات الصيف 2024",11          "ku": "فرۆشتنی هاوینی 2024"12        },13        "description": {14          "en": "Get up to 50% off on all summer items",15          "ar": "احصل على خصم يصل إلى 50% على جميع العناصر الصيفية",16          "ku": "تا 50% داشکاندن لەسەر هەموو بابەتەکانی هاوین"17        },18        "placement": "banner",19        "ad_type": "image",20        "content_url": "https://example.com/summer-sale-banner.jpg",21        "target_url": "/categories/summer-collection",22        "is_active": true,23        "start_date": "2024-06-01T00:00:00Z",24        "end_date": "2024-08-31T23:59:59Z",25        "priority": 10,26        "created_at": "2024-05-15T10:00:00Z",27        "updated_at": "2024-05-15T10:00:00Z"28      }29    ],30    "pagination": {31      "page": 1,32      "limit": 20,33      "total": 1,34      "totalPages": 135    }36  }37}

Success - No Advertisements Found200OK

Response body

json

1{2  "success": true,3  "data": {4    "advertisements": [],5    "pagination": {6      "page": 1,7      "limit": 20,8      "total": 0,9      "totalPages": 010    }11  }12}

Error - Unauthorized401Unauthorized

Response body

json

1{2  "success": false,3  "message": "Tenant required"4}

Error - Market Not Found404Not Found

Response body

json

1{2  "success": false,3  "message": "Market not found"4}

Create Advertisement

Storefront & Commerce / Advertisement Management

POST/storefront/advertisements

Creates a new advertisement for the tenant's market. Supports multi-language content and advanced targeting options. Authentication: - Required: Valid Bearer token with tenant admin permissions Required Fields: - type: Advertisement type (banner, sidebar, popup, inline) - placement: Where to display (home, category, product, checkout, global) - title: Multi-language title object - content: Multi-language content object Optional Fields: - image_url: Advertisement image URL - link_url: Target URL when clicked - is_active: Active status (default: true) - start_date: When to start showing - end_date: When to stop showing - targeting_rules: Demographic targeting - priority: Display priority (higher = shown first) Features: - Multi-language support (en, ar, ku) - Scheduled campaigns with start/end dates - Priority-based display ordering - Demographic targeting rules - Flexible placement options - Immediate activation control

Send a bearer token in the Authorization header for an authenticated OnDi user session.

Request

curl

1curl --request POST "$ONDI_BASE_URL/storefront/advertisements" \2  --header "Authorization: Bearer {{access_token}}" \3  --header "Content-Type: application/json" \4  --header "Content-Type: application/json" \5  --data '{6  "type": "banner",7  "placement": "home",8  "title": {9    "en": "Black Friday Sale",10    "ar": "تخفيضات الجمعة السوداء",11    "ku": "فرۆشتنی جەژنی ڕەش"12  },13  "content": {14    "en": "Massive discounts on all products",15    "ar": "خصومات هائلة على جميع المنتجات",16    "ku": "داشکاندنی گەورە لەسەر هەموو بەرهەمەکان"17  },18  "image_url": "https://example.com/black-friday-banner.jpg",19  "link_url": "/sales/black-friday",20  "is_active": true,21  "start_date": "2024-11-25T00:00:00Z",22  "end_date": "2024-11-30T23:59:59Z",23  "targeting_rules": {24    "demographics": [25      "18-35"26    ],27    "interests": [28      "fashion",29      "electronics"30    ]31  },32  "priority": 533}'

Request body

json

1{2  "type": "banner",3  "placement": "home",4  "title": {5    "en": "Black Friday Sale",6    "ar": "تخفيضات الجمعة السوداء",7    "ku": "فرۆشتنی جەژنی ڕەش"8  },9  "content": {10    "en": "Massive discounts on all products",11    "ar": "خصومات هائلة على جميع المنتجات",12    "ku": "داشکاندنی گەورە لەسەر هەموو بەرهەمەکان"13  },14  "image_url": "https://example.com/black-friday-banner.jpg",15  "link_url": "/sales/black-friday",16  "is_active": true,17  "start_date": "2024-11-25T00:00:00Z",18  "end_date": "2024-11-30T23:59:59Z",19  "targeting_rules": {20    "demographics": [21      "18-35"22    ],23    "interests": [24      "fashion",25      "electronics"26    ]27  },28  "priority": 529}

Request body fields

typeExample

string

Example field from the request body.

placementExample

string

Example field from the request body.

titleExample

object

Example field from the request body.

title.enExample

string

Example field from the request body.

title.arExample

string

Example field from the request body.

title.kuExample

string

Example field from the request body.

contentExample

object

Example field from the request body.

content.enExample

string

Example field from the request body.

content.arExample

string

Example field from the request body.

content.kuExample

string

Example field from the request body.

image_urlExample

string

Example field from the request body.

link_urlExample

string

Example field from the request body.

is_activeExample

boolean

Example field from the request body.

start_dateExample

string

Example field from the request body.

end_dateExample

string

Example field from the request body.

targeting_rulesExample

object

Example field from the request body.

targeting_rules.demographicsExample

array<string>

Example field from the request body.

targeting_rules.interestsExample

array<string>

Example field from the request body.

priorityExample

number

Example field from the request body.

Headers

AuthorizationOptional

header string

Bearer {{access_token}}

JWT token for tenant admin users (required)

Content-TypeOptional

header string

application/json

Responses

Success - Advertisement Created201Created

Response body

json

1{2  "success": true,3  "advertisement": {4    "id": "new-ad-uuid",5    "market_id": "market-uuid",6    "type": "banner",7    "placement": "home",8    "title": {9      "en": "Black Friday Sale",10      "ar": "تخفيضات الجمعة السوداء",11      "ku": "فرۆشتنی جەژنی ڕەش"12    },13    "content": {14      "en": "Massive discounts on all products",15      "ar": "خصومات هائلة على جميع المنتجات",16      "ku": "داشکاندنی گەورە لەسەر هەموو بەرهەمەکان"17    },18    "image_url": "https://example.com/black-friday-banner.jpg",19    "link_url": "/sales/black-friday",20    "is_active": true,21    "start_date": "2024-11-25T00:00:00Z",22    "end_date": "2024-11-30T23:59:59Z",23    "targeting_rules": {24      "demographics": [25        "18-35"26      ],27      "interests": [28        "fashion",29        "electronics"30      ]31    },32    "priority": 5,33    "is_currently_active": false,34    "created_at": "2024-07-20T10:00:00Z",35    "updated_at": "2024-07-20T10:00:00Z"36  },37  "message": "Advertisement created successfully"38}

Error - Validation Failed400Bad Request

Response body

json

1{2  "success": false,3  "message": "Validation failed",4  "errors": [5    {6      "field": "type",7      "message": "Type is required"8    },9    {10      "field": "title",11      "message": "Title is required"12    }13  ]14}

Get Advertisement Details

Storefront & Commerce / Advertisement Management

GET/storefront/advertisements/{{advertisement_id}}

Retrieves detailed information about a specific advertisement including analytics data. Authentication: - Required: Valid Bearer token with tenant admin permissions Path Parameters: - advertisement_id: UUID of the advertisement to retrieve Response Data: - Complete advertisement details - Analytics summary (views, clicks, CTR) - Market information - Current active status - Scheduling information Use Cases: - Advertisement editing workflows - Performance monitoring - Content review and approval - Analytics dashboard details

Send a bearer token in the Authorization header for an authenticated OnDi user session.

Request

curl

1curl --request GET "$ONDI_BASE_URL/storefront/advertisements/{{advertisement_id}}" \2  --header "Authorization: Bearer {{access_token}}"

Path parameters

advertisement_idRequired

path string

Variable used inside the request path.

Headers

AuthorizationOptional

header string

Bearer {{access_token}}

JWT token for tenant admin users (required)

Responses

Success - Advertisement Details200OK

Response body

json

1{2  "success": true,3  "advertisement": {4    "id": "ad-uuid",5    "market_id": "market-uuid",6    "type": "banner",7    "placement": "home",8    "title": {9      "en": "Summer Sale 2024",10      "ar": "تخفيضات الصيف 2024",11      "ku": "فرۆشتنی هاوینی 2024"12    },13    "content": {14      "en": "Get up to 50% off on all summer items",15      "ar": "احصل على خصم يصل إلى 50% على جميع العناصر الصيفية",16      "ku": "تا 50% داشکاندن لەسەر هەموو بابەتەکانی هاوین"17    },18    "image_url": "https://example.com/summer-sale-banner.jpg",19    "link_url": "/categories/summer-collection",20    "is_active": true,21    "start_date": "2024-06-01T00:00:00Z",22    "end_date": "2024-08-31T23:59:59Z",23    "targeting_rules": {},24    "priority": 10,25    "is_currently_active": true,26    "created_at": "2024-05-15T10:00:00Z",27    "updated_at": "2024-05-15T10:00:00Z",28    "market": {29      "store_name": "my-store"30    },31    "analytics": {32      "total_views": 1250,33      "total_clicks": 85,34      "click_through_rate": 6.835    }36  }37}

Error - Advertisement Not Found404Not Found

Response body

json

1{2  "success": false,3  "message": "Advertisement not found"4}

Update Advertisement

Storefront & Commerce / Advertisement Management

PUT/storefront/advertisements/{{advertisement_id}}

Updates an existing advertisement. All fields are optional - only provided fields will be updated. Authentication: - Required: Valid Bearer token with tenant admin permissions Path Parameters: - advertisement_id: UUID of the advertisement to update Updatable Fields: - type: Change advertisement type - placement: Change placement location - title: Update multi-language titles - content: Update multi-language content - image_url: Change advertisement image - link_url: Update target URL - is_active: Enable/disable advertisement - start_date: Modify start scheduling - end_date: Modify end scheduling - targeting_rules: Update targeting criteria - priority: Change display priority Features: - Partial updates (only send changed fields) - Multi-language content updates - Schedule modifications - Priority adjustments - Instant activation control

Send a bearer token in the Authorization header for an authenticated OnDi user session.

Request

curl

1curl --request PUT "$ONDI_BASE_URL/storefront/advertisements/{{advertisement_id}}" \2  --header "Authorization: Bearer {{access_token}}" \3  --header "Content-Type: application/json" \4  --header "Content-Type: application/json" \5  --data '{6  "title": {7    "en": "Updated Sale Title",8    "ar": "عنوان التخفيضات المحدث",9    "ku": "ناونیشانی فرۆشتنی نوێکراوە"10  },11  "is_active": false,12  "priority": 15,13  "end_date": "2024-12-31T23:59:59Z"14}'

Request body

json

1{2  "title": {3    "en": "Updated Sale Title",4    "ar": "عنوان التخفيضات المحدث",5    "ku": "ناونیشانی فرۆشتنی نوێکراوە"6  },7  "is_active": false,8  "priority": 15,9  "end_date": "2024-12-31T23:59:59Z"10}

Path parameters

advertisement_idRequired

path string

Variable used inside the request path.

Request body fields

titleExample

object

Example field from the request body.

title.enExample

string

Example field from the request body.

title.arExample

string

Example field from the request body.

title.kuExample

string

Example field from the request body.

is_activeExample

boolean

Example field from the request body.

priorityExample

number

Example field from the request body.

end_dateExample

string

Example field from the request body.

Headers

AuthorizationOptional

header string

Bearer {{access_token}}

JWT token for tenant admin users (required)

Content-TypeOptional

header string

application/json

Responses

Success - Advertisement Updated200OK

Response body

json

1{2  "success": true,3  "advertisement": {4    "id": "ad-uuid",5    "market_id": "market-uuid",6    "type": "banner",7    "placement": "home",8    "title": {9      "en": "Updated Sale Title",10      "ar": "عنوان التخفيضات المحدث",11      "ku": "ناونیشانی فرۆشتنی نوێکراوە"12    },13    "content": {14      "en": "Get up to 50% off on all summer items",15      "ar": "احصل على خصم يصل إلى 50% على جميع العناصر الصيفية",16      "ku": "تا 50% داشکاندن لەسەر هەموو بابەتەکانی هاوین"17    },18    "image_url": "https://example.com/summer-sale-banner.jpg",19    "link_url": "/categories/summer-collection",20    "is_active": false,21    "start_date": "2024-06-01T00:00:00Z",22    "end_date": "2024-12-31T23:59:59Z",23    "targeting_rules": {},24    "priority": 15,25    "is_currently_active": false,26    "created_at": "2024-05-15T10:00:00Z",27    "updated_at": "2024-07-20T11:00:00Z"28  },29  "message": "Advertisement updated successfully"30}

Delete Advertisement

Storefront & Commerce / Advertisement Management

DELETE/storefront/advertisements/{{advertisement_id}}

Permanently deletes an advertisement and all associated analytics data. Authentication: - Required: Valid Bearer token with tenant admin permissions Path Parameters: - advertisement_id: UUID of the advertisement to delete Important Notes: - This action is irreversible - All analytics data will be lost - Advertisement will be immediately removed from all placements - Consider deactivating instead of deleting for data retention Use Cases: - Cleanup of test advertisements - Removal of inappropriate content - Campaign end-of-life management - Database maintenance

Send a bearer token in the Authorization header for an authenticated OnDi user session.

Request

curl

1curl --request DELETE "$ONDI_BASE_URL/storefront/advertisements/{{advertisement_id}}" \2  --header "Authorization: Bearer {{access_token}}"

Path parameters

advertisement_idRequired

path string

Variable used inside the request path.

Headers

AuthorizationOptional

header string

Bearer {{access_token}}

JWT token for tenant admin users (required)

Responses

Success - Advertisement Deleted200OK

Response body

json

1{2  "success": true,3  "message": "Advertisement deleted successfully"4}

Get Advertisement Analytics

Storefront & Commerce / Advertisement Management

GET/storefront/advertisements/{{advertisement_id}}/analytics?start_date=2024-07-01&end_date=2024-07-31

Retrieves detailed analytics data for a specific advertisement with optional date range filtering. Authentication: - Required: Valid Bearer token with tenant admin permissions Path Parameters: - advertisement_id: UUID of the advertisement Query Parameters: - start_date (optional): Start date for analytics (ISO format) - end_date (optional): End date for analytics (ISO format) Analytics Metrics: - Total views and clicks - Click-through rate (CTR) - Daily breakdown data - Impression counts - Performance trends Features: - Date range filtering - Daily granular data - Calculated performance metrics - Historical trend analysis - Export-ready data format Use Cases: - Campaign performance review - ROI analysis and reporting - A/B testing comparisons - Optimization insights - Executive dashboards

Send a bearer token in the Authorization header for an authenticated OnDi user session.

Request

curl

1curl --request GET "$ONDI_BASE_URL/storefront/advertisements/{{advertisement_id}}/analytics?start_date=2024-07-01&end_date=2024-07-31" \2  --header "Authorization: Bearer {{access_token}}"

Path parameters

advertisement_idRequired

path string

Variable used inside the request path.

Query parameters

start_dateOptional

query string

2024-07-01

Start date for analytics data (ISO format)

end_dateOptional

query string

2024-07-31

End date for analytics data (ISO format)

Headers

AuthorizationOptional

header string

Bearer {{access_token}}

JWT token for tenant admin users (required)

Responses

Success - Analytics Data200OK

Response body

json

1{2  "success": true,3  "advertisement_id": "ad-uuid",4  "analytics": {5    "totalViews": 1250,6    "totalClicks": 85,7    "totalImpressions": 1500,8    "clickThroughRate": 6.8,9    "dailyData": [10      {11        "date": "2024-07-01",12        "views": 45,13        "clicks": 3,14        "impressions": 6015      },16      {17        "date": "2024-07-02",18        "views": 52,19        "clicks": 4,20        "impressions": 6521      },22      {23        "date": "2024-07-03",24        "views": 38,25        "clicks": 2,26        "impressions": 4827      }28    ]29  },30  "period": "2024-07-01_to_2024-07-31"31}