Session Offers API specification (S2S)

This document outlines the endpoint necessary to retrieve Offer content from Rokt using the Session API (v2).

Work with your Rokt account team to obtain the necessary credentials. For an end-to-end integration walkthrough, see Session API integration (S2S).

Endpoint

Environment	Action	URL
Production	POST	https://api.rokt.com/v2/sessions/offers

note

There is no separate sandbox URL. To validate before going live, send the rokt-test-session: true header on the same endpoint. Test sessions are tagged and filtered out of production metrics. The header marks reporting only — it does not force an offer to serve. For deterministic end-to-end testing, your account team can configure a staging page with dedicated test campaigns. Remove the header to go live.

Request

Authorization headers

Header	Description	Type	Note
Authorization	Basic auth credentials	string	Basic base64(rpub:rsec) — use the public and secret API keys provided by your account team.
rokt-account-id	Your Rokt account ID	string	Required on every call. This is the source of account identity on the Session API.

Required headers

Header	Description	Type	Example
Content-Type	Media type	string	application/json
rokt-platform-type	Platform the offers are being requested for	string	iOS, Android, Web, WebDesktop, or WebMobile (case-insensitive). Defaults to Web.

note

Server-to-server traffic classifies as Web by default. If your Rokt pages are configured for a native platform (iOS or Android), set the rokt-platform-type header to that platform — otherwise page detection will not match your native-configured pages and will return no offers. Web-configured pages need no header.

Root/Body

Property	Required	Type	Description
channel	Yes	object	Must contain "type": "s2s".
page	Yes	object	See Page.
customer	No	object	See Customer.
transaction	No	object	See Transaction.
payment	No	object	See Payment.
device	No	object	See Device.
attributes	No	object	Free-form string → string map for any partner-specific signal that doesn't fit a typed object.

note

Send only values you own. Rokt-derived attributes — geo, age and other demographics, device type/OS/version, payment method, and ML signals — are computed server-side and overwritten if sent; do not include them.

Page

Property	Required	Type	Description
page_identifier	Yes	string	Text used to differentiate views/pages.
page_variation_code	No	string	Optional variation code for the page.

Customer

Property	Required	Type	Description
email	No	string	Customer email address.
first_name	No	string	Customer first name.
last_name	No	string	Customer last name.
gender	No	string	Customer gender.
postal_code	No	string	Customer postal/zip code.
language	No	string	Customer language code (e.g. en).

Transaction

Property	Required	Type	Description
transaction_value	No	number	Value of the transaction.
currency	No	string	ISO 4217 currency code (e.g. USD).
confirmation_ref	No	string	Partner-side order or confirmation reference.

Payment

Property	Required	Type	Description
type	No	string	Payment method type (e.g. card).

Device

Property	Required	Type	Description
user_agent	No	string	User agent string of the client device or application.

Request example

POST https://api.rokt.com/v2/sessions/offers
Authorization: Basic base64(rpub:rsec)
rokt-account-id: <your Rokt account ID>
rokt-platform-type: Web
Content-Type: application/json

{
  "channel": { "type": "s2s" },
  "page": { "page_identifier": "checkout" },
  "customer": {
    "email": "jane.doe@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "gender": "F",
    "postal_code": "10001",
    "language": "en"
  },
  "transaction": {
    "transaction_value": 19.99,
    "currency": "USD",
    "confirmation_ref": "ORDER-000123"
  },
  "payment": { "type": "card" },
  "device": {
    "user_agent": "YourApp/1.0 (mobile)"
  },
  "attributes": {
    "your_custom_attribute": "value"
  }
}

Response

Success response (2xx)

A 2xx response returns the offer directly — there is no success/errors envelope. plugins may be empty, which is a valid no-fill scenario representing a real share of production traffic: render nothing and continue the page.

Key fields

What you need	Path in the response
Offer	plugins[].plugin.config.slots[].offer
Title / copy	…offer.creative.copy["creative.title"]
Image	…offer.creative.copy["creative.image.src"]
Disclaimer	…offer.creative.copy["creative.disclaimer"]
Terms & Conditions link	…offer.creative.copy["creative.termsAndConditions.link"]
Privacy Policy link	…offer.creative.copy["creative.privacyPolicy.link"]
Advertiser	…offer.creative.advertiser
Positive action + URL	…offer.creative.response_options_map.positive.url
Decline action	…offer.creative.response_options_map.negative
Element instance IDs (use as event parent_id)	…slots[].instance_guid, …offer.creative.instance_guid, …response_options_map[key].instance_guid
Page instance (use as event page_instance_guid)	page_instance_guid
Session ID (use as event session_id)	session_id
Session token (refreshed session reference)	session_token.token

Advertiser

Property	Type	Description
name	string	The advertiser's legal entity name.
brand	string	The advertiser's brand name.

Example success response (2xx)

A layout-configured account returns populated outer_layout_schema and per-slot layout_variant fields; a data-integration account returns the same offer/creative content with those layout schemas empty. All values below are synthetic examples — read the fields you need using the Key fields paths above.

{
  "session_id": "b1fb003c-e904-4083-b7b9-03cde555a7a1",
  "page_instance_guid": "018f2a1b-0000-7abc-8def-page00000001",
  "session_token": {
    "token": "<session_token>"
  },
  "plugins": [
    {
      "plugin": {
        "id": "3353172846080032866",
        "name": "dcui",
        "config": {
          "instance_guid": "ce5158a9-dc59-4a97-9006-a299901e4587",
          "outer_layout_schema": "<JSON-encoded layout schema>",
          "layout_schema_version": "2.0",
          "slots": [
            {
              "instance_guid": "8f492d28-83fb-4813-877e-26e752ea9474",
              "offer": {
                "campaign_id": "2749386944931233793",
                "account_id": "<your Rokt account ID>",
                "creative": {
                  "referral_creative_id": "2760914349384466797",
                  "instance_guid": "c9f37d78-731d-4a0e-b8bc-712bd8c46cc1",
                  "advertiser": {
                    "name": "Example Advertiser Inc.",
                    "brand": "Example Brand"
                  },
                  "copy": {
                    "creative.title": "Get 20% off your next order",
                    "creative.image.src": "https://example.com/creative/hero.png",
                    "creative.disclaimer": "New customers only. Terms apply.",
                    "creative.termsAndConditions.link": "https://example.com/terms",
                    "creative.privacyPolicy.link": "https://example.com/privacy"
                  },
                  "response_options_map": {
                    "positive": {
                      "id": "2760914349384466794",
                      "action": "Url",
                      "instance_guid": "1d47ded1-b483-44e6-abf8-1d1d5faa82bc",
                      "signal_type": "SignalResponse",
                      "short_label": "Yes",
                      "long_label": "Yes please",
                      "is_positive": true,
                      "url": "https://example.com/redeem",
                      "url_behavior": "newTab",
                      "token": "<event-token>"
                    },
                    "negative": {
                      "id": "2760914349384466796",
                      "action": "CaptureOnly",
                      "instance_guid": "24de5c75-ff04-41c5-b3f7-7d2ee129ecc6",
                      "signal_type": "SignalResponse",
                      "short_label": "No thanks",
                      "long_label": "No thanks",
                      "is_positive": false,
                      "token": "<event-token>"
                    }
                  },
                  "token": "<event-token>"
                }
              },
              "layout_variant": {
                "layout_variant_id": "3353172846080032865",
                "module_name": "standard-marketing",
                "format_type": "Text",
                "layout_variant_schema": "<JSON-encoded layout schema>"
              },
              "token": "<event-token>"
            }
          ]
        }
      },
      "fonts": []
    }
  ]
}

No-fill response (2xx)

When there are no relevant offers for a particular user, Rokt returns a 2xx with an empty plugins array. Render nothing and continue your page.

{
  "plugins": [],
  "page_instance_guid": "018f2a1b-0000-7abc-8def-page00000001",
  "session_token": {
    "token": "<session_token>"
  }
}

Error responses (4xx / 5xx)

Errors return a semantic HTTP status with a structured body:

{
  "error": "<code>",
  "message": "<detail>"
}

Validation failures include an additional details[] array.

Common error codes

HTTP status	Meaning
400	Malformed request body.
401	Missing or invalid Authorization header.
422	Request validation failed (see details[]).
429	Rate limited. Do not retry automatically — pause and contact your Rokt representative if 429s persist.
5xx	Unexpected server error. Retry after a brief delay (1–2 seconds). If the problem persists, contact support@rokt.com.

Caching offers

To maximize revenue opportunities, fetch offer content from /v2/sessions/offers earlier in the user's transaction journey — before the offer is expected to render — then cache it for fast client retrieval within the same transaction.

We recommend caching against a combination of unique transaction ID, user ID, and user device type. If the user context shifts (e.g. device change), re-fetch with updated attributes to ensure offer relevance.