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