Disco Partner Integration API

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.
servers:
  - url: https://partners.disconetwork.com
    description: Production
  - url: https://partners.disconetwork-staging.com
    description: Staging
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: ""
  /events/batch:
    post:
      tags:
        - Events
      summary: Create a batch of events used to record user actions
      description: Submit between 1 and 20 events in a single request. Each event is
        processed independently and the response reports the per-event result so
        the caller can retry only the events that failed.
      responses:
        "202":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BatchEventResponse"
          description: Every event in the batch was accepted for processing.
        "207":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BatchEventResponse"
          description: Some events were accepted and others failed. Inspect `results`
            to determine which events to retry.
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "403":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "502":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BatchEventResponse"
          description: Every event in the batch failed to be accepted for processing.
            The caller should retry the whole batch.
      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: createABatchOfEventsUsedToRecordUserActions
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BatchEventRequest"
        required: true
        description: An object containing the list of events to record.
  /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'
            - type: object
              title: 'phone'
              allOf:
                - type: object
                  required:
                    - phone
                  properties:
                    phone:
                      type: string
                      description: The phone number of the shopper
                      example: +1 (415) 123-4567
                - $ref: '#/components/schemas/UserDetails'
            - type: object
              title: 'external_guid'
              allOf:
                - type: object
                  required:
                    - external_guid
                  properties:
                    external_guid:
                      type: string
                      description: The external guid passed by an external source
                      example: 9f8b7c6d-1234-5678-9abc-def012345678
                - $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
            device_type:
              type: string
              enum:
                - MOBILE
                - TABLET
                - DESKTOP
              description: The source device of the customer
            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_sandbox:
              type: boolean
              description: Indicates if this is a sandbox request. If true, associated events will not drive conversions.
            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"
        running_experiments:
          type: array
          description: A list of currently running experiments
          items:
            $ref: "#/components/schemas/ExperimentSummaryDTO"
    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
            - FULLSCREEN
            - PULLUP
            - INLINE
        layout_id:
          type: string
          description: >
            Optional legacy widget selector retained for backward
            compatibility.
            Used when widget_id is not provided.
        widget_id:
          type: string
          maxLength: 64
          description: Optional widget selector. Takes precedence over layout_id.
        view:
          type: string
          description: What kind of view in the purchase flow was the recommendation shown
            on
          enum:
            - ORDER_STATUS
            - CHECKOUT
            - THANK_YOU
            - POST_ORDER
            - ORDER_TRACKING
            - SUPPORT_CENTER
            - REWARDED
            - EMAIL
        sub_view:
          type: string
          description: Used to distinguish sub-views for the same page type.
          default: DEFAULT
          enum:
            - DEFAULT
            - POST_CLAIM
            - BOOKING
            - PURCHASE
            - BOOKING_AND_PURCHASE
      required:
        - display_mode
        - view
    ResolvedWidget:
      type: object
      nullable: true
      description: Selected widget configuration. Null when unavailable.
      required:
        - widget_id
        - widget_mode
        - widget_type
        - widget_version
        - content
      properties:
        widget_id:
          type: string
          maxLength: 64
        layout_id:
          type: string
          nullable: true
          maxLength: 64
        widget_mode:
          type: string
          enum:
            - OVERLAY
            - INLINE
            - FULLSCREEN
            - PULLUP
        widget_type:
          type: string
          enum:
            - 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
        widget_version:
          type: number
          format: float
        content:
          type: object
          additionalProperties:
            type: string
            nullable: true
    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
        resolved_widget:
          $ref: "#/components/schemas/ResolvedWidget"
        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
                  description:
                    type: string
                    description: The advertiser's description
              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
                  json_content:
                    type: object
                    additionalProperties: true
                    nullable: true
                    description: The JSON content for this offer. JSON content is a tree of objects that can be used to display the offer in the UI in a flexible way.
                  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:
                        - id
                        - asset_type
                        - insertion_order
                        - image_url
                        - should_trigger_claim_flow
                      properties:
                        id:
                          type: string
                          description: The id of the product/asset being displayed. This will be attached to the click event.
                          example: PROD123
                        asset_type:
                          type: string
                          description: The type of asset being returned.
                          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
                        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.
                        should_trigger_claim_flow:
                          type: boolean
                          description: Whether or not clicking on this asset should trigger a claim.
                  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
                              - BANNER_VISUAL
                              - STACKED_TILE
                              - LAYERED_TILE
                              - PRODUCT_VISUAL
                        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
                              - BANNER_VISUAL
                              - STACKED_TILE
                              - LAYERED_TILE
                              - PRODUCT_VISUAL
                        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. Either `target_url` or `content` will be provided.
                    required:
                      - 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 to further terms and conditions hosted by the
                          advertiser.
                      content:
                        type: string
                        nullable: true
                        description: The terms and conditions content for this offer set by the advertiser.
          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}]}
        recommendation_group_properties:
          type: object
          description: A mapping from recommendation group id to properties describing how to display that group
          additionalProperties:
            type: object
            required:
              - slot_context
            properties:
              heading:
                type: string
                description: The heading of the group
              slot_context:
                type: string
                description: Represents whether the group is a hero or scrollable group, etc.
                enum:
                  - HERO
                  - SCROLLABLE
        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 tri

# --- truncated at 32 KB (42 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/disconetwork/refs/heads/main/openapi/disconetwork-partner-api.yml