Flipp (Wishabi) Publications API

openapi: 3.2.0
info:
  version: '4.0'
  title: FlyerKit Publications API
  description: 'An API to access Flipp''s publication data for use in your applications.


    ### Overview


    The FlyerKit API gives retailers like yourself access to the structured data that powers the Flipp circular platform. With this API, Flipp empowers you and your teams to create new experiences for your web properties and applications. The FlyerKit API allows you to integrate your circular data by creating custom promotions and integrations (modules, search, emails, menus, etc.) with the goal of increasing circular readership.


    For example, you could integrate items from your circular directly into an email campaign or display thumbnails of your most popular items from across your publications as part of a module on a landing page.

    When used in conjunction with the FlyerKit mobile application SDKs (available for both Android and iOS), the FlyerKit API can be used to create a circular browsing experience within your native application.


    This document is primarily created for development and product teams as a technical reference, but can be used by individuals with expertise in digital marketing, e-commerce and information technology to gain a high level overview of FlyerKit API capabilities and functionality.


    ### Changes from FlyerKit v3.0


    * Updated the access token model, allowing retailers to have multiple FlyerKit access tokens with different levels of permission.

    NOTE: access tokens from previous FlyerKit versions will no longer work in v4.0 and new ones will need to be issued by your Flipp technical contact.


    * Added the ability to view future publications and products which are not yet live. This requires an access token with special permissions issued by your Flipp technical contact.


    * Added the ability to filter products by keywords and/or tags in all product endpoints.


    * Changed the `category` field returned in item models from a string to an array containing all of the item''s categories and renamed it `categories`.


    * Created a new endpoint `/flyerkit/v4.0/publications/{merchant_identifier}/products` which returns products across all of a retailer''s publications.


    * Added deep_link url field to publications and product endpoints. These new fields will return a direct link to a publication or item on a retailer''s page.


    ### Access Token Management


    Access tokens are issued by your Flipp technical contact and if needed, multiple access tokens can be created for your various development teams or partners. Access tokens should always be kept secret and not shared.


    Access tokens are passed to the FlyerKit API as URL parameters.


    ### Supported Formats


    ##### JSON


    The FlyerKit API currently only returns data in JSON format. Example responses are provided for each of the FlyerKit endpoints.


    ### Versioning


    FlyerKit uses a semantic versioning scheme with a major and minor version number. Requests are made against a major version as part of the base path in the URI. All backward compatible changes will be made in minor versions. Clients will not be able to request a specific minor version as the server will always serve the latest version for a major release.


    Any changes in the API that are not backward compatible will use an updated major version.

    '
servers:
- url: https://api.flipp.com/flyerkit/v4.0
tags:
- name: publications
paths:
  /publications/{merchant_identifier}:
    get:
      summary: Find publications by merchant and store or postal/zip code
      description: Returns a list of available publications for a given store and optionally postal/zip code. Publications are selected using the supplied store's location. The validity dates of a publication specify the period for which the content (sales, pricing, etc.) is valid. The availability dates specify the time that the publication should be accessible within an application.The sort order depends on order that should be manually set up on 'Flyers sorting' tab in Fadmin
      tags:
      - publications
      parameters:
      - name: merchant_identifier
        in: path
        description: Your merchant name identifier which can be obtained from your Flipp technical contact.
        required: true
        schema:
          type: string
      - name: access_token
        in: query
        description: Contact your Flipp technical contact for your API access token.
        required: true
        schema:
          type: string
      - name: locale
        in: query
        description: 'Providing a locale will return content from that locale''s language whenever Flipp has that content available. Content includes the underlying circular, as well as categories.

          When localized content is not available for a given locale, an empty response is returned.

          | Locale              | Description                                               |

          | ------------------- | --------------------------------------------------------- |

          | en-CA               | English, Canada                                           |

          | fr-CA               | French, Canada                                            |

          | en-US               | English, United States                                    |

          '
        required: true
        schema:
          type: string
      - name: store_code
        in: query
        description: Retailer's store code.
        schema:
          type: string
      - name: postal_code
        in: query
        description: Optional if store_code is provided. Values can be a Canadian postal code, or a United States zipcode.
        schema:
          type: string
      - name: see_future
        in: query
        description: Whether to include future publications in the results. Requires special access token permissions.
        schema:
          type: boolean
      - name: show_storefronts
        in: query
        description: Show Digital Content. If true will suppress publications that are not optimized for vertical scroll. If false will suppress digital only content. Default is false.
        schema:
          type: boolean
      responses:
        '200':
          description: Publications response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/publication'
        '422':
          description: Missing or invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
  /publication/{publication_id}/pages:
    get:
      summary: Returns pages in a publication
      description: Returns the list of pages in the given publication.The width of the thumbnails in the response may vary to preserve image aspect ratios.
      tags:
      - publications
      parameters:
      - name: publication_id
        in: path
        description: Unique identifier for the publication.
        required: true
        schema:
          type: integer
      - name: access_token
        in: query
        description: Contact your Flipp technical contact for your API access token.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Pages response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/publication_page'
        '422':
          description: Missing or invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
  /publication/{publication_id}/highlights:
    get:
      summary: Returns highlights in a publication
      description: Returns the list of highlights in the given publication. Highlights are special tags given to items which allow them to be highlighted on the front end by darkening the surrounding items/areas of the publication. For example, some merchants like all items made in the USA to be given a "Made in USA" highlight.
      tags:
      - publications
      parameters:
      - name: publication_id
        in: path
        description: Unique identifier for the publication.
        required: true
        schema:
          type: integer
      - name: access_token
        in: query
        description: Contact your Flipp technical contact for your API access token.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Highlights response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/publication_highlight'
        '422':
          description: Missing or invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
  /publication/{publication_id}/categories:
    get:
      summary: Returns categories in a publication
      description: Returns the list of categories in the given publication. The categories can be used to implement a feature that jumps to a specific category in the publication. For example, if the publication has a grocery section, then the grocery category would be used to scroll to the start of the grocery section.
      tags:
      - publications
      parameters:
      - name: publication_id
        in: path
        description: Unique identifier for the publication.
        required: true
        schema:
          type: integer
      - name: access_token
        in: query
        description: Contact your Flipp technical contact for your API access token.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Categories response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/publication_category'
        '422':
          description: Missing or invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
  /publication/{publication_id}/products:
    get:
      summary: Returns products in a publication
      description: For a given publication ID, returns a list of products in the publication. The products in the response are sorted by position, from first page to last, then top to bottom, then left to right by default.Text will be localized according to the locale of the publication. If keywords or tags are provided, a maximum of 1000 items will be returned.
      tags:
      - publications
      parameters:
      - name: publication_id
        in: path
        description: Unique identifier for the publication.
        required: true
        schema:
          type: integer
      - name: access_token
        in: query
        description: Contact your Flipp technical contact for your API access token.
        required: true
        schema:
          type: string
      - name: page
        in: query
        description: Limit products to those appearing on a specified page in the circular.
        schema:
          type: integer
      - name: display_type
        in: query
        description: 'Comma-delimited list of integers specifying types of circular items to return.

          If not provided, this endpoint will only return items with a display type of 1.

          See table below for a list of display types.

          | Display Type Number | Description                                               |

          | ------------------- | --------------------------------------------------------- |

          | 1                   | Circular item                                             |

          | 3                   | Video (YouTube embedded URL or link to mp4 file)          |

          | 5                   | Web linkout (link to external site)                       |

          | 7                   | Circular page link (link to another page in the circular) |

          | 15                  | iframe (displays a URL in an iframe)                      |

          | 25                  | Coupon (retailer coupon displayed as a circular item)     |

          | all                 | All items regardless of type                              |

          '
        schema:
          type: string
      - name: postal_code
        in: query
        description: Postal/zip code to specify the region from which to fetch coupons.
        schema:
          type: string
      - name: store_code
        in: query
        description: Store code required for deep_link of the product.
        schema:
          type: string
      - name: keywords
        in: query
        description: Comma-delimited list of keywords appearing in item names/descriptions with which to filter items.
        schema:
          type: string
      - name: tags
        in: query
        description: Text strings that allow items to be filtered based on more detailed groupings/categorizations. Ask your Flipp Technical contact for more details on how to provide tags against your items.
        schema:
          type: string
      - name: sort_by
        in: query
        description: "Return items sorted by a specified criterion. Supported sort criteria are listed in the table below.\n| Sort criterion      | Description                                               |\n| ------------------- | --------------------------------------------------------- |\n| popularity          | Orders items based on the running total of clicks that\nshoppers have made on the items in the current circular.\nItem click counts are updated at least twice per day.\n                                 |\n"
        schema:
          type: string
      - name: sort_order
        in: query
        description: 'When used with sort_by, determines the order in which items are sorted by the specified criterion.

          | Sort order          | Description                                               |

          | ------------------- | --------------------------------------------------------- |

          | asc                 | Sort items in ascending order.                            |

          | desc                | Sort items in descending order (default).                 |

          '
        schema:
          type: string
      - name: category
        in: query
        description: Filter products by given category.
        schema:
          type: string
      - name: size
        in: query
        description: Set the count of products to be returned. Positive number. All products will be returned if size >= total products count and offset = 0 or missing. [] is returned if there are no products available.
        schema:
          type: integer
      - name: offset
        in: query
        description: Set the count of items to be skipped when size parameter is specified. 0 is a default value. [] is returned if offset is too big.
        schema:
          type: integer
      responses:
        '200':
          description: Products response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/product'
        '422':
          description: Missing or invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
components:
  schemas:
    product:
      properties:
        id:
          type: integer
          description: Unique identifier for the product
          example: 7775353
        flyer_id:
          type: integer
          description: Flyer ID to which the product belongs
          example: 47524
        flyer_run_id:
          type: integer
          description: Identifier for the circular
          example: 8329
        name:
          type: string
          description: Localized product name
          example: Celestial Series Countertops
        deep_link:
          type:
          - string
          - 'null'
          description: Link to a flyer item on the merchant's website. Requires store_code. Publication must be live.
          example: http://retailersite.com?flyer_type_name=weekly&flyer_run=1984&store_code=1984&flyer_item_id=1234
        sale_story:
          type:
          - string
          - 'null'
          description: Localized news story for the product
          example: SPECIAL 60% OFF
        current_price:
          type:
          - float
          - 'null'
          description: The current price for the product
          example: 19.99
        original_price:
          type:
          - float
          - 'null'
          description: The original price for the product
          example: 34.99
        dollars_off:
          type:
          - float
          - 'null'
          description: The advertised number of dollars off
          example: 240.01
        percent_off:
          type:
          - float
          - 'null'
          description: The advertised percent savings
          example: 69.01
        sku:
          type:
          - string
          - 'null'
          description: The product stock keeping unit
          example: 780-4069
        custom_id_field_1:
          type:
          - string
          - 'null'
          description: Field used by merchants to store custom info
          example: 0081341P
        custom_id_field_2:
          type:
          - string
          - 'null'
          description: Field used by merchants to store custom info
          example: '# BONUS Reward Miles when you buy 1'
        custom_id_field_3:
          type:
          - string
          - 'null'
          description: Field used by merchants to store custom info
          example: $0.75
        description:
          type:
          - string
          - 'null'
          description: Localized text describing the product
          example: From Michael Michael Kors in tan or black.
        brand:
          type: string
          description: The brand of the product
          example: Corinthian
        pre_price_text:
          type: string
          description: Localized text to place before price_text
          example: '2 for '
        price_text:
          type: string
          description: Localized text for the price
          example: '5.47'
        post_price_text:
          type: string
          description: Localized text to place after price_text
          example: CAD
        valid_from:
          type:
          - date
          - 'null'
          description: Start of the product's validity period
          example: '2014-01-01'
        valid_to:
          type:
          - date
          - 'null'
          description: End of the product's validity period
          example: '2015-12-31'
        categories:
          type:
          - array
          - 'null'
          description: The categories of the product
          items:
            type: string
          example:
          - Kitchen
        current_price_range:
          type:
          - string
          - 'null'
          description: Localized text of the product price range
          example: $130 - $150
        original_price_range:
          type:
          - string
          - 'null'
          description: Localized text of the original range
          example: $130 - $150
        small_image_url:
          type:
          - string
          - 'null'
          description: URL of a small image of the product
          example: https://cdn.flippenterprise.net/flyer_items/7775353/1373462007/standard.jpg
        medium_image_url:
          type:
          - string
          - 'null'
          description: URL of a medium image of the product
          example: https://cdn.flippenterprise.net/flyer_items/7775353/1373462007/large.jpg
        large_image_url:
          type:
          - string
          - 'null'
          description: URL of a large image of the product
          example: https://cdn.flippenterprise.net/flyer_items/7775353/1373462007/plus_large.jpg
        x_large_image_url:
          type:
          - string
          - 'null'
          description: URL of a very large image of the product
          example: https://cdn.flippenterprise.net/flyer_items/7775353/1373462007/extra_large.jpg
        left:
          type:
          - float
          - 'null'
          description: The left coordinate of the product's bounding box
          example: 3990.63
        top:
          type:
          - float
          - 'null'
          description: The top coordinate of the product's bounding box
          example: 1652.96
        width:
          type: float
          description: The width of the product's bounding box
          example: 1294.6899999999996
        height:
          type: float
          description: The height of the product's bounding box
          example: 857.8000000000002
        item_type:
          type:
          - integer
          - 'null'
          description: Display type of the circular item
          example: 1
        page:
          type: integer
          description: Page the item is on
          example: 3
        page_width:
          type: float
          description: Page width
          example: 1978
        page_height:
          type: float
          description: Page height
          example: 2560
        page_relative_left_offset:
          type:
          - float
          - 'null'
          description: Relative left offset of page
          example: 34.63000000000011
        page_relative_top_offset:
          type:
          - float
          - 'null'
          description: Relative top offset of page
          example: 1652.96
        average_rating:
          type:
          - integer
          - 'null'
          description: Average rating of item
          example: 4.8
        images:
          type: array
          description: Array of product image URLs
          items:
            type: string
          example:
          - https://cdn.flippenterprise.net/flyer_items/7775353/1373462007/extra_large.jpg
        video_type:
          type:
          - integer
          - 'null'
          description: 'Type of video: 0 is youtube embedded; 1 is mp4 URL'
          example: 1
        video_url:
          type:
          - string
          - 'null'
          description: Video of product
          example: https://www.youtube.com/watch?v=y03MqvSExy4&list=PLn2kV0B9P4xeaE1uTelWyQhFQe8Wlbkz3&index=36&rel=0
        web_url:
          type:
          - string
          - 'null'
          description: Link to the external item page
          example: https://www.jcpenney.com/for-the-home/shop-departments/kitchen-dining/shop-kitchen/small-appliances/kitchen-aid/stand-mixers/_/N-1nohrcZ60Z1z141ux/cat.jump?id=cat100240104&deptId=dept20000011&subcatId=cat100240016
        web_commission_url:
          type:
          - string
          - 'null'
          description: Link to the external item page with tracking codes
          example: http://www.homedepot.com/webapp/wcs/stores/servlet/BuildLinkToHomeDepot?linktype=product&id=202193246&cm_sp=1hdcom2online_catalog-_-product_feed-_-D30X-_-202193246&site=wishabi|hd
        hosted_coupon_image:
          type:
          - string
          - 'null'
          description: Image of coupon for hosted experiences
          example: https://cdn.flippenterprise.net/flyer_items/7775353/1373462007/extra_large.jpg
        distribution_coupon_image:
          type:
          - string
          - 'null'
          description: Image of coupon for distribution experiences
          example: https://cdn.flippenterprise.net/flyer_items/7775353/1373462007/extra_large.jpg
        page_destination:
          type:
          - integer
          - 'null'
          description: Number of page that the item points to
          example: 26
        coupons:
          type: array
          description: Array of coupons for the item
          items:
            $ref: '#/components/schemas/product_coupon'
        sub_items:
          type: array
          description: Array of subitems for the item
          items:
            $ref: '#/components/schemas/sub_item'
    publication_page:
      properties:
        page:
          type: integer
          description: The page number, beginning at 1
          example: 1
        flyer_id:
          type: integer
          description: The flyer ID of the page
          example: 348864
        flyer_run_id:
          type: integer
          description: The flyer run ID of the page
          example: 47315
        image_150h_url:
          type:
          - string
          - 'null'
          description: URL of page thumbnail 150 pixels high
          example: https://cdn.flippenterprise.net/sub_pages/thumbnail/60106d22-5b09-11e5-b5bd-22000bb3a4ba/thumbnail_image_150h_s3_key
        image_400h_url:
          type:
          - string
          - 'null'
          description: URL of page thumbnail 400 pixels high
          example: https://cdn.flippenterprise.net/sub_pages/thumbnail/60106d22-5b09-11e5-b5bd-22000bb3a4ba/thumbnail_image_400h_s3_key
        image_2000h_url:
          type:
          - string
          - 'null'
          description: URL of page thumbnail 2000 pixels high
          example: https://cdn.flippenterprise.net/sub_pages/thumbnail/60106d22-5b09-11e5-b5bd-22000bb3a4ba/thumbnail_image_xlarge_s3_key
        left:
          type:
          - float
          - 'null'
          description: The left coordinate of the page's bounding box
          example: 0.0
        top:
          type:
          - float
          - 'null'
          description: The top coordinate of the page's bounding box
          example: 0.0
        width:
          type: float
          description: The width of the page's bounding box
          example: 2560.0
        height:
          type: float
          description: The height of the page's bounding box
          example: 2560.0
    correction_notice:
      properties:
        html:
          type: string
          description: HTML content of the correction notice
          example: <p>Correction</p>
        image_url:
          type:
          - string
          - 'null'
          description: Image associated with the correction notice
          example: https://cdn.flippenterprise.net/flyers/348864/correction/1232923480.jpg
    publication_highlight:
      properties:
        name:
          type: string
          description: The name of the highlight
          example: Grocery Aisle
        left:
          type:
          - float
          - 'null'
          description: The left coordinate of the highlight's bounding box
          example: 10169.2
        top:
          type:
          - float
          - 'null'
          description: The top coordinate of the highlight's bounding box
          example: 1989.54
        width:
          type: float
          description: The width of the highlight's bounding box
          example: 556.5
        height:
          type: float
          description: The height of the highlight's bounding box
          example: 469.6700000000001
    publication:
      properties:
        id:
          type: integer
          description: Unique identifier for the publication
          example: 348864
        flyer_run_id:
          type: integer
          description: ID for the circular
          example: 47315
        flyer_type_id:
          type: integer
          description: Unique identifier for the type of circular
          example: 12234
        name:
          type: string
          description: Localized publication name
          example: Mailer
        description:
          type:
          - string
          - 'null'
          description: Label given to publication by retailer
          example: Tribune Ad
        sfml_url:
          type:
          - string
          - 'null'
          description: Storefront Payload URL
          example: https://sfml.flippback.com/587807/3433653/22811814cd2e63f0c8b92f53fc5193f9831bf4103e7e2efff5c74680648f1ce4.sfml
        storefront_payload_url:
          type:
          - string
          - 'null'
          description: Storefront Payload URL
          example: https://cdn-gateflipp.flippback.com/storefront-hosted/587807/3433653/22811814cd2e63f0c8b92f53fc5193f9831bf4103e7e2efff5c74680648f1ce4?merchant_id=543&store_id=12345
        storefront_payload:
          type:
          - string
          - 'null'
          description: Storefront Payload
          example: https://cdn-gateflipp.flippback.com/storefront-payload/587807/3433653/22811814cd2e63f0c8b92f53fc5193f9831bf4103e7e2efff5c74680648f1ce4?merchant_id=543
        deep_link:
          type:
          - string
          - 'null'
          description: Link to the publication on the merchant's website. Requires store_code. Publication must be live.
          example: http://retailersite.com?flyer_type_name=weekly&flyer_run=1984&store_code=1984
        flyer_type:
          type:
          - string
          - 'null'
          description: Flipp's name identifier of the type of circular
          example: mailer
        total_pages:
          type: integer
          description: Number of pages in the flyer
          example: 9
        external_display_name:
          type:
          - string
          - 'null'
          description: Localized publication external display name
          example: Mailer
        locale:
          type: locale
          description: The publication's locale
          example: en
        postal_code:
          type:
          - string
          - 'null'
          description: The given postal/zip code of given store
          example: 07866
        valid_from:
          type:
          - date
          - 'null'
          description: The start of the validity period
          example: '2015-03-16T00:00:00-04:00'
        valid_to:
          type:
          - date
          - 'null'
          description: The end of the validity period
          example: '2016-01-30T23:59:00-05:00'
        available_from:
          type:
          - date
          - 'null'
          description: The start of the availability period
          example: '2015-03-16T01:00:00-04:00'
        available_to:
          type:
          - date
          - 'null'
          description: The end of the availability period
          example: '2016-01-31T00:59:00-05:00'
        thumbnail_image_url:
          type:
          - string
          - 'null'
          description: A thumbnail image intended for a listing
          example: https://cdn.flippenterprise.net/flyers/348864/l_thumbnail/1425009356.jpg
        flyer_selector_thumbnail_url:
          type:
          - string
          - 'null'
          description: URL links to the flyer selector image used on hosted desktop
          example: https://cdn.flippenterprise.net/flyers/348864/thumbnail/1425009356.jpg
        first_page_thumbnail_url:
          type:
          - string
          - 'null'
          description: The first page thumbnail of the circular (height 2000px)
          example: https://cdn.flippenterprise.net/sub_pages/thumbnail/60106d22-5b09-11e5-b5bd-22000bb3a4ba/thumbnail_image_xlarge_s3_key
        first_page_thumbnail_150h_url:
          type:
          - string
          - 'null'
          description: The first page thumbnail of the circular (height 150px)
          example: https://cdn.flippenterprise.net/sub_pages/thumbnail/60106d22-5b09-11e5-b5bd-22000bb3a4ba/thumbnail_image_150h_s3_key
        first_page_thumbnail_400h_url:
          type:
          - string
          - 'null'
          description: The first page thumbnail of the circular (height 400px)
          example: https://cdn.flippenterprise.net/sub_pages/thumbnail/60106d22-5b09-11e5-b5bd-22000bb3a4ba/thumbnail_image_400h_s3_key
        first_page_thumbnail_2000h_url:
          type:
          - string
          - 'null'
          description: The first page thumbnail of the circular (height 2000px)
          example: https://cdn.flippenterprise.net/sub_pages/thumbnail/60106d22-5b09-11e5-b5bd-22000bb3a4ba/thumbnail_image_xlarge_s3_key
        image_first_page_400w:
          type:
          - string
          - 'null'
          description: The first page thumbnail of the circular (width 400px)
          example: https://cdn.fli

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