Flipp FlyerKit API

swagger: '2.0'
info:
  version: '4.0'
  title: FlyerKit
  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.

    '
host: api.flipp.com
basePath: /flyerkit/v4.0
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
        type: string
      - name: access_token
        in: query
        description: Contact your Flipp technical contact for your API access token.
        required: true
        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
        type: string
      - name: store_code
        in: query
        description: Retailer's store code.
        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.
        type: string
      - name: see_future
        in: query
        description: Whether to include future publications in the results. Requires special access token
          permissions.
        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.
        type: boolean
      responses:
        '200':
          description: Publications response
          schema:
            type: array
            items:
              $ref: '#/definitions/publication'
        '422':
          description: Missing or invalid parameters
          schema:
            $ref: '#/definitions/error'
  /publications/{merchant_identifier}/products:
    get:
      summary: Returns products across publications
      description: Returns a list of available products for a given store or postal/zip code. If a store
        code is given, products are selected using the store's location. Otherwise, products are chosen
        using the given postal/zip code. If both a store code and postal/zip code are provided, the store
        code takes precedence. 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.Results are sorted by the 'left'
        column asc which means physical location of item on the flyer from left to right.
      tags:
      - products
      parameters:
      - name: merchant_identifier
        in: path
        description: Your merchant name identifier which can be obtained from your Flipp technical contact.
        required: true
        type: string
      - name: access_token
        in: query
        description: Contact your Flipp technical contact for your API access token.
        required: true
        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
        type: string
      - name: store_code
        in: query
        description: Retailer's store code.
        required: true
        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.
        type: string
      - name: page
        in: query
        description: Limit products to those appearing on a specified page in the circular.
        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                              |

          '
        type: string
      - name: postal_code
        in: query
        description: Postal/zip code to specify the region from which to fetch coupons.
        type: string
      - name: keywords
        in: query
        description: Comma-delimited list of keywords appearing in item names/descriptions with which
          to filter items.
        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.
        type: string
      - name: see_future
        in: query
        description: Whether to include future publications in the results. Requires special access token
          permissions.
        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.
        type: boolean
      - name: category
        in: query
        description: Filter products by given category.
        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.
        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.
        type: integer
      responses:
        '200':
          description: Products response
          schema:
            type: array
            items:
              $ref: '#/definitions/merchant_product'
        '422':
          description: Missing or invalid parameters
          schema:
            $ref: '#/definitions/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
        type: integer
      - name: access_token
        in: query
        description: Contact your Flipp technical contact for your API access token.
        required: true
        type: string
      responses:
        '200':
          description: Pages response
          schema:
            type: array
            items:
              $ref: '#/definitions/publication_page'
        '422':
          description: Missing or invalid parameters
          schema:
            $ref: '#/definitions/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
        type: integer
      - name: access_token
        in: query
        description: Contact your Flipp technical contact for your API access token.
        required: true
        type: string
      responses:
        '200':
          description: Highlights response
          schema:
            type: array
            items:
              $ref: '#/definitions/publication_highlight'
        '422':
          description: Missing or invalid parameters
          schema:
            $ref: '#/definitions/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
        type: integer
      - name: access_token
        in: query
        description: Contact your Flipp technical contact for your API access token.
        required: true
        type: string
      responses:
        '200':
          description: Categories response
          schema:
            type: array
            items:
              $ref: '#/definitions/publication_category'
        '422':
          description: Missing or invalid parameters
          schema:
            $ref: '#/definitions/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
      - products
      parameters:
      - name: publication_id
        in: path
        description: Unique identifier for the publication.
        required: true
        type: integer
      - name: access_token
        in: query
        description: Contact your Flipp technical contact for your API access token.
        required: true
        type: string
      - name: page
        in: query
        description: Limit products to those appearing on a specified page in the circular.
        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                              |

          '
        type: string
      - name: postal_code
        in: query
        description: Postal/zip code to specify the region from which to fetch coupons.
        type: string
      - name: store_code
        in: query
        description: Store code required for deep_link of the product.
        type: string
      - name: keywords
        in: query
        description: Comma-delimited list of keywords appearing in item names/descriptions with which
          to filter items.
        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.
        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"
        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).                 |

          '
        type: string
      - name: category
        in: query
        description: Filter products by given category.
        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.
        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.
        type: integer
      responses:
        '200':
          description: Products response
          schema:
            type: array
            items:
              $ref: '#/definitions/product'
        '422':
          description: Missing or invalid parameters
          schema:
            $ref: '#/definitions/error'
  /product/{product_id}:
    get:
      summary: Returns detailed information about a product
      description: Returns detailed information about the specified product. Text will be localized according
        to the locale of the product's publication.
      tags:
      - products
      parameters:
      - name: product_id
        in: path
        description: Unique identifier for the product.
        required: true
        type: integer
      - name: access_token
        in: query
        description: Contact your Flipp technical contact for your API access token.
        required: true
        type: string
      - name: postal_code
        in: query
        description: Postal/zip code to specify which the region from which to fetch coupons.
        type: string
      - name: store_code
        in: query
        description: Store code required for deep_link of the product.
        type: string
      responses:
        '200':
          description: Product response
          schema:
            $ref: '#/definitions/detailed_product'
        '422':
          description: Missing or invalid parameters
          schema:
            $ref: '#/definitions/error'
  /product/{product_id}/sub_items:
    get:
      summary: Returns detailed inventory information about a product's sub items get from MI9 Retail
        API
      description: Returns detailed inventory information about the specified product's sub items in a
        certain store.
      tags:
      - products
      parameters:
      - name: product_id
        in: path
        description: Unique identifier for the product.
        required: true
        type: integer
      - name: access_token
        in: query
        description: Contact your Flipp technical contact for your API access token.
        required: true
        type: string
      - name: store_code
        in: query
        description: Store code required for getting inventory data.
        required: true
        type: string
      responses:
        '200':
          description: Product response
          schema:
            type: array
            items:
              $ref: '#/definitions/inventory_sub_item'
        '422':
          description: Missing or invalid parameters
          schema:
            $ref: '#/definitions/error'
  /stores/{merchant_identifier}:
    get:
      summary: Returns closest stores to a postal/zip code
      description: Returns a list of the five closest stores to the specified postal/zip code.
      tags:
      - stores
      parameters:
      - name: merchant_identifier
        in: path
        description: Your merchant name identifier which can be obtained from your Flipp technical contact.
        required: true
        type: string
      - name: access_token
        in: query
        description: Contact your Flipp technical contact for your API access token.
        required: true
        type: string
      - name: postal_code
        in: query
        description: Postal/zip code of user.
        required: true
        type: string
      responses:
        '200':
          description: Stores response
          schema:
            type: array
            items:
              $ref: '#/definitions/store'
        '422':
          description: Missing or invalid parameters
          schema:
            $ref: '#/definitions/error'
  /fsa/{merchant_name_identifier}:
    get:
      summary: Find geo locate fsa by merchant and ip
      description: 'Returns normalized geo locate fsa for a given merchant and optionally ip. Geo locate
        fsa is selected by country. '
      tags:
      - fsa
      parameters:
      - name: merchant_name_identifier
        in: path
        description: Your merchant name identifier which can be obtained from your Flipp technical contact.
        required: true
        type: string
      - name: access_token
        in: query
        description: Contact your Flipp technical contact for your API access token.
        required: true
        type: string
      - name: ip_override
        in: query
        description: Optional parameter to override request remote IP.
        type: string
      responses:
        '200':
          description: Geo locate fsa response
          schema:
            $ref: '#/definitions/fsa'
        '422':
          description: Missing or invalid parameters
          schema:
            $ref: '#/definitions/error'
  /copyright:
    get:
      summary: Returns Flipp copyright
      tags:
      - copyright
      responses:
        '200':
          description: Copyright response
definitions:
  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
        description: Label given to publication by retailer
        example: Tribune Ad
        nullable: true
      sfml_url:
        type: string
        description: Storefront Payload URL
        example: https://sfml.flippback.com/587807/3433653/22811814cd2e63f0c8b92f53fc5193f9831bf4103e7e2efff5c74680648f1ce4.sfml
        nullable: true
      storefront_payload_url:
        type: string
        description: Storefront Payload URL
        example: https://cdn-gateflipp.flippback.com/storefront-hosted/587807/3433653/22811814cd2e63f0c8b92f53fc5193f9831bf4103e7e2efff5c74680648f1ce4?merchant_id=543&store_id=12345
        nullable: true
      storefront_payload:
        type: string
        description: Storefront Payload
        example: https://cdn-gateflipp.flippback.com/storefront-payload/587807/3433653/22811814cd2e63f0c8b92f53fc5193f9831bf4103e7e2efff5c74680648f1ce4?merchant_id=543
        nullable: true
      deep_link:
        type: string
        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
        nullable: true
      flyer_type:
        type: string
        description: Flipp's name identifier of the type of circular
        example: mailer
        nullable: true
      total_pages:
        type: integer
        description: Number of pages in the flyer
        example: 9
      external_display_name:
        type: string
        description: Localized publication external display name
        example: Mailer
        nullable: true
      locale:
        type: locale
        description: The publication's locale
        example: en
      postal_code:
        type: string
        description: The given postal/zip code of given store
        example: 07866
        nullable: true
      valid_from:
        type: date
        description: The start of the validity period
        example: '2015-03-16T00:00:00-04:00'
        nullable: true
      valid_to:
        type: date
        description: The end of the validity period
        example: '2016-01-30T23:59:00-05:00'
        nullable: true
      available_from:
        type: date
        description: The start of the availability period
        example: '2015-03-16T01:00:00-04:00'
        nullable: true
      available_to:
        type: date
        description: The end of the availability period
        example: '2016-01-31T00:59:00-05:00'
        nullable: true
      thumbnail_image_url:
        type: string
        description: A thumbnail image intended for a listing
        example: https://cdn.flippenterprise.net/flyers/348864/l_thumbnail/1425009356.jpg
        nullable: true
      flyer_selector_thumbnail_url:
        type: string
        description: URL links to the flyer selector image used on hosted desktop
        example: https://cdn.flippenterprise.net/flyers/348864/thumbnail/1425009356.jpg
        nullable: true
      first_page_thumbnail_url:
        type: string
        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
        nullable: true
      first_page_thumbnail_150h_url:
        type: string
        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
        nullable: true
      first_page_thumbnail_400h_url:
        type: string
        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
        nullable: true
      first_page_thumbnail_2000h_url:
        type: string
        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
        nullable: true
      image_first_page_400w:
        type: string
        description: The first page thumbnail of the circular (width 400px)
        example: https://cdn.flippenterprise.net/flyers/2797863/first_page_thumbnail_400w/1564075442.jpg
        nullable: true
      image_first_page_140w:
        type: string
        description: The first page thumbnail of the circular (width 140px)
        example: https://cdn.flippenterprise.net/flyers/2797863/first_page_thumbnail_140w/1564075442.jpg
        nullable: true
      image_first_page_100w:
        type: string
        description: The first page thumbnail of the circular (width 100px)
        example: https://cdn.flippenterprise.net/flyers/2797863/first_page_thumbnail_100w/1564075442.jpg
        nullable: true
      correction_notices:
        type: array
        items:
          $ref: '#/definitions/correction_notice'
      custom_flyer_item_disclaimer:
        type: string
        description: English custom flyer item disclaimer of the given flyer_type
        example: Price and availability may vary by store.
        nullable: true
      french_custom_flyer_item_disclaimer:
        type: string
        description: French custom flyer item disclaimer of the given flyer_type
        example: Les prix et l'offre des produits peuvent varier en magasin.
        nullable: true
      validity_text:
        type: string
        description: Auto generated text by the valid_to field for Content Showcase
        example: Valid Until 2016-01-30T23:59:00-05:00
        nullable: true
      key_message:
        type: string
        description: Circular key message field for Content Showcase
        example: New Movie Releases
        nullable: true
      key_message_short:
        type: string
        description: Short variant of circular key message field for Content Showcase
        example: New Movie Releases
        nullable: true
      pdf_url:
        type: string
        description: Print version of the publication in PDF format
        example: https://cdn.flippenterprise.net/flyers/26376715/711004c22f8216e4.pdf
        nullable: true
  correction_notice:
    properties:
      html:
        type: string
        description: HTML content of the correction notice
        example: <p>Correction</p>
      image_url:
        type: string
        description: Image associated with the correction notice
        example: https://cdn.flippenterprise.net/flyers/348864/correction/1232923480.jpg
        nullable: true
  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
        descript

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