Flipp (Wishabi) Products API

openapi: 3.2.0
info:
  version: '4.0'
  title: FlyerKit Products 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: products
paths:
  /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
        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.
        required: true
        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: 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: 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: 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
      - 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/merchant_product'
        '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:
      - products
      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'
  /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
        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: postal_code
        in: query
        description: Postal/zip code to specify which 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
      responses:
        '200':
          description: Product response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/detailed_product'
        '422':
          description: Missing or invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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
        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: store_code
        in: query
        description: Store code required for getting inventory data.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Product response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/inventory_sub_item'
        '422':
          description: Missing or invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
components:
  schemas:
    product_feature:
      properties:
        text:
          type:
          - string
          - 'null'
          description: Text describing the feature
          example: Cast iron plating for improved durability.
    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'
    merchant_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'
    

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