Placements API

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

identifier

string

required

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

attributes

object

required

User and transaction data for personalization

Show Customer Information

userId

string

required

Unique customer identifier from your system

mobile

string

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

firstname

string

Customer first name

lastname

string

Customer last name

age

number

Customer age in years

gender

string

Customer gender (“male” or “female”)

interests

array

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

country

string

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

language

string

Two-letter language code (ISO 639-1)

Show Transaction Data

currency

string

Three-letter currency code (ISO 4217)

confirmationref

string

Order confirmation reference

paymenttype

string

Payment method used

cartItems

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.

identifier

string

Unique identifier for this placement

templateName

string

Name of the template used for rendering

template_data

object

Structured data for native rendering

Show data properties

entities

array

Array of content entities

Show Entity Types

Collection Entity

object

Groups related products together

Show Collection properties

object

string

Always “collection”

string

Unique collection identifier

name

string

Collection display name

items

array

Array of product references

Show Item reference

ref

string

Product ID reference

Product Entity

object

Individual product for display

Show Product properties

object

string

Always “product”

string

Unique product identifier

title

string

Product name

description

string

Product description (optional)

price

object

Pricing information

Show Price object

amount

number

Price

currency

string

Three-letter currency code

compare_price

object

Original price for discounted items (optional)

media

array

Product images and media

Show Media object

role

string

Media role (“primary” or “secondary”)

uri

string

Media URL

content_type

string

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

brand

string

Product brand (optional)

category

string

Product category (optional)

click_url

string

Product purchase/detail page URL

rating

object

Customer ratings (optional)

Show Rating object

average

number

Average rating (1-5)

count

number

Number of reviews

Incentive Entity

object

Promotional incentive or discount

Show Incentive properties

object

string

Always “incentive”

string

Unique incentive identifier

kind

string

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

value

object

Incentive value information

Show Value object

amount

number

Value amount

currency

string

Currency code

title

string

Incentive display title

description

string

Incentive description (optional)

Creative Entity

object

Visual content or messaging

Show Creative properties

object

string

Always “creative”

string

Unique creative identifier

title

string

Creative headline (optional)

content

string

Text content or message

media

array

Creative media (optional)

Show Media object

role

string

Media role (“primary” or “secondary”)

uri

string

Media URL

content_type

string

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

video_url

string

Creative video URL (optional)

cta

object

Call-to-action button (optional)

Show CTA object

text

string

Button text

click_url

string

Button destination URL

rendered_at

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": "كولومبي قهوه"
    }
  }'

{
  "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",
        "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",
        "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",
        "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"
      }
    ]
  }
}

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)
}

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

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