Delivery

The delivery endpoint is how you fetch advertising content for your members. Given a member and an ad unit, it returns the list of deals that are eligible for that member in that slot - complete with ready-to-render creative content.

The Integration Loop

A complete ad delivery integration follows this cycle:

1. Create ad units defining your available advertising surfaces
2. Call list-eligible for a specific member + ad unit to get matching deals
3. Render the creative content returned for each eligible deal
4. Record an impression when the creative is displayed to the member
5. Save a clip if the member activates/saves the deal

Listing Eligible Deals

curl -X POST https://<your-instance-url>/publisher.v1/delivery/list-eligible \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "member_id": "m_x1y2z3",
    "ad_unit_id": "au_abc123"
  }'

Response:

[
  {
    "deal_id": "deal_001",
    "creative_id": "dc_abc",
    "variant_id": "var_001",
    "format": "banner",
    "content": {
      "surface": {
        "title": "10% cashback at Store",
        "summary": "Earn cashback on your next purchase",
        "image_url": "https://cdn.example.com/banner.png",
        "reward": { "percent": 10 }
      },
      "details": {
        "title": "Store Cashback Deal",
        "image_url": "https://cdn.example.com/detail.png",
        "description": "Get 10% back on purchases over $20",
        "summary": "Limited time offer"
      }
    }
  }
]

How Eligibility Works

The delivery engine evaluates several criteria server-side:

1. Format matching - Only deals with creatives matching the ad unit's format are considered.
2. Audience targeting - Each deal has placement rules that define target audience criteria based on member attributes (e.g. tier, location, spend range). Only deals whose criteria match the member's current attributes are returned.
3. Clip exclusion - Deals the member has already clipped are excluded. A clipped deal has been "activated" and is no longer eligible for delivery.
4. Variant assignment - For deals with multiple variants, the system deterministically assigns a variant to each member ensuring consistent delivery.

All of this happens server-side. As an integrator, you simply provide the member ID and ad unit ID and receive the final list of eligible deals with their creative content.

Creative Content Structure

The content object varies by format but follows a consistent pattern:

Banner Format

{
  "surface": {
    "title": "Deal headline",
    "summary": "Short description",
    "image_url": "https://...",
    "reward": { "percent": 10 }
  },
  "details": {
    "title": "Full title",
    "image_url": "https://...",
    "description": "Detailed description",
    "summary": "Brief summary"
  }
}

Card Format

{
  "surface": {
    "title": "Deal headline",
    "summary": "Short description",
    "image_url": "https://...",
    "reward": { "amount": 500 }
  },
  "details": {
    "title": "Full title",
    "image_url": "https://...",
    "description": "Detailed description",
    "summary": "Brief summary"
  }
}

Reward Variants

The reward field in surface can take several forms:

Format	Example	Meaning
Percentage	{"percent": 10}	10% cashback
Fixed amount	{"amount": 500}	Fixed reward in minor units
Formatted	{"formatted": "Up to $5"}	Pre-formatted display string

Rendering Recommendations

• Use surface fields for the initial ad display (the creative as shown in the ad unit slot).
• Use details fields for an expanded view if the member taps or clicks to learn more.
• The image_url fields resolve to your Publisher instance (e.g. https://<your-instance-url>/assets/...) where the image can be downloaded directly. You may want to proxy these URLs through your own servers for caching, CDN integration, or to avoid exposing the Publisher URL to end users.

Platform-Side Configuration

Deals, placement rules, and targeting criteria are configured on the K42 platform - not through the Publisher API. As a publisher, your responsibilities are:

1. Define your ad units (format + channel)
2. Maintain accurate member attributes for targeting
3. Call list-eligible and render the results
4. Record impressions and manage clips

The platform handles deal lifecycle, creative management, and targeting rule configuration.