Flipp (Wishabi) Stores API

openapi: 3.2.0
info:
  version: '4.0'
  title: FlyerKit Stores 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: stores
paths:
  /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
        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: postal_code
        in: query
        description: Postal/zip code of user.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Stores response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/store'
        '422':
          description: Missing or invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
components:
  schemas:
    error:
      properties:
        message:
          type: string
          description: The error message
          example: Invalid publication_id or access token
        code:
          type: string
          description: HTTP status code
          example: '422'
    store:
      properties:
        id:
          type: integer
          description: The store's Flipp ID
          example: 3057
        address:
          type:
          - string
          - 'null'
          description: The store's address
          example: 6220 Menard Drive
        city:
          type:
          - string
          - 'null'
          description: The store's city
          example: Casper
        latitude:
          type:
          - string
          - 'null'
          description: The store's latitude
          example: '42.843126'
        longitude:
          type:
          - string
          - 'null'
          description: The store's longitude
          example: '-106.276372'
        merchant_store_code:
          type: string
          description: The store's code defined by the merchant
          example: '3243'
        name:
          type:
          - string
          - 'null'
          description: The store's name
          example: CASPER
        phone_number:
          type:
          - string
          - 'null'
          description: The store's phone number
          example: '9056230110'
        postal_code:
          type:
          - string
          - 'null'
          description: The store's postal/zip code
          example: '82609'
        province:
          type:
          - string
          - 'null'
          description: The store's province or state
          example: WY
        sat_close:
          type:
          - string
          - 'null'
          description: The store's Saturday closing hour
          example: '18:00'
        sat_open:
          type:
          - string
          - 'null'
          description: The store's Saturday opening hour
          example: '8:00'
        sun_close:
          type:
          - string
          - 'null'
          description: The store's Sunday closing hour
          example: '18:00'
        sun_open:
          type:
          - string
          - 'null'
          description: The store's Sunday opening hour
          example: '10:00'
        mon_close:
          type:
          - string
          - 'null'
          description: The store's Monday closing hour
          example: '21:00'
        mon_open:
          type:
          - string
          - 'null'
          description: The store's Monday opening hour
          example: '8:00'
        tue_close:
          type:
          - string
          - 'null'
          description: The store's Tuesday closing hour
          example: '21:00'
        tue_open:
          type:
          - string
          - 'null'
          description: The store's Tuesday opening hour
          example: '8:00'
        wed_close:
          type:
          - string
          - 'null'
          description: The store's Wednesday closing hour
          example: '21:00'
        wed_open:
          type:
          - string
          - 'null'
          description: The store's Wednesday opening hour
          example: '8:00'
        thu_close:
          type:
          - string
          - 'null'
          description: The store's Thursday closing hour
          example: '21:00'
        thu_open:
          type:
          - string
          - 'null'
          description: The store's Thursday opening hour
          example: '8:00'
        fri_close:
          type:
          - string
          - 'null'
          description: The store's Friday closing hour
          example: '21:00'
        fri_open:
          type:
          - string
          - 'null'
          description: The store's Friday opening hour
          example: '8:00'
        distance:
          type:
          - string
          - 'null'
          description: The store's distance from postal in miles(US) or kilometers(CA)
          example: 4mi