Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mazeedplus.com/llms.txt

Use this file to discover all available pages before exploring further.

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

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

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