Skip to main content

Advertisement Management

6 API calls in this section.

List Advertisements​

Storefront & Commerce / Advertisement Management
GET/storefront/advertisements

Retrieves advertisements for the tenant's market with advanced filtering and pagination. Only accessible by tenant administrators for advertisement management.

  • Required: Valid Bearer token with tenant admin permissions

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

Query parameters

ParameterTypeDescription
pageOptionalstring

Page number for pagination (default: 1)

Example: 1

limitOptionalstring

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

Example: 20

placementOptionalstring

Filter by ad placement location (banner, sidebar, popup, etc.)

Example: banner

is_activeOptionalstring

Filter by active status (true/false)

Example: true

searchOptionalstring

Search advertisements by title or description content

Example: summer sale

include_expiredOptionalstring

Include expired advertisements (default: false)

Example: false

Headers

ParameterTypeDescription
AuthorizationRequiredstring

JWT token for tenant admin users (required)

Example: Bearer {{access_token}}

Staging
Request
curl
1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/storefront/advertisements?page=1&limit=20&placement=banner&is_active=true&search=summer sale&include_expired=false" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}"

Response examples

200OK
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}

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.

  • 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

Headers

ParameterTypeDescription
AuthorizationRequiredstring

JWT token for tenant admin users (required)

Example: Bearer {{access_token}}

Content-Typestring

Example: application/json

Body parameters

ParameterTypeDescription
typestring—
placementstring—
titleobject—
title.enstring—
title.arstring—
title.kustring—
contentobject—
content.enstring—
content.arstring—
content.kustring—
image_urlstring—
link_urlstring—
Show 7 more body fields

Additional body parameters

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

Response examples

201Created
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}

Get Advertisement Details​

Storefront & Commerce / Advertisement Management
GET/storefront/advertisements/{{advertisement_id}}

Retrieves detailed information about a specific advertisement including analytics data.

  • Required: Valid Bearer token with tenant admin permissions

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

Path parameters

ParameterTypeDescription
advertisement_idRequiredstring

UUID of the advertisement to retrieve

Headers

ParameterTypeDescription
AuthorizationRequiredstring

JWT token for tenant admin users (required)

Example: Bearer {{access_token}}

Staging
Request
curl
1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/storefront/advertisements/${ADVERTISEMENT_ID}" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}"

Response examples

200OK
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}

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.

  • Required: Valid Bearer token with tenant admin permissions

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

Path parameters

ParameterTypeDescription
advertisement_idRequiredstring

UUID of the advertisement to update

Headers

ParameterTypeDescription
AuthorizationRequiredstring

JWT token for tenant admin users (required)

Example: Bearer {{access_token}}

Content-Typestring

Example: application/json

Body parameters

ParameterTypeDescription
titleobject—
title.enstring—
title.arstring—
title.kustring—
is_activeboolean—
prioritynumber—
end_datestring—
Staging
Request
curl
1curl --globoff --request PUT "https://staging-api.ondi.io/functions/v1/storefront/advertisements/${ADVERTISEMENT_ID}" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "Content-Type: application/json" \4  --data-raw '{5  "title": {6    "en": "Updated Sale Title",7    "ar": "عنوان التخفيضات المحدث",8    "ku": "ناونیشانی فرۆشتنی نوێکراوە"9  },10  "is_active": false,11  "priority": 15,12  "end_date": "2024-12-31T23:59:59Z"13}'

Response examples

200OK
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.

  • Required: Valid Bearer token with tenant admin permissions

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

Path parameters

ParameterTypeDescription
advertisement_idRequiredstring

UUID of the advertisement to delete

Headers

ParameterTypeDescription
AuthorizationRequiredstring

JWT token for tenant admin users (required)

Example: Bearer {{access_token}}

Staging
Request
curl
1curl --globoff --request DELETE "https://staging-api.ondi.io/functions/v1/storefront/advertisements/${ADVERTISEMENT_ID}" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}"

Response examples

200OK
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

Retrieves detailed analytics data for a specific advertisement with optional date range filtering.

  • Required: Valid Bearer token with tenant admin permissions

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

Path parameters

ParameterTypeDescription
advertisement_idRequiredstring

UUID of the advertisement

Query parameters

ParameterTypeDescription
start_dateOptionalstring

Start date for analytics data (ISO format) Start date for analytics (ISO format)

Example: 2024-07-01

end_dateOptionalstring

End date for analytics data (ISO format) End date for analytics (ISO format)

Example: 2024-07-31

Headers

ParameterTypeDescription
AuthorizationRequiredstring

JWT token for tenant admin users (required)

Example: Bearer {{access_token}}

Staging
Request
curl
1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/storefront/advertisements/${ADVERTISEMENT_ID}/analytics?start_date=2024-07-01&end_date=2024-07-31" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}"

Response examples

200OK
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}