Skip to main content

Ad Recommendations API

Request offers from Disco, render them in your own UI, and report outcomes back. The Ad Recommendations API is a direct API: call it from a client, an SDK, or your server, wherever your surface lives. It is distinct from the Channel API, which manages your publishers and exclusions. The Ad Recommendations API is how you actually serve ads. This guide is the walkthrough. The full request/response schemas for every endpoint live in the Ad Recommendations API reference.

Two calls make up the loop:

  1. POST /recommendations: send shopper and placement context, get back the best offers to display.
  2. POST /events: report what happened (impressions, clicks, conversions) so attribution and optimization work.

Base URL & authentication​

EnvironmentBase URL
Productionhttps://partners.disconetwork.com
Staginghttps://partners.disconetwork-staging.com
  • Authenticate with your x-api-key header, using the scoped API key Disco provisions for your integration. Legacy partner-wide keys are still accepted for existing integrations.
  • Every request also requires a version header (e.g. 1.0.0).
curl -X POST https://partners.disconetwork.com/recommendations \
  -H "x-api-key: your-api-key" \
  -H "version: 1.0.0" \
  -H "Content-Type: application/json" \
  -d @request.json

1. Request recommendations​

POST /recommendations ("Get Disco Advertiser Recommendations"). Send shopper identity and placement context; only user_details and placement_details are required.

Key request fields:

FieldRequiredDetails
user_details✓One shopper identifier (email, email_hash as SHA-256, phone, or external_guid) plus optional first_name, last_name, etc.
placement_details.view✓Surface: ORDER_STATUS · CHECKOUT · THANK_YOU · POST_ORDER · ORDER_TRACKING · SUPPORT_CENTER
placement_details.display_mode✓OVERLAY · FULLSCREEN · PULLUP · INLINE
order_detailsorder_id + cost details
purchasesArray of purchased items
attributesDevice / OS / language / IP context
custom_metadata.is_sandboxtrue for test requests (won't drive conversions)
Request body
{
  "user_details": { "email": "shopper@example.com", "first_name": "Monica" },
  "placement_details": { "display_mode": "INLINE", "view": "ORDER_STATUS" },
  "order_details": { "order_id": "67890XYZ" },
  "purchases": [ { "product_id": "PROD123", "name": "Headphones", "quantity": "1" } ]
}

Response: a session_id plus a recommendations map keyed by offer ID. Each offer carries its advertiser and creative:

Response: 200
{
  "session_id": "30576e99-fda5-41bc-b62c-65109ba47147",
  "recommendations": {
    "adb0e805-ef67-4083-a2be-0ff3e0b16dce": {
      "advertiser": {
        "id": "30576e99-fda5-41bc-b62c-65109ba47147",
        "name": "Marlowe's Roastery",
        "logo_url": "https://cdn.disconetwork.com/advertisers/marlowes.png"
      },
      "offer": {
        "id": "adb0e805-ef67-4083-a2be-0ff3e0b16dce",
        "heading": "15% OFF",
        "subheading": "On your next purchase",
        "target_url": "https://marlowes.com/collections/coffee",
        "cta_details": { "accept_copy": "Shop now", "decline_copy": "No thanks" }
      }
    }
  },
  "recommendation_groups": [ ],
  "footer": { }
}

Render the offers in your surface using each offer.heading / subheading / cta_details, linking to target_url. Hold onto the session_id and each offer.id; you'll pass them back on events.

2. Report events​

POST /events (single) or POST /events/batch (1–20 per call): report impressions, clicks, and conversions so Disco can attribute and optimize. Include the version header, and reference the session_id and the offer.id from the recommendation response.

  • /events → 201 on success.
  • /events/batch → 202 (all accepted) or 207 (partial; inspect results to retry only the failures).

Notes​

  • Sandbox: set custom_metadata.is_sandbox: true to test without driving conversions.
  • Versioning: the version header is required on every call; pin it and update deliberately.
  • The full endpoint schemas (request/response for /recommendations, /events, /events/batch) live in the Ad Recommendations API reference, auto-generated from the OpenAPI spec.