openapi: 3.0.0
info:
  title: External API for Disco Integration Partners
  version: 1.0.0
  description: The API used by Disco partners that will provide their own UI experience.
tags:
  - name: recommendations
  - name: events
paths:
  /events:
    post:
      tags:
        - events
      summary: Create an event used to record user actions
      responses:
        "201":
          description: The request was successful, and a new resource was created.
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "403":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalServerError"
      parameters:
        - in: header
          name: version
          description: The version of the api you wish to use
          example: 1.0.0
          style: simple
          schema:
            type: string
          explode: false
          required: true
          allowReserved: false
      operationId: createAnEventUsedToRecordUserActions
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EventRequest"
        required: true
        description: ""
  /recommendations:
    post:
      tags:
        - recommendations
      summary: Get Disco Advertiser Recommendations
      security:
        - ApiKey: []
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RecommendationsResponse"
          description: The request was successful, and the server has returned the
            requested resource in the response body.
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "403":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalServerError"
      parameters:
        - in: header
          name: version
          description: The version of the API you wish to use
          example: 1.0.0
          style: simple
          schema:
            type: string
          explode: false
          required: true
          allowReserved: false
      description: Use the Disco Network advertiser recommendation engine to get the
        best offers for your customers in post-purchase experiences.
      operationId: getDiscoAdvertiserRecommendations
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RecommendationsRequest"
        required: true
        description: The body of the request
components:
  schemas:
    CommonRequestProperties:
      type: object
      description: The properties shared between the recommendations and event request
        payloads
      required:
        - placement_details
        - user_details
      properties:
        user_details:
          oneOf:
            - type: object
              title: 'email'
              allOf:
                - type: object
                  required:
                    - email
                  properties:
                    email:
                      type: string
                      format: email
                      description: The email of the shopper, as provided by the shopper
                      example: michelle@disconetwork.com
                - $ref: '#/components/schemas/UserDetails'
            - type: object
              title: 'email_hash'
              allOf:
                - type: object
                  required:
                    - email_hash
                  properties:
                    email_hash:
                      type: string
                      description: The shopper's email as a [SHA-256 hash](https://csrc.nist.gov/pubs/fips/180-4/upd1/final)
                      example: 211550f0381ba43da1bdbd6acca2deeaaaa9ea5bfacaa2523be92ac1091c7333
                - $ref: '#/components/schemas/UserDetails'
        placement_details:
          $ref: "#/components/schemas/PlacementDetailsObject"
        order_details:
          type: object
          description: Contains details pertaining the the overall order
          properties:
            cost_details:
              $ref: "#/components/schemas/CostDetailsSummary"
            order_id:
              type: string
              description: Unique identifier of the order
            payment_type:
              type: string
              description: The type of payment used
              example: VISA
          required:
            - cost_details
            - order_id
        purchases:
          type: array
          description: List of purchased items
          items:
            $ref: "#/components/schemas/ProductSummaryDto"
        attributes:
          type: object
          description: General properties about the request
          properties:
            user_agent:
              type: string
              description: The user_agent, if applicable
            operating_system:
              type: string
              description: The operating system the user is on
              example: iOS
            operating_system_version:
              type: string
              description: The version of the user's operating system
              example: 18.3.2
            ip_address:
              type: string
              description: The IP Address of the shopper
            ip_address_hash:
              type: string
              description: The [SHA-256 hash](https://csrc.nist.gov/pubs/fips/180-4/upd1/final) of the shopper's IP Address
            platform_type:
              type: string
              description: Describes the type of device the shopper was user
              enum:
                - MOBILE
                - WEB
            language:
              type: string
              description: Language associated with the current session. Use a valid [ISO-639](https://www.iso.org/iso-639-language-code) language code.
        custom_metadata:
          type: object
          description: These are custom fields associated to this partner integration
          properties:
            is_add_to_order_customer:
              type: boolean
              description: Did this customer use the limited time window add-to-order functionality
            is_sports_betting_eligible:
              type: boolean
              description: Has the user purchased age-gated alcohol and tobacco products
            is_fam:
              type: boolean
              description: Is this user a part of Gopuff subscription service
            is_student:
              type: boolean
              description: Does this user have a college email address
        shipping:
          $ref: "#/components/schemas/AddressRequestDto"
        billing:
          $ref: "#/components/schemas/AddressRequestDto"
    UserDetails:
      type: object
      properties:
        title:
          type: string
          description: The shopper's preferred title
          enum:
            - MR
            - MRS
            - MS
            - MISS
        first_name:
          type: string
          description: The first name as provided by the shopper
          example: Monica
        last_name:
          type: string
          description: The last name as provided by the shopper
          example: Stone
        phone:
          type: string
          example: +1 (415) 123-4567
          description: The shopper's phone number
        gender:
          type: string
          description: The shopper's specified gender
          enum:
            - MALE
            - FEMALE
            - OTHER
            - UNSPECIFIED
        dob:
          type: string
          description: The shopper's date of birth. Format `YYYY-MM-DD`
        age:
          type: number
          description: The shopper's age
          minimum: 0
    PlacementDetailsObject:
      type: object
      description: Contains details about the placement of the offers within the UI
      properties:
        display_mode:
          type: string
          description: This is the type of display widget used.
          enum:
            - OVERLAY
            - PULLUP
            - INLINE
        layout_id:
          type: string
          description: "If you make changes to the UI, make sure to version those changes and pass the version in. ie, you may have multiple versions: alpha, 1.0, foobar, etc"
        view:
          type: string
          description: What kind of view in the purchase flow was the recommendation shown
            on
          enum:
            - ORDER_STATUS
            - CHECKOUT
            - THANK_YOU
      required:
        - display_mode
        - layout_type
        - view
    RecommendationsRequest:
      allOf:
        - $ref: "#/components/schemas/CommonRequestProperties"
      description: The body of the request for the /recommendations endpoint
    RecommendationsResponse:
      type: object
      description: The response body from the recommendations endpoint
      required:
        - recommendations
        - recommendation_groups
        - footer
        - session_id
      properties:
        session_id:
          type: string
          format: uuid
          description: Unique identifier used in the Disco system for events
          example: 30576e99-fda5-41bc-b62c-65109ba47147
        recommendations:
          type: object
          description: Each element here contains the details for a given offer. The keys here are the offer_id's found in the recommendation_groups.
          additionalProperties:
            type: object
            required:
              - advertiser
              - offer
            properties:
              advertiser:
                type: object
                description: Contains top-level details about the advertiser for this ad
                  recommendation
                required:
                  - name
                  - logo_url
                  - id
                properties:
                  id:
                    type: string
                    format: uuid
                    example: 30576e99-fda5-41bc-b62c-65109ba47147
                    description: This is the identifier for the advertiser in the Disco Network
                      system.
                  name:
                    type: string
                    example: Marlowe's Roastery
                    description: The advertiser's brand name
                  logo_url:
                    type: string
                    format: uri
                    description: The url of the advertiser logo. You may or may not want to display
                      this, depending on your layout
              offer:
                type: object
                description: Contains details about the offer
                required:
                  - heading
                  - target_url
                  - metadata
                  - cta_details
                  - id
                properties:
                  id:
                    type: string
                    format: uuid
                    description: The id of the recommendation. Will need to be passed back on events
                      for this offer.
                    example: adb0e805-ef67-4083-a2be-0ff3e0b16dce
                  heading:
                    type: string
                    description: The top line header for this offer
                    example: 15% OFF
                  subheading:
                    type: string
                    description: Text to go below the top line heading of the offer
                    example: On your next purchase
                  target_url:
                    type: string
                    format: uri
                    description: The url to take the shopper to when they click on the offer
                    example: https://some-shop.com/collections/hop-shop/products/large-suit
                  cta_details:
                    type: object
                    description: Contains the call-to-action button copies
                    required:
                      - accept_copy
                      - decline_copy
                    properties:
                      accept_copy:
                        type: string
                        description: The positive-response CTA copy
                        example: Claim Offer
                      decline_copy:
                        type: string
                        description: The negative-response CTA copy
                        example: No Thanks
                      transition_copy:
                        type: string
                        description: The CTA copy used during transition to the offer
                        example: Taking you to Marlowe's Roastery
                      claimed_accept_copy:
                        type: string
                        description: The positive-response CTA copy used after an offer is clicked
                        example: Copy code & shop
                      claimed_decline_copy:
                        type: string
                        description: The negative-response CTA copy used after an offer is clicked
                        example: Next offer
                  assets:
                    type: array
                    description: An optional list of assets which can be displayed in your UI
                    items:
                      type: object
                      required:
                        - asset_type
                        - insertion_order
                        - image_url
                      properties:
                        asset_type:
                          type: string
                          description: The type of asset being returned. Product assets are the only ones that need product events to be fired.
                          enum:
                            - PRODUCT
                            - IMAGE
                        image_url:
                          type: string
                          format: uri
                          description: The full url of the hosted image
                        insertion_order:
                          type: integer
                          format: int32
                          description: The order in which you should display each asset in the UI
                          minimum: 0
                          example: 0
                        id:
                          type: string
                          description: The id of the product/asset being displayed. This will be present if the `asset_type` is PRODUCT.
                        target_url:
                          type: string
                          format: uri
                          example: https://www.my-shop.com/
                          description: The url that the user will be taken to if they click this asset. This will be present if the asset is clickable.
                  metadata:
                    oneOf:
                      - type: object
                        title: 'PROMO_CODE'
                        required:
                          - type
                          - code
                          - layout_type
                        properties:
                          code:
                            type: string
                            example: IR3723
                            description: The promo code for an offer, provided by the advertiser
                          type:
                            enum:
                              - PROMO_CODE
                            type: string
                            description: Indicates the type of ad. `promo_code` indicates that a
                              promo_code field is provided
                          layout_type:
                            type: string
                            description: The intended display format for this ad. Use this property to help determine the layout of the parts of the offer such as text, image, links, etc.
                            enum:
                              - TEXT_RICH
                              - BRAND_VISUAL
                              - FEATURED_IMAGE
                        description: An object containing a promo code
                      - type: object
                        title: 'NO_PROMO_CODE'
                        required:
                          - type
                          - layout_type
                        properties:
                          type:
                            enum:
                              - NO_PROMO_CODE
                            type: string
                            description: Indicates the type of ad. `no_promo_code` indicates that a
                              promo_code does not exist
                          layout_type:
                            type: string
                            description: The intended display format for this ad. Use this property to help determine the layout of the parts of the offer such as text, image, links, etc.
                            enum:
                              - TEXT_RICH
                              - BRAND_VISUAL
                              - FEATURED_IMAGE
                        description: an object without a promo code
                  disclosure_details:
                    type: object
                    description: Contains details about the term & conditions for an offer set by
                      the advertiser. Should be displayed in a popup
                    required:
                      - copy
                      - target_url
                      - close_button_copy
                      - more_button_copy
                    properties:
                      copy:
                        type: string
                        description: The full text body of the disclosure set by the advertiser
                      target_url:
                        type: string
                        format: uri
                        example: https://www.your-site.com/terms-and-conditions
                        description: An optional link further terms and conditions hosted by the
                          advertiser.
                      more_button_copy:
                        type: string
                        example: Learn More
                        description: The copy to use on the button for further terms and conditions
                      close_button_copy:
                        type: string
                        example: Close
                        description: The copy to use for the close button of the disclosure popup
          example: {7c2d0ba1-9c53-4032-824d-72e49850ecc6: {advertiser: {}, offer: {}}}
        recommendation_groups:
          type: object
          description: 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.
          additionalProperties:
            type: array
            items:
              type: object
              required:
                - insertion_order
                - insertion_id
                - offer_id
                - advertiser_id
              properties:
                insertion_order:
                  type: integer
                  format: int32
                  description: The order in which you should display this recommendation
                  minimum: 0
                  example: 1
                insertion_id:
                  type: string
                  description: This identifier helps Disco identify the effectiveness of each
                    recommendation, and needs to be passed in future event
                    payloads.
                  example: 827d0-eniu29dbnf92
                offer_id:
                  type: string
                  description: The id of the offer to show in this slot. This is the key you will use to lookup details in recommendations.
                advertiser_id:
                  type: string
                  description: The id of the advertiser listing the offer in this slot
          example: {group_0: [{insertion_order: 0, insertion_id: "827d0-eniu29dbnf92", offer_id: 7c2d0ba1-9c53-4032-824d-72e49850ecc6, advertiser_id: 6d3f8745-9fde-47be-91fa-fbe09870f997}]}
        running_experiments:
          type: array
          description: A list of currently running experiments
          items:
            $ref: "#/components/schemas/ExperimentSummaryDTO"
        footer:
          type: object
          description: Contains the text, links, and assets needed to display the
            DiscoNetwork footer.
          required:
            - attribution_details
            - privacy_policy
          properties:
            attribution_details:
              type: object
              description: Contains text and assets for Disco Network attribution footer
              required:
                - copy
                - disco_logo_url
                - target_url
              properties:
                copy:
                  type: string
                  description: The copy for the footer, should come before the logo
                  example: Powered by
                disco_logo_url:
                  type: string
                  format: uri
                  description: The url of the disco logo. Should be inline after the footer copy.
                  example: https://launcher.disconetwork.com/static/media/disco-logo-gray.01a8140f2bc1b025de45ba9950bc6341.svg
                target_url:
                  type: string
                  format: uri
                  description: Disco Network's url
                  example: https://disconetwork.com
            privacy_policy:
              type: object
              description: Contains the text and link for the disco privacy policy.
              required:
                - copy
                - target_url
              properties:
                copy:
                  type: string
                  description: The copy to display for the privacy policy link
                  example: Privacy Policy
                target_url:
                  type: string
                  format: uri
                  description: URL to the page that hosts Disco Network's privacy policy
                  example: https://www.disconetwork.com/privacy-policy
    BaseEventProperties:
      type: object
      description: The properties shared on all events
      required:
        - event_name
        - event_datetime
        - session_id
      properties:
        event_name:
          enum:
            - WIDGET_LOAD
            - WIDGET_DISPLAY
            - WIDGET_VIEW
            - BRAND_DISPLAY
            - BRAND_VIEW
            - BRAND_CLICK
            - PRODUCT_DISPLAY
            - PRODUCT_VIEW
            - PRODUCT_CLICK
            - ELEMENT_CLICK
          type: string
          description: The name of the event you are sending to Disco. Casing must be all
            caps
        event_datetime:
          type: string
          format: date-time
          description: The [RFC-3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) datetime at which the event occurred on the shopper's device
          example: 2025-03-21T17:32:28Z
        session_id:
          type: string
          format: uuid
          description: An identifier provided on the response of the recommendations
            endpoint to identify the session associated with the event
          example: 70f05c32-7760-4753-93c9-b759cf7e7fda
      discriminator:
        propertyName: event_name
    BrandEventProperties:
      type: object
      required:
        - offer_id
        - advertiser_id
        - insertion_id
      properties:
        offer_id:
          type: string
          format: uuid
          description: Unique identifier of the offer this event is being sent for
          example: 955a3fcb-a264-4bce-a65a-0a2f1216627f
        advertiser_id:
          type: string
          format: uuid
          description: Unique identifier of the advertiser this event is being sent for
          example: 98b5ecf0-9902-4034-ad43-1b13f7db7d7f
        insertion_id:
          type: string
          description: Unique identifier associated with this advertiser provided from the
            recommendations endpoint
          example: 827d0-eniu29dbnf92
    RequiredBrandEventProperties:
      type: object
      required:
        - brand_properties
      properties:
        brand_properties:
          allOf:
            - $ref: "#/components/schemas/BrandEventProperties"

    ProductEventProperties:
      type: object
      required:
        - product_properties
      properties:
        product_properties:
          type: object
          required:
            - product_id
          properties:
            product_id:
              type: string
              description: Unique asset identifier of the product asset that was displayed
              example: PROD123
    WidgetEventRequest:
      title: WidgetEventRequest
      allOf:
        - $ref: "#/components/schemas/BaseEventProperties"
    BrandDisplayRequest:
      title: BrandDisplayRequest
      allOf:
        - $ref: "#/components/schemas/BaseEventProperties"
        - type: object
          required:
            - initiating_target
          properties:
            initiating_target:
              type: string
              description: Indicates the UI element that triggered this event
              enum:
                - INLINE_SLOT
        - $ref: "#/components/schemas/RequiredBrandEventProperties"
    BrandClickRequest:
      title: BrandClickRequest
      allOf:
        - $ref: "#/components/schemas/BaseEventProperties"
        - type: object
          required:
            - initiating_target
          properties:
            initiating_target:
              type: string
              description: Indicates the UI element that triggered this event
              enum:
                - INLINE_ACTION_BUTTON
        - $ref: "#/components/schemas/RequiredBrandEventProperties"
    ProductDisplayRequest:
      title: ProductDisplayRequest
      allOf:
        - $ref: "#/components/schemas/BaseEventProperties"
        - type: object
          required:
            - initiating_target
          properties:
            initiating_target:
              type: string
              description: Indicates the UI element that triggered this event
              enum:
                - INLINE_TILE
        - $ref: "#/components/schemas/RequiredBrandEventProperties"
        - $ref: "#/components/schemas/ProductEventProperties"
    ProductClickRequest:
      title: ProductClickRequest
      allOf:
        - $ref: "#/components/schemas/BaseEventProperties"
        - $ref: "#/components/schemas/RequiredBrandEventProperties"
        - $ref: "#/components/schemas/ProductEventProperties"
        - type: object
          required:
            - initiating_target
          properties:
            initiating_target:
              type: string
              description: Indicates the UI element that triggered this event
              enum:
                - INLINE_TILE
    ElementClickRequest:
      title: ElementClickRequest
      allOf:
        - $ref: "#/components/schemas/BaseEventProperties"
        - type: object
          required:
            - initiating_target
          properties:
            initiating_target:
              type: string
              description: Indicates the UI element that triggered this event
              enum:
                - INLINE_NAV_FORWARD
                - INLINE_NAV_BACKWARD
                - INLINE_FOOTER_DISCO
                - INLINE_FOOTER_PRIVACY
        - type: object
          properties:
            brand_properties:
              description: This is required for `INLINE_NAV_FORWARD/BACKWARD` initiating targets
              allOf:
                - $ref: "#/components/schemas/BrandEventProperties"
    EventRequest:
      oneOf:
        - $ref: "#/components/schemas/WidgetEventRequest"
        - $ref: "#/components/schemas/ElementClickRequest"
        - $ref: "#/components/schemas/BrandDisplayRequest"
        - $ref: "#/components/schemas/BrandClickRequest"
        - $ref: "#/components/schemas/ProductDisplayRequest"
        - $ref: "#/components/schemas/ProductClickRequest"
      description: Request body for hitting the /event endpoint
      discriminator:
        propertyName: event_name
        mapping:
          WIDGET_LOAD: "#/components/schemas/WidgetEventRequest"
          WIDGET_DISPLAY: "#/components/schemas/WidgetEventRequest"
          WIDGET_VIEW: "#/components/schemas/WidgetEventRequest"
          BRAND_DISPLAY: "#/components/schemas/BrandDisplayRequest"
          BRAND_VIEW: "#/components/schemas/BrandDisplayRequest"
          BRAND_CLICK: "#/components/schemas/BrandClickRequest"
          PRODUCT_DISPLAY: "#/components/schemas/ProductDisplayRequest"
          PRODUCT_VIEW: "#/components/schemas/ProductDisplayRequest"
          PRODUCT_CLICK: "#/components/schemas/ProductClickRequest"
          ELEMENT_CLICK: "#/components/schemas/ElementClickRequest"
    AddressRequestDto:
      type: object
      description: The structure of an address in our request bodies
      required: []
      properties:
        address_line_1:
          type: string
          description: The main line of the address
          example: 431 Main St.
        address_line_2:
          type: string
          description: The optional line 2 of the address
          example: Suite 2A
        city:
          type: string
          description: The city of the address
          example: Miami
        state:
          type: string
          description: The [USPS 2-Letter State
            Abbreviation](https://pe.usps.com/text/pub28/28apb.htm) of the
            address
          example: FL
        zip:
          type: string
          description: The zipcode of the address
          example: 45231
        phone:
          type: string
          description: The phone number of the user's shipping address, if different than
            user's main phone number
          example: +1 (415) 123-4567
    ProductSummaryDto:
      type: object
      description: A description of a purchased item, to be provided in our requests
      properties:
        name:
          type: string
          description: The name of the product
        type:
          type: string
          description: Category of the product
          example: Electronics
        variant:
          type: object
          additionalProperties:
            type: string
            example:
              color: Black
              size: Large
          description: Variant of the product. (e.g., color, size)
        quantity:
          type: number
          minimum: 0
          description: Quantity purchased
          example: "2"
        description:
          type: string
          description: Description of the product.
          example: Noise-cancelling headphones
        cost_details:
          $ref: "#/components/schemas/CostDetailsSummary"
        product_id:
          type: string
          description: Unique identifier for the product
    ExperimentSummaryDTO:
      type: object
      description: Properties describing an actively running product experiment
      required:
        - name
        - version
      properties:
        name:
          type: string
          description: The name of the current experiment
          example:  optimization_04
        version:
          type: string
          description: The a/b bucket value for this request
          enum:
            - CONTROL_BUCKET
            - TEST_BUCKET
    CostDetailsSummary:
      type: object
      properties:
        amount:
          type: string
          description: The full cost of the item
          example: 100.00
        currency_code:
          type: string
          description: The [ISO-4217 currency
            code](https://www.iso.org/iso-4217-currency-codes.html)
          example: USD
      required:
        - amount
        - currency_code
      description: Contains all details pertaining to the cost of the parent container item
  responses:
    Unauthenticated:
      description: Authentication is required to access the requested resource. The
        client must include the appropriate credentials.
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
            required:
              - message
    Unauthorized:
      description: The server understood the request, but refuses to authorize it.
        Ensure the client has appropriate permissions.
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
            required:
              - message
    NotFound:
      content:
        application/json:
          schema:
            type: object
            required:
              - message
            properties:
              message:
                type: string
      description: The server cannot find the requested resource. The endpoint may be
        invalid or the resource may no longer exist.
    BadRequest:
      content:
        application/json:
          schema:
            type: object
            required:
              - message
            properties:
              errors:
                type: array
                items:
                  type: object
                  required:
                    - message
                  properties:
                    message:
                      type: string
              message:
                type: string
      description: The server could not understand the request due to invalid syntax.
        The client should modify the request and try again.
    InternalServerError:
      content:
        application/json:
          schema:
            type: object
            required:
              - message
            properties:
              message:
                type: string
      description: The server encountered an unexpected condition that prevented it
        from fulfilling the request. Report the issue to the support team if it
        persists.
  parameters: {}
  securitySchemes:
    ApiKey:
      in: header
      name: x-api-key
      type: apiKey
      description: "Key Auth: Requests contain a valid `x-api-key` in the request headers."
