Skip to main content

DiscoBeat S2S Integration

Serve Disco ads on your channel's surfaces server-to-server — request offers from Disco, render them in your own UI, and report outcomes back. This is distinct from the Channel API, which manages your publishers and exclusions; S2S is how you actually serve ads. This guide is the walkthrough — the full request/response schemas for every endpoint live in the Recommendations & Events API reference.

Two calls make up the loop:

  1. POST /recommendations — send shopper + 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.
  • 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 + placement context; only user_details and placement_details are required.

Key request fields:

FieldRequiredDetails
user_details✓One shopper identifier — email, email_hash (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 Recommendations & Events API reference, auto-generated from the OpenAPI spec.