--- updatedAt: 2026-04-28T09:02:40.000Z --- # Choose Variations Get the chosen variations for one or more campaigns.
If you are not sure which server URL you should use, [see here](https://dy.dev/docs/experience-api-basics). # OpenAPI definition ```json { "openapi": "3.0.3", "info": { "version": "2.2", "title": "Dynamic Yield Experience API", "description": "API definitions for all Dynamic Yield public endpoints.", "contact": { "name": "API Support", "email": "apisupport@mastercard.com", "url": "https://developer.mastercard.com/support" } }, "servers": [ { "url": "https://dy-api.com/v2", "description": "US data center" }, { "url": "https://direct.dy-api.com/v2", "description": "US data center, direct endpoint" }, { "url": "https://dy-api.eu/v2", "description": "EU data center" }, { "url": "https://direct.dy-api.eu/v2", "description": "EU data center, direct endpoint" } ], "security": [ { "ApiKeyAuth": [] } ], "tags": [ { "name": "Experience APIs", "description": "Serve user experience and track user interactions." } ], "paths": { "/serve/user/choose": { "summary": "Choose Variations", "post": { "summary": "Choose Variations", "description": "Get the chosen variations for one or more campaigns.
If you are not sure which server URL you should use, [see here](https://dy.dev/docs/experience-api-basics).", "operationId": "chooseVariations", "tags": [ "Experience APIs" ], "requestBody": { "$ref": "#/components/requestBodies/ChooseBody" }, "responses": { "200": { "$ref": "#/components/responses/SuccessChoose" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/InvalidUnprocessable" } } } } }, "components": { "schemas": { "ChoosePayloadEcom": { "title": "Choose Request - E-Commerce", "type": "object", "properties": { "user": { "$ref": "#/components/schemas/ChooseUserEcom" }, "session": { "$ref": "#/components/schemas/SessionChoose" }, "context": { "$ref": "#/components/schemas/ContextChooseEcom" }, "selector": { "$ref": "#/components/schemas/SelectorChoose" }, "options": { "$ref": "#/components/schemas/OptionsChooseEcom" } }, "required": [ "user", "session", "context", "selector" ] }, "ChoosePayloadFi": { "allOf": [ { "title": "Choose Request - Financial Institutions" }, { "$ref": "#/components/schemas/ChoosePayloadEcom" } ] }, "ChoosePayloadQsr": { "title": "Choose Request - Restaurants", "type": "object", "properties": { "user": { "$ref": "#/components/schemas/ChooseUserQsr" }, "session": { "$ref": "#/components/schemas/SessionChoose" }, "context": { "$ref": "#/components/schemas/ContextChooseQsr" }, "selector": { "description": "Campaigns to choose variations for, formatted as `widgetIdentifier@campaignIdentifier`.", "type": "object", "properties": { "names": { "$ref": "#/components/schemas/Names" }, "groups": { "$ref": "#/components/schemas/Groups" }, "preview": { "$ref": "#/components/schemas/Preview" } }, "required": [ "names" ] }, "options": { "$ref": "#/components/schemas/OptionsChooseQsr" } }, "required": [ "user", "session", "context", "selector" ] }, "Choice": { "title": "Choice", "type": "object", "properties": { "choices": { "description": "The chosen variation for each campaign.", "type": "array", "items": { "oneOf": [ { "title": "type: DECISION", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "default": "DECISION", "pattern": "DECISION" }, "variations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "name": { "type": "string" }, "payload": { "type": "object", "properties": { "type": { "type": "string", "default": "CUSTOM_JSON", "pattern": "CUSTOM_JSON" }, "data": { "type": "object" } } }, "rolloutFlag": { "type": "boolean", "description": "Only in Rollout campaigns" }, "analyticsMetadata": { "type": "object", "properties": { "campaignId": { "type": "number" }, "campaignName": { "type": "string" }, "experienceId": { "type": "number" }, "experienceName": { "type": "string" }, "variationId": { "type": "number" }, "variationName": { "type": "string" } } } } } }, "groups": { "type": "array", "items": { "type": "string" } }, "decisionId": { "type": "string" }, "allocationGroup": { "type": "string" } } }, { "title": "type: RECS_DECISION", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "default": "RECS_DECISION", "pattern": "RECS_DECISION" }, "variations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "name": { "type": "string" }, "payload": { "type": "object", "properties": { "type": { "type": "string", "default": "RECS", "pattern": "RECS" }, "data": { "type": "object", "properties": { "custom": { "type": "object" }, "slots": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string" }, "slotId": { "type": "string" }, "productData": { "type": "object" } } } } } } } }, "analyticsMetadata": { "type": "object", "properties": { "campaignId": { "type": "number" }, "campaignName": { "type": "string" }, "experienceId": { "type": "number" }, "experienceName": { "type": "string" }, "variationId": { "type": "number" }, "variationName": { "type": "string" } } } } } }, "groups": { "type": "array", "items": { "type": "string" } }, "decisionId": { "type": "string" }, "allocationGroup": { "type": "string" } } }, { "title": "type: QSR_PRODUCT_RECS_DECISION", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "default": "QSR_PRODUCT_RECS_DECISION", "pattern": "QSR_PRODUCT_RECS_DECISION" }, "variations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "name": { "type": "string" }, "payload": { "type": "object", "properties": { "type": { "type": "string", "default": "QSR_PRODUCT_RECS", "pattern": "QSR_PRODUCT_RECS" }, "data": { "type": "object" } } }, "analyticsMetadata": { "type": "object", "properties": { "campaignId": { "type": "number" }, "campaignName": { "type": "string" }, "experienceId": { "type": "number" }, "experienceName": { "type": "string" }, "variationId": { "type": "number" }, "variationName": { "type": "string" } } } } } }, "groups": { "type": "array", "items": { "type": "string" } }, "decisionId": { "type": "string" }, "allocationGroup": { "type": "string" } } }, { "title": "type: SORTING_DECISION", "type": "object", "properties": { "name": { "type": "string" }, "id": { "type": "number" }, "type": { "type": "string", "default": "SORTING_DECISION", "pattern": "SORTING_DECISION" }, "decisionId": { "type": "string" }, "variations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "payload": { "type": "object", "properties": { "data": { "type": "object", "properties": { "slots": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string" }, "slotId": { "type": "string" } } } } } } } } } } } } } ] } }, "cookies": { "description": "Cookies returned from the server.", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" }, "maxAge": { "type": "string" } } } }, "warnings": { "description": "Errors returned by the server.", "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "Error": { "description": "Response object for an invalid request.", "type": "object", "properties": { "message": { "$ref": "#/components/schemas/ErrorMessage" }, "type": { "$ref": "#/components/schemas/ErrorType" } } }, "ErrorMessage": { "description": "Error description.", "type": "string", "example": "request must contain context page location" }, "ErrorType": { "description": "The type of error encountered.", "type": "string", "example": "badRequest" }, "ChooseUserEcom": { "title": "User", "description": "User ID. A Dynamic Yield-generated identifier is used, and managed via cookies. For a new user, send this object empty.", "type": "object", "properties": { "dyid": { "$ref": "#/components/schemas/Dyid" }, "dyid_server": { "$ref": "#/components/schemas/Dyid" }, "active_consent_accepted": { "$ref": "#/components/schemas/ActiveConsentAccepted" } } }, "ChooseUserQsr": { "oneOf": [ { "$ref": "#/components/schemas/ChooseUserQsrSharedDeviceTrue" }, { "$ref": "#/components/schemas/ChooseUserQsrSharedDeviceFalse" } ] }, "ChooseUserQsrSharedDeviceTrue": { "title": "User (sharedDevice: true)", "description": "User ID. A Dynamic Yield-generated identifier is used, and managed via cookies. For a new user, send this object empty.", "type": "object", "properties": { "sharedDevice": { "$ref": "#/components/schemas/SharedDeviceTrue" }, "cuid": { "description": "User identifier value. Required for identified user flows.", "type": "string", "example": "customer_12345" }, "cuidType": { "description": "Use this identifier type to identify users across devices (for example, `customer_id`, `account_id`, or `he` for SHA-256 hashed email).
**Note: Do not include any personal information in this ID.**
Required for identified user flows.", "type": "string", "example": "customer_id" } }, "required": [ "sharedDevice" ] }, "ChooseUserQsrSharedDeviceFalse": { "allOf": [ { "title": "User (sharedDevice: false)" }, { "$ref": "#/components/schemas/ChooseUserEcom" }, { "properties": { "sharedDevice": { "$ref": "#/components/schemas/SharedDeviceFalse" } } } ], "required": [ "sharedDevice" ] }, "Dyid": { "description": "The _dyid cookie value. The user ID assigned to visitors by Dynamic Yield. For a new user, send this param empty. Learn more about the [user ID](https://dy.dev/docs/experience-api-basics#user-id).", "type": "string" }, "ActiveConsentAccepted": { "description": "Add this attribute only if [active cookie consent](https://dy.dev/docs/active-cookie-consent) is enabled. Set to `true` if user gave consent for cookies.", "type": "boolean", "default": false }, "SharedDeviceTrue": { "description": "Set to `true` for transactions done on a shared device in a branch (always `true` for kiosk and ODMB).", "type": "boolean", "default": true }, "SharedDeviceFalse": { "description": "Set to `false` for transactions made on personal devices.", "type": "boolean", "default": false }, "SessionChoose": { "title": "Session", "description": "Session ID. A Dynamic Yield-generated identifier is used. For new sessions, send this object empty.", "type": "object", "properties": { "dy": { "description": "Pass the value of the `_dyjsession` cookie if it exists. Otherwise, a new session identifier will be created by Dynamic Yield and returned in the response.", "type": "string", "example": "ohyr6v42l9zd4bpinnvp7urjjx9lrssw" } } }, "ContextChooseEcom": { "title": "Context", "description": "The request's context.", "type": "object", "properties": { "page": { "$ref": "#/components/schemas/Page" }, "device": { "$ref": "#/components/schemas/DeviceChooseEcom" }, "channel": { "$ref": "#/components/schemas/ChannelEcom" }, "pageAttributes": { "$ref": "#/components/schemas/PageAttributes" }, "listedItems": { "$ref": "#/components/schemas/ListedItems" }, "branch": { "$ref": "#/components/schemas/BranchEcom" } }, "required": [ "page", "device" ] }, "ContextChooseQsr": { "title": "Context", "description": "The request's context.", "type": "object", "properties": { "page": { "$ref": "#/components/schemas/Page" }, "device": { "$ref": "#/components/schemas/DeviceChooseQsr" }, "branch": { "$ref": "#/components/schemas/BranchQsr" }, "channel": { "$ref": "#/components/schemas/ChannelQsr" }, "cart": { "$ref": "#/components/schemas/CartQsr" }, "pageAttributes": { "$ref": "#/components/schemas/PageAttributes" } }, "required": [ "branch", "channel" ] }, "Page": { "description": "Data for the page currently being browsed.", "type": "object", "properties": { "type": { "$ref": "#/components/schemas/PageType" }, "data": { "$ref": "#/components/schemas/PageData" }, "location": { "$ref": "#/components/schemas/Location" }, "referrer": { "$ref": "#/components/schemas/Referrer" }, "locale": { "$ref": "#/components/schemas/Locale" } }, "required": [ "type", "location" ] }, "PageType": { "description": "Page type. Must be upper case. Valid values are:
`HOMEPAGE`, `CATEGORY`, `PRODUCT`, `CART`, and `OTHER`.", "type": "string", "enum": [ "HOMEPAGE", "CATEGORY", "PRODUCT", "CART", "OTHER" ], "example": "HOMEPAGE" }, "PageData": { "description": "Additional data for non-homepage pages: The SKU for a `PRODUCT` page, the category for a `CATEGORY` page, SKUs for the `CART` page, and the page ID in `OTHER`. Learn more about [page context data](https://dy.dev/docs/page-context#localization-in-page-context).", "type": "array", "items": { "type": "string" }, "example": [ "p76311-020" ] }, "Location": { "description": "The current location. URL (for web), location (for SPA), or screen name (for mobile apps). Enables targeting the current page/screen.", "type": "string", "example": "https://shop.biz/nice-shirt-p76311.html" }, "Referrer": { "description": "The previous location. URL (for web), location (for SPA), or screen name (for mobile apps). Enables targeting the previous page or screen. For web implementations, can be used for traffic source targeting, including search, social, and referral traffic classification. Pass the full referrer URL (include HTTP:// or HTTPS://) not only the referring domain.", "type": "string", "example": "https://google.cz" }, "Locale": { "description": "Page locale code, such as `en_US`. Learn more about [using country codes for locale](https://dy.dev/docs/page-context#localization-in-page-context).", "type": "string", "example": "en_US" }, "DeviceChooseEcom": { "description": "Data for the served device.", "type": "object", "properties": { "userAgent": { "$ref": "#/components/schemas/UserAgent" }, "type": { "$ref": "#/components/schemas/DeviceTypeEcom" }, "browser": { "$ref": "#/components/schemas/Browser" }, "ip": { "$ref": "#/components/schemas/Ip" }, "dateTime": { "$ref": "#/components/schemas/DateTime" } } }, "DeviceChooseQsr": { "description": "Data for the served device.", "type": "object", "properties": { "userAgent": { "$ref": "#/components/schemas/UserAgent" }, "type": { "$ref": "#/components/schemas/DeviceTypeQsr" }, "browser": { "$ref": "#/components/schemas/Browser" }, "ip": { "$ref": "#/components/schemas/Ip" }, "dateTime": { "$ref": "#/components/schemas/DateTime" }, "id": { "$ref": "#/components/schemas/DeviceIdQsr" } }, "required": [ "dateTime", "type" ] }, "UserAgent": { "description": "For web clients, the browser user-agent string. If not passed, the API gateway checks for the header in the HTTPS request. This applies only to client-side API calls when isImplicitClientData: true is set in the Options object.", "type": "string", "example": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/56.0.2924.87 Safari/537.36" }, "DeviceTypeEcom": { "description": "Use when the user agent isn't available. Valid values are:
`DESKTOP`, `SMARTPHONE`, `TABLET`, `KIOSK`", "type": "string", "enum": [ "DESKTOP", "SMARTPHONE", "TABLET", "KIOSK" ] }, "DeviceTypeQsr": { "description": "Use when the user agent isn't available. Valid values are:
`DESKTOP`, `SMARTPHONE`, `TABLET`, `KIOSK`, `ODMB`", "type": "string", "enum": [ "DESKTOP", "SMARTPHONE", "TABLET", "KIOSK", "ODMB" ] }, "Browser": { "description": "Use when the user agent isn't available. Valid values are:
`Chrome`, `Firefox`, `Opera`, `Safari`, `Other`", "type": "string", "enum": [ "Chrome", "Firefox", "Opera", "Safari", "Other" ], "example": "Firefox" }, "Ip": { "description": "The client IP address, for geolocation-based targeting and audience building. If not passed, the caller IP is used. This applies only to client-side API calls when isImplicitClientData: true is set in the Options object.", "type": "string", "example": "54.100.200.255" }, "DateTime": { "description": "Date & time in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sss±hh:mm (with local time zone).", "type": "string", "example": "2024-01-01T22:30:00.000-05:00" }, "DeviceIdQsr": { "description": "The identifier of the device in the branch.", "type": "string" }, "ChannelEcom": { "description": "Report and monitor each channel’s Experience API implementation. The channel corresponds to the Experience OS app used (`WEB` or `APP`), and the values are available for filtering in the API logs.", "type": "string", "enum": [ "WEB", "APP" ] }, "ChannelQsr": { "description": "Report and monitor each channel's experience API implementation. Channels correspond to the Experience OS app used. Available channels: `WEB`, `APP`, `KIOSK`, `DRIVE-THRU`", "type": "string", "enum": [ "WEB", "APP", "KIOSK", "DRIVE-THRU" ] }, "BranchEcom": { "description": "The branch where the user experience is taking place.", "type": "object", "properties": { "id": { "$ref": "#/components/schemas/BranchIdEcom" } }, "required": [ "id" ] }, "BranchQsr": { "description": "Use to recommend only items in stock at the branch the user is browsing.", "type": "object", "properties": { "id": { "$ref": "#/components/schemas/BranchIdQsr" }, "dayPart": { "$ref": "#/components/schemas/DayPart" }, "orderFulfillment": { "$ref": "#/components/schemas/OrderFulfillment" } }, "required": [ "dayPart" ] }, "BranchIdEcom": { "description": "The branch's unique identifier.", "type": "string" }, "BranchIdQsr": { "description": "The ID of the branch the recommendation is for.", "type": "string" }, "DayPart": { "description": "Define the period of the day the request ralates to. Possible values are those used in the Product Catalog.", "type": "string", "enum": [ "BREAKFAST", "LUNCH", "DINNER", "LATENIGHT" ] }, "OrderFulfillment": { "description": "The fulfillment type of the order the request relates to.", "type": "string", "enum": [ "DELIVERY", "PICKUP", "DINEIN", "CURBSIDE" ] }, "PageAttributes": { "description": "Pass key-value pairs you want to use for targeting in this campaign. **The value must exactly match the value in the campaign targeting condition, and is case sensitive.** This data is not stored and cannot be used for creating audiences. Values can be strings or numbers.", "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "ListedItems": { "description": "List of SKUs to sort on PLP. Use only for Sorting Optimizer campaigns.", "type": "array", "items": { "type": "string" }, "example": [ "SKU1", "SKU2" ] }, "SelectorChoose": { "title": "Selector", "description": "Campaigns to choose variations for.", "type": "object", "properties": { "names": { "$ref": "#/components/schemas/Names" }, "groups": { "$ref": "#/components/schemas/Groups" }, "preview": { "$ref": "#/components/schemas/Preview" }, "args": { "$ref": "#/components/schemas/Args" } }, "required": [ "names" ] }, "Groups": { "description": "Call a group of selectors instead of listing each selector individually. Learn more about working with [selector groups](https://dy.dev/docs/selector-groups).", "type": "array", "items": { "type": "string" } }, "Names": { "description": "The list of selectors that are eligible for this page. A selector represents a technical name for a campaign. Learn more about [using selectors in your campaigns](https://dy.dev/docs/choose#recommended-use).", "type": "array", "items": { "type": "string" }, "example": [ "Banner Main", "German Banner", "PDP Recs Tray" ] }, "Preview": { "description": "Campaigns to generate previews for. [Learn more about enabling preview mode](https://dy.dev/docs/preview-api-web#enabling-preview-mode).", "type": "object", "properties": { "ids": { "$ref": "#/components/schemas/Ids" } }, "required": [ "ids" ] }, "Ids": { "description": "Array of preview tokens, as provided in the `dyApiPreview` URL parameter. [Learn more about enabling preview mode](https://dy.dev/docs/preview-api-web#enabling-preview-mode).", "type": "array", "items": { "type": "string" } }, "Args": { "description": "Real-time filters for recommendation results, based on data obtained within the session. Learn more about working with [real-time filters](https://dy.dev/docs/return-real-time-filter-data).", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ArgsItem" } }, "ArgsItem": { "description": "Real-time filter for a single selector. The object key should corresponds to a selector name defined under `selector.names`.", "type": "object", "properties": { "realtimeRules": { "$ref": "#/components/schemas/RealtimeRules" } } }, "RealtimeRules": { "description": "A list of realtime filtering rules.", "type": "array", "items": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/RealtimeRuleType" }, "slots": { "$ref": "#/components/schemas/RealtimeRuleSlots" }, "query": { "$ref": "#/components/schemas/RealtimeRuleQuery" } } } }, "RealtimeRuleType": { "description": "Valid values are: `include`, `exclude`.", "type": "string", "enum": [ "include", "exclude" ] }, "RealtimeRuleSlots": { "description": "All or specific slot positions. The first slot is in position 0.", "type": "array", "items": { "type": "integer" } }, "RealtimeRuleQuery": { "description": "The filtering query.", "type": "object", "properties": { "conditions": { "$ref": "#/components/schemas/QueryConditions" } } }, "QueryConditions": { "description": "The realtime rule's query conditions.", "type": "array", "items": { "type": "object", "properties": { "field": { "$ref": "#/components/schemas/QueryField" }, "arguments": { "$ref": "#/components/schemas/QueryArguments" } }, "required": [ "field", "arguments" ] } }, "QueryField": { "description": "Field within the returned results to apply the query for.", "type": "string", "example": "categories" }, "QueryArguments": { "description": "A list of arguments for a query condition.", "type": "array", "items": { "type": "object", "properties": { "action": { "$ref": "#/components/schemas/QueryAction" }, "value": { "$ref": "#/components/schemas/QueryValue" } }, "required": [ "action", "value" ] } }, "QueryAction": { "description": "Condition types for filtering recommendations. Valid values are: