Session Offers API specification (S2S)

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

For the same contract as an interactive, schema-level reference, see the Session API reference.

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 carry error: "validation_failed" and an additional details[] array naming each offending field.

Common error codes

HTTP status	Meaning
400	Malformed request body, or a body that failed validation (error: "validation_failed").
401	Missing or invalid Authorization header.
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.