A Comprehensive Guide

API Documentation for Quantum sponsored product Ads

Introduction

The Quantum API provides a comprehensive suite of tools to manage and operate sponsored product listing campaigns. These APIs allow you to:

Create, manage, and delete sponsored product listing campaigns.
Generate detailed reports, including impressions, clicks, and conversions.
Implement advanced targeting using demographic and geographic filters.
Retrieve available ad inventory and place bids for product listings.

Note: The APIs for sponsored product listings are identical to those for other ad types. However, the responsibility for displaying the sponsored products within the partner’s e-commerce platform lies with the partner’s implementation.

This documentation is structured to ensure a seamless integration experience for developers.

Base URL

All API requests should be directed to the following base URL:

				
					https://api.engine.quantums.com.sa/

Authentication

Quantum API requires an API key for authentication. Include the key in the headers of each request:

				
					Authorization: Bearer YOUR_API_KEY

Contact support to obtain your API key.

Campaign Management APIs

List Campaigns

Endpoint: GET /campaigns

Description: Retrieve a paginated list of sponsored product listing campaigns.

Parameters:

Parameter	Type	Location	Required	Description
skip	integer	query	Yes	Number of records to skip.
take	integer	query	Yes	Number of records to retrieve.

Response:

200 OK: Returns an array of campaigns with their metadata.

Example Request:

				
					curl -X GET "https://api.engine.quantums.com.sa/campaigns?skip=0&take=10" \
-H "Authorization: Bearer YOUR_API_KEY"

Expected Response:

				
					[
  {
    "id": "92de7c0d-ecba-4f27-b014-a997a2110291",
    "name": "Holiday Sponsored Products",
    "dailyBudget": 2000,
    "totalBudget": 30000,
    "impressionBid": 15,
    "status": "Active"
  }
]

Create Campaign

Endpoint: POST /campaigns
Description: Create a new sponsored product listing campaign with specified parameters.
Request Body (JSON):

				
					{
  "name": "Campaign Name",
  "dailyBudget": 1500,
  "totalBudget": 15000,
  "impressionBid": 10,
  "startAt": "2024-12-01T00:00:00Z",
  "endAt": "2024-12-31T23:59:59Z",
  "notificationUri": "https://example.com/notify",
  "tags": [["category:electronics", "region:ksa"]],
  "description": "Promoting top electronics in KSA",
  "productList": [
    "product1-id",
    "product2-id"
  ]
}

Field	Type	Required	Description
name	string	Yes	The name of the campaign.
dailyBudget	number	Yes	The daily budget allocated for the campaign.
totalBudget	number	Yes	The total budget for the campaign.
impressionBid	number	Yes	The cost-per-impression bid amount.
startAt	string	Yes	The start date and time of the campaign (ISO 8601).
endAt	string	Yes	The end date and time of the campaign (ISO 8601).
notificationUri	string	Yes	URI for receiving campaign notifications.
tags	array	No	Tags for campaign targeting criteria.
description	string	No	Description of the campaign.
productList	array	Yes	List of product IDs to be included in the campaign.

Response:

200 OK: Returns details of the newly created campaign, including its unique identifier.

Example Request:

				
					curl -X POST "http://localhost:5068/campaigns" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
  "name": "Holiday Sponsored Products",
  "dailyBudget": 2000,
  "totalBudget": 30000,
  "impressionBid": 15,
  "startAt": "2024-12-01T00:00:00Z",
  "endAt": "2024-12-31T23:59:59Z",
  "tags": [["category:electronics", "region:ksa"]],
  "description": "Promoting top electronics in KSA",
  "productList": ["product1-id", "product2-id"]
}'

Expected Response:

				
					{
  "id": "92de7c0d-ecba-4f27-b014-a997a2110291",
  "name": "Holiday Sponsored Products",
  "dailyBudget": 2000,
  "totalBudget": 30000,
  "impressionBid": 15,
  "status": "Active",
  "tags": [["category:electronics", "region:ksa"]],
  "description": "Promoting top electronics in KSA",
  "productList": ["product1-id", "product2-id"],
  "startAt": "2024-12-01T00:00:00Z",
  "endAt": "2024-12-31T23:59:59Z"
}

Generate Campaign Reports

Endpoint: POST /reports
Description: Generate a detailed report for a campaign, providing metrics such as impressions, clicks, and conversions.
Request Body (JSON):

				
					{
  "from": "2024-12-01T00:00:00Z",
  "to": "2024-12-15T23:59:59Z",
  "campaignId": "92de7c0d-ecba-4f27-b014-a997a2110291",
  "groupBy": "category"
}

Field	Type	Required	Description
from	string	Yes	The start date and time for the report (ISO 8601).
to	string	Yes	The end date and time for the report (ISO 8601).
campaignId	UUID	Yes	Unique identifier of the campaign.
groupBy	string	No	The tag used for grouping results.

Response:

200 OK: Returns a JSON report grouped by specified criteria, such as region.

Example Request:

				
					curl -X POST "http://localhost:5068/reports" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
  "from": "2024-12-01T00:00:00Z",
  "to": "2024-12-15T23:59:59Z",
  "campaignId": "92de7c0d-ecba-4f27-b014-a997a2110291",
  "groupBy": "category"
}'

Expected Response:

				
					{
  "reportBuckets": [
    {
      "from": "2024-12-01T00:00:00Z",
      "to": "2024-12-02T00:00:00Z",
      "dataPoints": {
        "category:electronics": {
          "impressionsCount": 500,
          "clicks": 50,
          "addToCart": 10
        }
      }
    }
  ],
  "totalDataPoint": {
    "impressionsCount": 500,
    "clicks": 50,
    "addToCart": 10
  }
}

Schemas

Campaign Response

Field	Type	Description
id	UUID	Unique identifier for the campaign.
name	string	Name of the campaign.
dailyBudget	number	Daily budget allocated to the campaign.
totalBudget	number	Total budget allocated to the campaign.
impressionBid	number	Cost-per-impression bid.
status	string	Status of the campaign (e.g., Active, Paused).
tags	array	Targeting criteria tags.
productList	array	List of products included in the campaign.

Cross-Sell and Upsell Ads

Cross-sell and upsell ads are specialized forms of sponsored product listings that promote complementary or higher-value products. This section explains how to configure campaigns for cross-sell and upsell opportunities using Quantum API, with detailed instructions, configurations, and expected responses.

Cross-Sell Ads

Objective: Promote products related to the primary purchase. For example, promoting headphones with a mobile phone.

How It Works:

Cross-sell campaigns rely on associating complementary products with the primary product. These associations are defined through tags and productList configurations.

Configuration Details:

Field	Type	Required	Description
name	string	Yes	Name of the cross-sell campaign.
dailyBudget	number	Yes	Daily budget allocated for the campaign.
totalBudget	number	Yes	Total budget for the campaign.
impressionBid	number	Yes	Cost-per-impression bid amount.
startAt	string	Yes	Start date and time for the campaign (ISO 8601).
endAt	string	Yes	End date and time for the campaign (ISO 8601).
tags	array	Yes	Tags to associate products and targeting filters.
description	string	No	Description of the campaign objective.
productList	array	Yes	List of complementary product IDs.

Example Request:

				
					curl -X POST "http://localhost:5068/campaigns" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
  "name": "Cross-Sell Campaign",
  "dailyBudget": 1500,
  "totalBudget": 20000,
  "impressionBid": 8,
  "startAt": "2024-12-01T00:00:00Z",
  "endAt": "2024-12-31T23:59:59Z",
  "tags": [["category:electronics", "region:ksa"]],
  "description": "Promoting accessories for electronics buyers",
  "productList": ["product-headphone-id", "product-case-id"]
}'

Expected Response:

				
					{
  "id": "c1f27c2e-b1e4-4e6b-8d1a-9086e7d7d9b9",
  "name": "Cross-Sell Campaign",
  "dailyBudget": 1500,
  "totalBudget": 20000,
  "impressionBid": 8,
  "status": "Active",
  "tags": [["category:electronics", "region:ksa"]],
  "description": "Promoting accessories for electronics buyers",
  "productList": ["product-headphone-id", "product-case-id"],
  "startAt": "2024-12-01T00:00:00Z",
  "endAt": "2024-12-31T23:59:59Z"
}

Upsell Ads

Objective: Encourage customers to upgrade to higher-value products. For example, promoting a premium laptop to users viewing an entry-level laptop.

How It Works:

Upsell campaigns highlight higher-value products by targeting customers already interacting with similar but lower-tier items. Tags and product lists are configured to define these relationships.

Configuration Details:

Field	Type	Required	Description
name	string	Yes	Name of the upsell campaign.
dailyBudget	number	Yes	Daily budget allocated for the campaign.
totalBudget	number	Yes	Total budget for the campaign.
impressionBid	number	Yes	Cost-per-impression bid amount.
startAt	string	Yes	Start date and time for the campaign (ISO 8601).
endAt	string	Yes	End date and time for the campaign (ISO 8601).
tags	array	Yes	Tags to associate products and targeting filters.
description	string	No	Description of the campaign objective.
productList	array	Yes	List of higher-value product IDs.

Example Request:

				
					curl -X POST "http://localhost:5068/campaigns" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
  "name": "Upsell Campaign",
  "dailyBudget": 2000,
  "totalBudget": 25000,
  "impressionBid": 10,
  "startAt": "2024-12-01T00:00:00Z",
  "endAt": "2024-12-31T23:59:59Z",
  "tags": [["category:premium-electronics", "region:ksa"]],
  "description": "Upselling premium laptops to buyers of entry-level laptops",
  "productList": ["product-premium-laptop-id"]
}'

Expected Response:

				
					{
  "id": "d3b17e7c-8b2e-4c7d-ae65-d2b5f4c7a5b1",
  "name": "Upsell Campaign",
  "dailyBudget": 2000,
  "totalBudget": 25000,
  "impressionBid": 10,
  "status": "Active",
  "tags": [["category:premium-electronics", "region:ksa"]],
  "description": "Upselling premium laptops to buyers of entry-level laptops",
  "productList": ["product-premium-laptop-id"],
  "startAt": "2024-12-01T00:00:00Z",
  "endAt": "2024-12-31T23:59:59Z"
}

Best Practices for Cross-Sell and Upsell Ads

Define Complementary Relationships: Use meaningful tags and productList entries to ensure relevancy.
Target Segments Strategically: Configure tags to align with specific user behaviors, categories, or regions.
Monitor Performance: Regularly analyze campaign reports to optimize for better click-through and conversion rates.
Dynamic Updates: Keep the productList updated with new or trending products to maintain user engagement.