Placements API

curl https://api.mazeedplus.com/select-placement \
  -H "x-publishable-api-key: pk_live_51H7..." \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "checkout_success",
    "attributes": {
      "userId": "user_123456789",
      "mobile": "+966501234567",
      "currency": "sar",
      "country": "sa",
      "firstname": "Ahmed",
      "lastname": "Ali",
      "interests": ["technology", "gaming", "brand:Nike", "brand:Apple"],
      "q": "كولومبي قهوه"
    }
  }'

const response = await fetch("https://api.mazeedplus.com/select-placement", {
  method: "POST",
  headers: {
    "x-publishable-api-key": "pk_live_51H7...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    identifier: "checkout_success",
    attributes: {
      userId: "user_123456789",
      mobile: "+966501234567",
      currency: "sar",
      country: "sa",
      firstname: "Ahmed",
      lastname: "Ali",
      interests: ["technology", "gaming", "brand:Nike", "brand:Apple"],
      q: "كولومبي قهوه",
    },
  }),
});

const placement = await response.json();

import requests

response = requests.post(
    "https://api.mazeedplus.com/select-placement",
    headers={
        "x-publishable-api-key": "pk_live_51H7...",
        "Content-Type": "application/json"
    },
    json={
        "identifier": "checkout_success",
        "attributes": {
            "userId": "user_123456789",
            "mobile": "+966501234567",
            "currency": "sar",
            "country": "sa",
            "firstname": "Ahmed",
            "lastname": "Ali",
            "interests": ["technology", "gaming", "brand:Nike", "brand:Apple"],
            "q": "كولومبي قهوه"
        }
    }
)

placement = response.json()

<?php
$ch = curl_init('https://api.mazeedplus.com/select-placement');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'x-publishable-api-key: pk_live_51H7...',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'identifier' => 'checkout_success',
    'attributes' => [
        'userId' => 'user_123456789',
        'mobile' => '+966501234567',
        'currency' => 'sar',
        'country' => 'sa',
        'firstname' => 'Ahmed',
        'lastname' => 'Ali',
        'interests' => ['technology', 'gaming', 'brand:Nike', 'brand:Apple'],
        'q' => 'كولومبي قهوه'
    ]
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$placement = json_decode($response, true);
curl_close($ch);
?>

{
  "identifier": "checkout_success",
  "templateName": "Product Listing",
  "template_data": {
    "entities": [
      {
        "object": "collection",
        "id": "col_featured",
        "name": "Featured Products",
        "items": [
          { "ref": "prod_1234" },
          { "ref": "prod_5678" },
          { "ref": "prod_9012" }
        ]
      },
      {
        "object": "product",
        "id": "prod_1234",
        "title": "Wireless Headphones",
        "description": "High-quality wireless headphones with active noise cancellation and 30-hour battery life",
        "price": {
          "amount": 8999,
          "currency": "usd"
        },
        "media": [
          {
            "role": "primary",
            "uri": "https://example.com/headphones.jpg",
            "content_type": "image/jpeg"
          }
        ],
        "click_url": "https://checkout.mazeedplus.com/p/prod_1234"
      },
      {
        "object": "product",
        "id": "prod_5678",
        "title": "Smartphone Case",
        "description": "Premium protective case with shock-absorbing design",
        "price": {
          "amount": 2499,
          "currency": "usd"
        },
        "media": [
          {
            "role": "primary",
            "uri": "https://example.com/case.jpg",
            "content_type": "image/jpeg"
          }
        ],
        "click_url": "https://checkout.mazeedplus.com/p/prod_5678"
      },
      {
        "object": "product",
        "id": "prod_9012",
        "title": "Charging Cable",
        "description": "Fast-charging USB-C cable with braided nylon design",
        "price": {
          "amount": 1999,
          "currency": "usd"
        },
        "media": [
          {
            "role": "primary",
            "uri": "https://example.com/cable.jpg",
            "content_type": "image/jpeg"
          }
        ],
        "click_url": "https://checkout.mazeedplus.com/p/prod_9012"
      },
      {
        "object": "incentive",
        "id": "inc_abc123",
        "kind": "free_shipping",
        "value": {
          "amount": 0,
          "currency": "usd"
        },
        "title": "Free Shipping",
        "description": "Free shipping on orders over $50"
      }
    ]
  }
}

{
  "error": "Validation failed",
  "error_code": "VALIDATION_ERROR",
  "message": "Invalid request data",
  "details": {
    "_errors": [],
    "identifier": {
      "_errors": [
        "Required"
      ]
    }
  }
}

{
  "error": "Validation failed",
  "error_code": "VALIDATION_ERROR",
  "message": "Invalid request data",
  "details": {
    "_errors": [],
    "attributes": {
      "_errors": [],
      "userId": {
        "_errors": [
          "User ID is required"
        ]
      }
    }
  }
}

{
  "error": "Validation failed",
  "error_code": "VALIDATION_ERROR",
  "message": "Invalid request data",
  "details": {
    "_errors": [],
    "attributes": {
      "_errors": [],
      "mobile": {
        "_errors": [
          "Mobile number must include country code with + prefix (e.g., +966501234567)"
        ]
      }
    }
  }
}

{
  "error": "Placement not found",
  "error_code": "PLACEMENT_NOT_FOUND",
  "message": "No placement found with identifier: non-existent-placement"
}

The Placements API returns personalized content and offers based on user context and behavior. Use this API to display targeted promotions, product recommendations, and custom offers at key moments in your user journey.

Endpoint

POST https://api.mazeedplus.com/select-placement

Authentication

Authenticate your requests by including your API key in the x-publishable-api-key header.

x-publishable-api-key: pk_live_51H7...

Create a placement

Creates a personalized placement for display to your users.

Parameters

string

required

Unique identifier for the placement (e.g., “home-page”, “checkout_success”)

object

required

User and transaction data for personalization

Show Customer Information

string

required

Unique customer identifier from your system

string

Customer mobile phone number with country code (e.g., “+966501234567” for Saudi Arabia, “+971501234567” for UAE, “+201001234567” for Egypt)

string

Customer first name

string

Customer last name

number

Customer age in years

string

Customer gender (“male” or “female”)

array

Array of customer interests and brand preferences (e.g., [“technology”, “fitness”, “brand:Nike”, “brand:Apple”])

string

Two-letter country code (ISO 3166-1 alpha-2)

string

Two-letter language code (ISO 639-1)

Show Transaction Data

string

Three-letter currency code (ISO 4217)

string

Order confirmation reference

string

Payment method used

string

JSON string of cart contents for cross-sell analysis

Show Search

string

Search query to find relevant products

Returns

The response format depends on the Accept header:

JSON Response (default)

When Accept: application/json or no specific HTML accept header is provided, returns a placement object.

HTML Response

When Accept: text/html is provided, returns an HTML document directly in the response body with Content-Type: text/html.

string

Unique identifier for this placement

string

Name of the template used for rendering

object

Structured data for native rendering

Show data properties

array

Array of content entities

Show Entity Types

object

Groups related products together

Show Collection properties

string

Always “collection”

string

Unique collection identifier

string

Collection display name

array

Array of product references

Show Item reference

string

Product ID reference

object

Individual product for display

Show Product properties

string

Always “product”

string

Unique product identifier

string

Product name

string

Product description (optional)

object

Pricing information

Show Price object

number

Price

string

Three-letter currency code

object

Original price for discounted items (optional)

array

Product images and media

Show Media object

string

Media role (“primary” or “secondary”)

string

Media URL

string

MIME type (e.g., “image/jpeg”)

string

Product brand (optional)

string

Product category (optional)

string

Product purchase/detail page URL

object

Customer ratings (optional)

Show Rating object

number

Average rating (1-5)

number

Number of reviews

object

Promotional incentive or discount

Show Incentive properties

string

Always “incentive”

string

Unique incentive identifier

string

Incentive type (“cart_credit”, “discount_percentage”, “discount_fixed”, “free_shipping”)

object

Incentive value information

Show Value object

number

Value amount

string

Currency code

string

Incentive display title

string

Incentive description (optional)

object

Visual content or messaging

Show Creative properties

string

Always “creative”

string

Unique creative identifier

string

Creative headline (optional)

string

Text content or message

array

Creative media (optional)

Show Media object

string

Media role (“primary” or “secondary”)

string

Media URL

string

MIME type (e.g., “image/jpeg”)

string

Creative video URL (optional)

object

Call-to-action button (optional)

Show CTA object

string

Button text

string

Button destination URL

string

ISO timestamp of when the placement was rendered

curl https://api.mazeedplus.com/select-placement \
  -H "x-publishable-api-key: pk_live_51H7..." \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "checkout_success",
    "attributes": {
      "userId": "user_123456789",
      "mobile": "+966501234567",
      "currency": "sar",
      "country": "sa",
      "firstname": "Ahmed",
      "lastname": "Ali",
      "interests": ["technology", "gaming", "brand:Nike", "brand:Apple"],
      "q": "كولومبي قهوه"
    }
  }'

const response = await fetch("https://api.mazeedplus.com/select-placement", {
  method: "POST",
  headers: {
    "x-publishable-api-key": "pk_live_51H7...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    identifier: "checkout_success",
    attributes: {
      userId: "user_123456789",
      mobile: "+966501234567",
      currency: "sar",
      country: "sa",
      firstname: "Ahmed",
      lastname: "Ali",
      interests: ["technology", "gaming", "brand:Nike", "brand:Apple"],
      q: "كولومبي قهوه",
    },
  }),
});

const placement = await response.json();

import requests

response = requests.post(
    "https://api.mazeedplus.com/select-placement",
    headers={
        "x-publishable-api-key": "pk_live_51H7...",
        "Content-Type": "application/json"
    },
    json={
        "identifier": "checkout_success",
        "attributes": {
            "userId": "user_123456789",
            "mobile": "+966501234567",
            "currency": "sar",
            "country": "sa",
            "firstname": "Ahmed",
            "lastname": "Ali",
            "interests": ["technology", "gaming", "brand:Nike", "brand:Apple"],
            "q": "كولومبي قهوه"
        }
    }
)

placement = response.json()

<?php
$ch = curl_init('https://api.mazeedplus.com/select-placement');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'x-publishable-api-key: pk_live_51H7...',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'identifier' => 'checkout_success',
    'attributes' => [
        'userId' => 'user_123456789',
        'mobile' => '+966501234567',
        'currency' => 'sar',
        'country' => 'sa',
        'firstname' => 'Ahmed',
        'lastname' => 'Ali',
        'interests' => ['technology', 'gaming', 'brand:Nike', 'brand:Apple'],
        'q' => 'كولومبي قهوه'
    ]
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$placement = json_decode($response, true);
curl_close($ch);
?>

{
  "identifier": "checkout_success",
  "templateName": "Product Listing",
  "template_data": {
    "entities": [
      {
        "object": "collection",
        "id": "col_featured",
        "name": "Featured Products",
        "items": [
          { "ref": "prod_1234" },
          { "ref": "prod_5678" },
          { "ref": "prod_9012" }
        ]
      },
      {
        "object": "product",
        "id": "prod_1234",
        "title": "Wireless Headphones",
        "description": "High-quality wireless headphones with active noise cancellation and 30-hour battery life",
        "price": {
          "amount": 8999,
          "currency": "usd"
        },
        "media": [
          {
            "role": "primary",
            "uri": "https://example.com/headphones.jpg",
            "content_type": "image/jpeg"
          }
        ],
        "click_url": "https://checkout.mazeedplus.com/p/prod_1234"
      },
      {
        "object": "product",
        "id": "prod_5678",
        "title": "Smartphone Case",
        "description": "Premium protective case with shock-absorbing design",
        "price": {
          "amount": 2499,
          "currency": "usd"
        },
        "media": [
          {
            "role": "primary",
            "uri": "https://example.com/case.jpg",
            "content_type": "image/jpeg"
          }
        ],
        "click_url": "https://checkout.mazeedplus.com/p/prod_5678"
      },
      {
        "object": "product",
        "id": "prod_9012",
        "title": "Charging Cable",
        "description": "Fast-charging USB-C cable with braided nylon design",
        "price": {
          "amount": 1999,
          "currency": "usd"
        },
        "media": [
          {
            "role": "primary",
            "uri": "https://example.com/cable.jpg",
            "content_type": "image/jpeg"
          }
        ],
        "click_url": "https://checkout.mazeedplus.com/p/prod_9012"
      },
      {
        "object": "incentive",
        "id": "inc_abc123",
        "kind": "free_shipping",
        "value": {
          "amount": 0,
          "currency": "usd"
        },
        "title": "Free Shipping",
        "description": "Free shipping on orders over $50"
      }
    ]
  }
}

{
  "error": "Validation failed",
  "error_code": "VALIDATION_ERROR",
  "message": "Invalid request data",
  "details": {
    "_errors": [],
    "identifier": {
      "_errors": [
        "Required"
      ]
    }
  }
}

{
  "error": "Validation failed",
  "error_code": "VALIDATION_ERROR",
  "message": "Invalid request data",
  "details": {
    "_errors": [],
    "attributes": {
      "_errors": [],
      "userId": {
        "_errors": [
          "User ID is required"
        ]
      }
    }
  }
}

{
  "error": "Validation failed",
  "error_code": "VALIDATION_ERROR",
  "message": "Invalid request data",
  "details": {
    "_errors": [],
    "attributes": {
      "_errors": [],
      "mobile": {
        "_errors": [
          "Mobile number must include country code with + prefix (e.g., +966501234567)"
        ]
      }
    }
  }
}

{
  "error": "Placement not found",
  "error_code": "PLACEMENT_NOT_FOUND",
  "message": "No placement found with identifier: non-existent-placement"
}

Usage

The Placements API can return either structured JSON data or HTML content directly, depending on your Accept header.

Getting HTML Content Directly

To receive HTML content directly (for iframe or server-side rendering), set the Accept header:

curl https://api.mazeedplus.com/select-placement \
  -H "x-publishable-api-key: pk_live_51H7..." \
  -H "Content-Type: application/json" \
  -H "Accept: text/html" \
  -d '{
    "identifier": "home",
    "attributes": {
      "userId": "user_123456789",
      "q": "كولومبي قهوه"
    }
  }'

# Returns HTML document directly:
# <!DOCTYPE html>
# <html>
#   <head><style>...</style></head>
#   <body>...</body>
# </html>

Getting Structured JSON Data

For native mobile apps or custom rendering, request JSON (default):

const response = await fetch("https://api.mazeedplus.com/select-placement", {
  method: "POST",
  headers: {
    "x-publishable-api-key": "pk_live_51H7...",
    "Content-Type": "application/json",
    "Accept": "application/json"  // Optional, JSON is default
  },
  body: JSON.stringify({
    identifier: "home",
    attributes: {
      userId: "user_123456789",
      q: "كولومبي قهوه"
    }
  })
});

const placement = await response.json();
// Use placement.template_data for native rendering

Native mobile integration

Use the structured data for native rendering:

// iOS example
struct Product {
    let id: String
    let title: String
    let price: Price
    let imageUrl: String
    let url: String
}

// Parse collections and products
let collections = placement.data.entities.filter { $0.object == "collection" }
let products = placement.data.entities.filter { $0.object == "product" }

// Display featured collection
if let featured = collections.first(where: { $0.id == "col_featured" }) {
    let featuredProducts = featured.items.compactMap { item in
        products.first { $0.id == item.ref }
    }
    displayProductCollection(featuredProducts)
}

Mobile Ad Integration

Getting Started

Integration Guides

API Reference

Endpoint

Authentication

Create a placement

Parameters

Returns

JSON Response (default)

HTML Response

Usage

Getting HTML Content Directly

Getting Structured JSON Data

Native mobile integration

​Endpoint

​Authentication

​Create a placement

​Parameters

​Returns

​JSON Response (default)

​HTML Response

​Usage

​Getting HTML Content Directly

​Getting Structured JSON Data

​Native mobile integration

Endpoint

Authentication

Create a placement

Parameters

Returns

JSON Response (default)

HTML Response

Usage

Getting HTML Content Directly

Getting Structured JSON Data

Native mobile integration