---
title: "Get Disco Advertiser Recommendations"
method: POST
path: "/recommendations"
tags: ["Recommendations"]
---

# Get Disco Advertiser Recommendations

`POST /recommendations`

## Request

- Base URL: `https://partners.disconetwork.com`
- URL: `https://partners.disconetwork.com/recommendations`
- Auth: API key in header `x-api-key`
- TypeScript: <https://skmtc.dev/disconetwork/apis/external-api-for-disco-integration-partners/docs/recommendations/post.ts> (a function with typed inputs; its response is checked against the schema)

Use the Disco Network advertiser recommendation engine to get the best offers for your customers in post-purchase experiences.

## Headers

- `version` string, required

## Request body

- RecommendationsRequest: The properties shared between the recommendations and event request payloads
  - `user_details` union, required
    - object
      - `email` string, email, required: The email of the shopper, as provided by the shopper
      - `title` 'MR' | 'MRS' | 'MS' | 'MISS': The shopper's preferred title
      - `first_name` string: The first name as provided by the shopper
      - `last_name` string: The last name as provided by the shopper
      - `phone` string: The shopper's phone number
      - `gender` 'MALE' | 'FEMALE' | 'OTHER' | 'UNSPECIFIED': The shopper's specified gender
      - `dob` string: The shopper's date of birth. Format `YYYY-MM-DD`
      - `age` number: The shopper's age
    - object
      - `email_hash` string, required: The shopper's email as a [SHA-256 hash](https://csrc.nist.gov/pubs/fips/180-4/upd1/final)
      - `title` 'MR' | 'MRS' | 'MS' | 'MISS': The shopper's preferred title
      - `first_name` string: The first name as provided by the shopper
      - `last_name` string: The last name as provided by the shopper
      - `phone` string: The shopper's phone number
      - `gender` 'MALE' | 'FEMALE' | 'OTHER' | 'UNSPECIFIED': The shopper's specified gender
      - `dob` string: The shopper's date of birth. Format `YYYY-MM-DD`
      - `age` number: The shopper's age
    - object
      - `phone` string, required: The shopper's phone number
      - `title` 'MR' | 'MRS' | 'MS' | 'MISS': The shopper's preferred title
      - `first_name` string: The first name as provided by the shopper
      - `last_name` string: The last name as provided by the shopper
      - `gender` 'MALE' | 'FEMALE' | 'OTHER' | 'UNSPECIFIED': The shopper's specified gender
      - `dob` string: The shopper's date of birth. Format `YYYY-MM-DD`
      - `age` number: The shopper's age
    - object
      - `external_guid` string, required: The external guid passed by an external source
      - `title` 'MR' | 'MRS' | 'MS' | 'MISS': The shopper's preferred title
      - `first_name` string: The first name as provided by the shopper
      - `last_name` string: The last name as provided by the shopper
      - `phone` string: The shopper's phone number
      - `gender` 'MALE' | 'FEMALE' | 'OTHER' | 'UNSPECIFIED': The shopper's specified gender
      - `dob` string: The shopper's date of birth. Format `YYYY-MM-DD`
      - `age` number: The shopper's age
  - `placement_details` PlacementDetailsObject, required: Contains details about the placement of the offers within the UI
    - `display_mode` 'OVERLAY' | 'FULLSCREEN' | 'PULLUP' | 'INLINE', required: This is the type of display widget used.
    - `layout_id` string: Optional legacy widget selector retained for backward compatibility. Used when widget_id is not provided.
    - `widget_id` string: Optional widget selector. Takes precedence over layout_id.
    - `view` 'ORDER_STATUS' | 'CHECKOUT' | 'THANK_YOU' | 'POST_ORDER' | 'ORDER_TRACKING' | 'SUPPORT_CENTER' | 'REWARDED' | 'EMAIL', required: What kind of view in the purchase flow was the recommendation shown on
    - `sub_view` 'DEFAULT' | 'POST_CLAIM' | 'BOOKING' | 'PURCHASE' | 'BOOKING_AND_PURCHASE': Used to distinguish sub-views for the same page type.
  - `order_details` object: Contains details pertaining the the overall order
    - `cost_details` CostDetailsSummary, required: Contains all details pertaining to the cost of the parent container item
      - `amount` number, float: The full cost of the item
      - `currency_code` string: The [ISO-4217 currency code](https://www.iso.org/iso-4217-currency-codes.html)
    - `order_id` string, required: Unique identifier of the order
    - `payment_type` string: The type of payment used
  - `purchases` ProductSummaryDto[]: List of purchased items
    - `name` string: The name of the product
    - `type` string: Category of the product
    - `variant` object: Variant of the product. (e.g., color, size)
    - `quantity` number: Quantity purchased
    - `description` string: Description of the product.
    - `cost_details` CostDetailsSummary: Contains all details pertaining to the cost of the parent container item
      - `amount` number, float: The full cost of the item
      - `currency_code` string: The [ISO-4217 currency code](https://www.iso.org/iso-4217-currency-codes.html)
    - `product_id` string: Unique identifier for the product
    - `attributes` PurchaseAttributes: Free-form attributes for a purchased item
      - `is_clearance` boolean: Indicates whether this product is a clearance item
      - `is_gift` boolean: Indicates whether this product was purchased as a gift
  - `attributes` object: General properties about the request
    - `user_agent` string: The user_agent, if applicable
    - `device_type` 'MOBILE' | 'TABLET' | 'DESKTOP': The source device of the customer
    - `operating_system` string: The operating system the user is on
    - `operating_system_version` string: The version of the user's operating system
    - `ip_address` string: The IP Address of the shopper
    - `ip_address_hash` string: The [SHA-256 hash](https://csrc.nist.gov/pubs/fips/180-4/upd1/final) of the shopper's IP Address
    - `platform_type` 'MOBILE' | 'WEB': Describes the type of device the shopper was user
    - `language` string: Language associated with the current session. Use a valid [ISO-639](https://www.iso.org/iso-639-language-code) language code.
  - `custom_metadata` object: These are custom fields associated to this partner integration
    - `is_sandbox` boolean: Indicates if this is a sandbox request. If true, associated events will not drive conversions.
    - `is_add_to_order_customer` boolean: Did this customer use the limited time window add-to-order functionality
    - `is_sports_betting_eligible` boolean: Has the user purchased age-gated alcohol and tobacco products
    - `is_fam` boolean: Indicates membership in the partner's subscription program
    - `is_student` boolean: Does this user have a college email address
  - `shipping` AddressRequestDto: The structure of an address in our request bodies
    - `address_line_1` string: The main line of the address
    - `address_line_2` string: The optional line 2 of the address
    - `city` string: The city of the address
    - `state` string: The [USPS 2-Letter State Abbreviation](https://pe.usps.com/text/pub28/28apb.htm) of the address
    - `zip` string: The zipcode of the address
    - `phone` string: The phone number of the user's shipping address, if different than user's main phone number
  - `billing` AddressRequestDto: The structure of an address in our request bodies
    - `address_line_1` string: The main line of the address
    - `address_line_2` string: The optional line 2 of the address
    - `city` string: The city of the address
    - `state` string: The [USPS 2-Letter State Abbreviation](https://pe.usps.com/text/pub28/28apb.htm) of the address
    - `zip` string: The zipcode of the address
    - `phone` string: The phone number of the user's shipping address, if different than user's main phone number
  - `running_experiments` ExperimentSummaryDTO[]: A list of currently running experiments
    - `name` string, required: The name of the current experiment
    - `version` integer, required: The bucket number of the experiment

## Response `200`

The request was successful, and the server has returned the requested resource in the response body.

- RecommendationsResponse: The response body from the recommendations endpoint
  - `session_id` string, uuid, required: Unique identifier used in the Disco system for events
  - `resolved_widget` ResolvedWidget, nullable: Selected widget configuration. Null when unavailable.
    - `widget_id` string, required
    - `layout_id` string, nullable
    - `widget_mode` 'OVERLAY' | 'INLINE' | 'FULLSCREEN' | 'PULLUP', required
    - `widget_type` 'LEAD_GEN' | 'ESSENTIAL' | 'APP_NATIVE_ESSENTIAL' | 'APP_NATIVE_SCROLLABLE' | 'APP_NATIVE_HYBRID' | 'APP_NATIVE_BANNER_VISUAL' | 'APP_NATIVE_BRAND_VISUAL' | 'APP_NATIVE_GALLERY' | 'SHOPIFY_NATIVE_ESSENTIAL' | 'SHOPIFY_NATIVE_LEAD_GEN', required
    - `widget_version` number, float, required
    - `content` object, required
  - `recommendations` object, required: Each element here contains the details for a given offer. The keys here are the offer_id's found in the recommendation_groups.
  - `recommendation_groups` object, required: Ordered groups of offer ids to display. Get details for each offer from recommendations object. By default there will be one group with the key "group_0" with the recommendations you need to power the ad serving experience.
  - `recommendation_group_properties` object: A mapping from recommendation group id to properties describing how to display that group
  - `running_experiments` ExperimentSummaryDTO[]: A list of currently running experiments
    - `name` string, required: The name of the current experiment
    - `version` integer, required: The bucket number of the experiment
  - `footer` object, required: Contains the text, links, and assets needed to display the DiscoNetwork footer.
    - `attribution_details` object, required: Contains text and assets for Disco Network attribution footer
      - `copy` string, required: The copy for the footer, should come before the logo
      - `disco_logo_url` string, uri, required: The url of the disco logo. Should be inline after the footer copy.
      - `target_url` string, uri, required: Disco Network's url
    - `privacy_policy` object, required: Contains the text and link for the disco privacy policy.
      - `copy` string, required: The copy to display for the privacy policy link
      - `target_url` string, uri, required: URL to the page that hosts Disco Network's privacy policy

## Other responses

- `400`: The server could not understand the request due to invalid syntax. The client should modify the request and try again.
- `401`: Authentication is required to access the requested resource. The client must include the appropriate credentials.
- `403`: The server understood the request, but refuses to authorize it. Ensure the client has appropriate permissions.
- `500`: The server encountered an unexpected condition that prevented it from fulfilling the request. Report the issue to the support team if it persists.

---

[API](https://skmtc.dev/disconetwork/apis/external-api-for-disco-integration-partners.md) - [All operations](https://skmtc.dev/disconetwork/apis/external-api-for-disco-integration-partners/llms.txt) - [OpenAPI document](https://skmtc.dev/disconetwork/apis/external-api-for-disco-integration-partners/revisions/6daa87b07a73?raw)