CloudKitchens Market Intel Endpoints API

openapi: 3.2.0
info:
  title: Public Marketintel Endpoints API
  description: '# Overview


    The API endpoints are developed around RESTful principles secure via the OAuth2.0 protocol.'
  version: v1
  license:
    name: Proprietary
servers:
- url: https://{{public-api-url}}
  description: Staging server url
tags:
- name: Market Intel Endpoints
paths:
  /v1/market-intel/discovered-stores:
    post:
      tags:
      - Market Intel Endpoints
      summary: Notify stores discovered at the geolocations
      operationId: postDiscoverStoresResult
      parameters:
      - $ref: '#/components/parameters/eventIdOptionalHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DiscoverStoresEventResult'
        required: true
      responses:
        '204':
          description: The stores discovered updates are successfully processed
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '422':
          $ref: '#/components/responses/422'
      security:
      - OAuth2.0:
        - marketintel.service_integration
components:
  schemas:
    Money:
      required:
      - amount
      - currencyCode
      type: object
      properties:
        currencyCode:
          maxLength: 3
          minLength: 3
          type: string
          description: The 3-letter currency code (ISO 4217) to use for all monetary values.
          example: EUR
        amount:
          minimum: 0
          type: number
          description: Amount value.
          example: 25.21
      description: Money amount.
      example: 25.21
    Marketintel_StoreDeliveryInformation:
      type: object
      properties:
        minDeliveryBasketSize:
          type:
          - object
          - 'null'
          description: The minimum basket value of the order needed for delivery
          $ref: '#/components/schemas/Money'
        deliveryFee:
          type:
          - object
          - 'null'
          description: The delivery fee for the order
          $ref: '#/components/schemas/Money'
        deliveryType:
          type:
          - string
          - 'null'
          description: The delivery type for the order
          example: Third Party
        deliveryTimeMinutes:
          type:
          - integer
          - 'null'
          description: The estimated delivery time in minutes
          example: 30
      description: The Store delivery information.
    Marketintel_TimeRange:
      required:
      - end
      - start
      type: object
      properties:
        start:
          type: string
          description: Start time of the range in 24 hour format.
          example: 08:00
        end:
          type: string
          description: End time of the range in 24 hour format.
          example: '22:00'
      description: Time range in a given date.
    Marketintel_StorePromotion:
      type: object
      properties:
        displayName:
          type:
          - string
          - 'null'
          description: The name of the promotion.
          example: Flat rate discount on Christmas day
        promotionType:
          type:
          - string
          - 'null'
          description: The type of promotion.
          example: Flat rate discount
        campaignType:
          type:
          - string
          - 'null'
          description: The type of promotion campaign.
          example: Christmas
        promotionId:
          type:
          - string
          - 'null'
          description: The external promotion id.
          example: 12345
      description: The Store Promotion information. At least one of the displayName, promotionType, campaignType or promotionId need to be present.
    Marketintel_StoreMenu:
      type: object
      properties:
        category:
          type:
          - string
          - 'null'
          description: The grouping category name.
          example: Fast Food
        ids:
          type: array
          description: The list of external store ids in the list in rank order.
          items:
            type: string
            description: The external id the store
            example: 123456
        location:
          type: object
          description: The geographic location of the stores that was searched from.
      description: The Store listing in ranking order based on category.
    Marketintel_Coordinates:
      type: object
      properties:
        coordinatesType:
          type: string
          description: Coordinates type
          enum:
          - WGS84
          - GCJ02
        location:
          type: object
          description: The longitude and latitude of a location.
          $ref: '#/components/schemas/Location'
      description: The geographical coordinates of a location.
    DiscoveredStore:
      type: object
      properties:
        storeDetails:
          type: object
          description: The store details.
          $ref: '#/components/schemas/Marketintel_StoreDetails'
        locationBasedInformation:
          type:
          - object
          - 'null'
          description: The location information of the store.
          $ref: '#/components/schemas/Marketintel_LocationBasedInformation'
      description: The discovered store information.
    Location:
      required:
      - latitude
      - longitude
      type:
      - object
      - 'null'
      properties:
        latitude:
          type: number
          description: The latitude of the location.
          format: double
          example: 38.8977
        longitude:
          type: number
          description: The longitude of the location.
          format: double
          example: 77.0365
      description: Latitude and longitude of the address.
    Marketintel_LocationBasedInformation:
      type: object
      properties:
        estimatedDeliveryTimeInSeconds:
          type:
          - integer
          - 'null'
          description: The estimated delivery time in seconds
          example: 1200
        distanceInMeters:
          type:
          - integer
          - 'null'
          description: The distance in meters
          example: 3000
      description: The estimated delivery time of the store and delivery distance from the store. At least one of the attributes need to be set.
    ErrorMessage:
      type: object
      properties:
        message:
          type: string
          description: The error description.
          example: The request body is invalid.
        details:
          type: array
          description: The error details.
          items:
            $ref: '#/components/schemas/ErrorDetail'
      description: The error response object.
    Marketintel_StoreChain:
      type: object
      properties:
        chainId:
          type:
          - string
          - 'null'
          description: The external chain id.
          example: 1
        chainName:
          type:
          - string
          - 'null'
          description: The name of the chain.
          example: Macdonalds
      description: The Store Chain information.
    Marketintel_SpecialHours:
      required:
      - date
      - timeRanges
      - type
      type: object
      properties:
        date:
          type: string
          description: Date the special hour configuration applies.
          format: date
          example: '2021-10-01'
        timeRanges:
          type: array
          minItems: 1
          description: Hours range applied to configured date.
          items:
            $ref: '#/components/schemas/Marketintel_TimeRange'
        type:
          type: string
          description: Store state that should be applied during the configured special hour.
          enum:
          - OPEN
          - CLOSED
      description: Describes the configuration of special store hours.
    Marketintel_StoreRating:
      type: object
      properties:
        ratingScore:
          type:
          - number
          - 'null'
          description: The normalized rating score of the store.
          example: 2
        estimatedRatingCount:
          type:
          - integer
          - 'null'
          description: The estimated number of scores in the rating.
          example: 100
        displayRatingCount:
          type:
          - string
          - 'null'
          description: The display text of the number of scores in the rating.
          example:
          - 20+
          - 20
      description: The Store rating information. At least one of the ratingScore, estimatedRatingCount or displayRatingCount need to be present.
    DiscoverStoresEventResult:
      type: object
      properties:
        storesDiscovered:
          type: array
          minItems: 0
          description: Represents a list of discovered stores.
          items:
            $ref: '#/components/schemas/DiscoveredStore'
        storeRankings:
          type: array
          minItems: 0
          description: Represents the store rankings.
          items:
            $ref: '#/components/schemas/Marketintel_StoreListing'
      description: The result of an event that request to find stores at the provided geolocations.
    Marketintel_HoursData:
      required:
      - regularHours
      - specialHours
      - timeZone
      type: object
      properties:
        timeZone:
          type: string
          description: TimeZone of all times under it. (https://www.joda.org/joda-time/timezones.html)
          format: timezone-id
          example: America/Los_Angeles
        regularHours:
          type: array
          description: List of regular hours configuration.
          items:
            $ref: '#/components/schemas/Marketintel_RegularHours'
        specialHours:
          type: array
          description: List of special hours configuration, for occasions like Christmas, Thanksgiving, or any other holidays.
          items:
            $ref: '#/components/schemas/Marketintel_SpecialHours'
      description: Represents hours configuration with regular hours and special hours.
    Marketintel_GeoLocationInformation:
      type: object
      properties:
        regionId:
          type: string
          description: The region id of the geographical location.
          example:
          - LATAM-N
        superRegion:
          type: string
          description: The super region of the geographical location.
          example:
          - LATAM
        h3Index:
          type: string
          description: The H3Index value of the geographic location.
          example:
          - 886d344c81fffff
        searchText:
          type:
          - string
          - 'null'
          description: The text used to search for stores.
          example:
          - chinese food
        address:
          type: object
          description: The address of the geographical location.
          $ref: '#/components/schemas/Address'
      description: The geographical location information used to discover stores.  This information will need be pass back with the result.
    Address:
      type:
      - object
      - 'null'
      properties:
        fullAddress:
          type:
          - string
          - 'null'
          description: Full, human comprehensible address. It is usually formatted in the order appropriate for your locale.
          example: 123 Sample Street Ste 100, San Francisco, CA 94103
        postalCode:
          type: string
          description: Postal code of the address.
          example: '20500'
        city:
          type: string
          description: The city/town portion of the address.
          example: Washington
        state:
          type: string
          description: Highest administrative subdivision which is used for postal addresses of a country or region. For example, this can be a state, a province, or a prefecture.
          example: DC
        countryCode:
          type: string
          description: CLDR country code. See http://cldr.unicode.org/
          example: US
        addressLines:
          type:
          - array
          - 'null'
          description: Address lines (e.g. street, PO Box, or company name) or the full single line address (e.g. street, city, state, country, zip).
          example:
          - 1600 Pennsylvania Avenue NW
          - 123 Sample Street Ste 100, San Francisco, CA 94103
          items:
            type: string
        linesOfAddress:
          type:
          - array
          - 'null'
          deprecated: true
          description: 'Deprecated: use addressLines. Address lines (e.g. street, PO Box, or company name) or the full single line address (e.g. street, city, state, country, zip).'
          example:
          - 1600 Pennsylvania Avenue NW
          - 123 Sample Street Ste 100, San Francisco, CA 94103
          items:
            type: string
        location:
          $ref: '#/components/schemas/Location'
      description: Order delivery address.
    Marketintel_StoreListing:
      type: object
      properties:
        category:
          type:
          - string
          - 'null'
          description: The grouping category name.
          example: Fast Food
        ids:
          type: array
          description: The list of external store ids in the list in rank order.
          items:
            type: string
            description: The external id the store
            example: 123456
        location:
          type: object
          description: The geographic location of the stores that was searched from.
      description: The Store listing in ranking order based on category.
    ErrorDetail:
      type: object
      properties:
        attribute:
          type: string
          description: The error attribute.
          example: Order Currency Code
        message:
          type: string
          description: The error detail description.
          example: Order Currency Code must be exactly 3 characters
      description: The error detail response object.
    Marketintel_RegularHours:
      required:
      - days
      - timeRanges
      type: object
      properties:
        days:
          type: array
          description: The day of the week this configuration applies.
          items:
            type: string
            description: Day of the week.
            enum:
            - MONDAY
            - TUESDAY
            - WEDNESDAY
            - THURSDAY
            - FRIDAY
            - SATURDAY
            - SUNDAY
        timeRanges:
          type: array
          description: Hours range applied to the provided day of the week
          items:
            $ref: '#/components/schemas/Marketintel_TimeRange'
      description: Describes the configuration of regular hours.
    Marketintel_StoreDetails:
      type: object
      properties:
        regionId:
          type:
          - string
          - 'null'
          description: The region that store belongs to.
          example: LATAM-N
        provider:
          type: string
          description: The store information provider
          example: ubereats-provider
        id:
          type: string
          description: The external store id
          example: 12345
        storeUrl:
          type:
          - string
          - 'null'
          description: The store url
          example: 30
        location:
          type: object
          description: The Geographic location used to discover the store
          $ref: '#/components/schemas/Marketintel_GeoLocationInformation'
        address:
          type:
          - object
          - 'null'
          description: The store address
          $ref: '#/components/schemas/Address'
        phoneNumbers:
          type: array
          minItems: 0
          description: The store phone numbers.
          items:
            type: string
            example: 613-123-4567
        storeName:
          type:
          - string
          - 'null'
          description: The name of the store.
          example: McDonald's
        menu:
          type:
          - object
          - 'null'
          description: The store menu.
          $ref: '#/components/schemas/Marketintel_StoreMenu'
        storeHours:
          type:
          - object
          - 'null'
          description: The store hours.
          $ref: '#/components/schemas/Marketintel_HoursData'
        tags:
          type: array
          minItems: 0
          description: The store tags
          items:
            description: The store tag
            example: chinese
        storeBannerPhotoUrl:
          type:
          - string
          - 'null'
          description: The store bannel photo url.
          example: https://www.ubereats.com/ca/store/mcdonalds-1000-rideau-street/1QY5X6QcQX2Q4Z3Z3QZQYQ.jpg
        storeRating:
          type:
          - object
          - 'null'
          description: The store ratings.
          $ref: '#/components/schemas/Marketintel_StoreRating'
        coordinates:
          type:
          - object
          - 'null'
          description: The coordinates of the store.
          $ref: '#/components/schemas/Marketintel_Coordinates'
        storeSales:
          type:
          - object
          - 'null'
          description: The store sales information.
          $ref: '#/components/schemas/Marketintel_StoreSales'
        avgBasketAmount:
          type:
          - object
          - 'null'
          description: The average order amount.
          $ref: '#/components/schemas/Money'
        storePromotions:
          type: array
          minItems: 0
          description: The store promotions.
          items:
            $ref: '#/components/schemas/Marketintel_StorePromotion'
        storeChain:
          type: object
          description: The store chain information.
          $ref: '#/components/schemas/Marketintel_StoreChain'
        storeDeliveryInformation:
          type:
          - object
          - 'null'
          description: The Store delivery information.
          $ref: '#/components/schemas/Marketintel_StoreDeliveryInformation'
        logoPhotoUrl:
          type:
          - string
          - 'null'
          description: The store photo url.
          example: https://www.ubereats.com/ca/store/mcdonalds-1000-rideau-street/1QY5X6QcQX2Q4Z3Z3QZQYQ.jpg
        priceLevel:
          type:
          - string
          - 'null'
          description: The estimated delivery time in minutes.
          $ref: '#/components/schemas/Marketintel_StorePriceLevel'
      description: The Store delivery information.
    Marketintel_StoreSales:
      type: object
      properties:
        periodType:
          type:
          - string
          - 'null'
          description: The period type of the sales data
          example: null
        numberOfSales:
          type:
          - integer
          - 'null'
          description: The number of sales.
          example: 100
        displayNumberOfSales:
          type:
          - string
          - 'null'
          description: The display text of the number of sales.
          example:
          - 20
          - 20+
      description: The Store Sales information. At least one of the periodType, numberOfSales or displayNumberOfSales need to be present.
    Marketintel_StorePriceLevel:
      type: object
      properties:
        priceLevel:
          type:
          - number
          - 'null'
          description: The price level of the store in numeric rating.
          example: 3
        priceLevelName:
          type:
          - string
          - 'null'
          description: The price level of the store in text.
          example: $$$
      description: The Store Price Level information. At least one of the price level or price level name need to be present.
  parameters:
    eventIdOptionalHeader:
      name: X-Event-Id
      in: header
      required: false
      schema:
        type: string
        description: Optional unique identifier of the event that this callback refers to.
        example: cf0ce51b-d74e-40d3-b177-1925ab4edc0c
  responses:
    '401':
      description: Invalid authorization.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    '400':
      description: The request is malformed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    '404':
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    '422':
      description: The request body is not valid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    '403':
      description: Authorization not valid for the requested resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
  securitySchemes:
    OAuth2.0:
      type: oauth2
      description: "The **Authorization API** is based on the [OAuth2.0 protocol](https://tools.ietf.org/html/rfc6749), supporting the (Client Credentials)[https://datatracker.ietf.org/doc/html/rfc6749#section-4.4] and the (Authorization Code)[https://datatracker.ietf.org/doc/html/rfc6749#section-4.1] flows. Resources expect a valid token sent as a `Bearer` token in the HTTP `Authorization` header.\n### Scopes\nScopes must be configured by our internal team to be enabled for an app. Once the scopes are configured they can be enabled on the Application Settings Page in Developer Portal. Each endpoint requires a given scope that can be verified on each endpoint documentation. When generating an OAuth2.0 token multiple scopes can be requested.\n\n### Authorization Code Flow\nTo perform this flow, the authorization code flow must be enabled in the Application Settings Page in Developer Portal. When enabling the flow it is mandatory to provide a redirect URI pointing to your application. Once the flow is complete we will redirect the user to this URI passing the 'code' and 'state' parameters.\nThe Authorization Code flow provides a temporary code that the client application can exchange for an access token. To start the flow the application must request the user authorization. This is done by sending a request to https://{{public-api-url}}/v1/auth/oauth2/authorize.\nExample\n```\ncurl --location 'https://{{public-api-url}}/v1/auth/oauth2/authorize?client_id=[CLIENT_ID]&redirect_uri=[REDIRECT_URI]&response_type=code&scope=organization.read&state=8A9D16B4C3E25F6A'\n```\nThis call will return a 302 redirecting the user to our authorization page. If the user approves the application, we will redirect to configured URI passing the authorization code in the query parameter 'code'. The 'state' parameter is also sent to ensure the source of the data.\nWith the authorization code, the client application can generate the token.\n### Client Credentials Flow\nThe client_credentials flow does not require any steps before generating the token. Once your application is ready, and the client_id and client_secret are available, the token can be generated by following the instructions in the next section.\n\n### Generate Token\nTo generate the token, use the `Client ID` and `Client Secret` (provided during onboarding), and optionally the authorization code obtained after performing the Authorization Code flow, to the [Token Auth endpoint](#operation/requestToken) endpoint. The result of this invocation is a token that is valid for a pre-determined time or until it is manually revoked.\n\nThe access token obtained will be sent as a `Bearer` value of the `Authorization` HTTP header.\n\nClient credentials in the request-body and HTTP Basic Auth are supported.\n\n#### Request Example for client_credentials\n```\ncurl --location --request POST 'https://{{public-api-url}}/v1/auth/token' \\\n  --header 'Content-Type: application/x-www-form-urlencoded' \\\n  --data-urlencode 'scope=ping' \\\n  --data-urlencode 'grant_type=client_credentials' \\\n  --data-urlencode 'client_id=[APPLICATION_ID]' \\\n  --data-urlencode 'client_secret=[CLIENT_SECRET]'\n\n```\n#### Request Example for authorization_code\n```\ncurl --location --request POST 'https://{{public-api-url}}/v1/auth/token' \\\n  --header 'Content-Type: application/x-www-form-urlencoded' \\\n  --data-urlencode 'scope=ping' \\\n  --data-urlencode 'grant_type=authorization_code' \\\n  --data-urlencode 'client_id=[APPLICATION_ID]' \\\n  --data-urlencode 'client_secret=[CLIENT_SECRET]' \\\n  --data-urlencode 'code=[code]' \\\n  --data-urlencode 'redirect_uri=[redirect_uri]'\n\n```\n#### Response Example\n```\n{\n  \"access_token\": \"oMahtBwBbnZeh4Q66mSuLFmk2V0_CLCKVt0aYcNJlcg.yditzjwCP7yp0PgR6AzQR3wQ1rTdCjkcPeAMuyfK-NU\",\n  \"expires_in\": 2627999,\n  \"scope\": \"ping orders.create\",\n  \"token_type\": \"bearer\"\n}\n```\n\n### Token Usage\n\nThe token provided in field `access_token` is used to authenticate when consuming the API endpoints. Send the token value in the `Authorization` header of every request. The token expiration time is represented in the field `expired_in`, in seconds. Currently, all tokens are valid for 30 days and should be stored and re-used while still valid.\n\nNote that occasionally, a 401 error may be returned for a valid token due to an internal service issue. Such occurrences should be rare. To prevent exposing potential vulnerabilities to attackers, the Public API does not disclose other types of errors in the authentication flow if for any reason the token can't be validated (when it's a valid token then it's ok to return 5XX or other 4XX though - such as 403). In such scenarios, although the internal auth flow avoids retries to prevent attacks, if the token is known to be valid and not expired, a retry with a backoff interval by the client is advised. Another option is to request a new token.\n\n#### Example\n\n```\ncurl --location --request GET 'https://{{public-api-url}}/v1/ping' \\\n  --header 'Authorization: Bearer <access_token>' \\\n  --header 'X-Store-Id: <storeId>'\n\n```\n"
      flows:
        clientCredentials:
          tokenUrl: /v1/auth/token
          scopes:
            catalog: Permission to interact with product inventory for existing stores.
            delivery.provider: Permission to provide delivery services for existing orders.
            finance: Permission to provide financial data for orders/stores.
            manager.menus: Permission to manage menus.
            manager.orders: Permission to manage orders.
            manager.storefront: Permission to manage storefront.
            menus.async_job.read: Permission to read the status of a menu upsert job.
            menus.entity_suspension: Permission to notify the result of a menu entity availability update, after being requested by a webhook event.
            menus.get_current: Permission to send the current state of a menu, after being requested by a webhook event.
            menus.publish: Permission to notify the result of a publish menus operation for a given store.
            menus.read: Permission to read the current menus for a given store.
            menus.upsert: Permission to create/update menus for a given store.
            menus.upsert_hours: Permission to notify the receiving of the upsert hours menu event, after being requested by a webhook event.
            orders.create: Permission to create new order for a given store.
            orders.read: Permission to read orders and connected data.
            orders.update: Permission to create and update new orders for a given store.
            ping: Permission to ping the system.
            reports.generate_report: Permission to request reports for given store(s) and period of time.
            reviews.reply: Permission to reply to reviews.
            storefront.store_pause_unpause: Permission to notify the result of a pause/unpause operation, after being requested by a webhook event.
            storefront.store_availability: Permission to send the current state of store.
            storefront.store_hours_configuration: Permission to send the current store hours configuration.
            stores.manage: Permission to onboard stores and update the identifier.
            callback.error.write: Token has permission to send failed webhook event results.
            manager.loyalty: Permission to interact with loyalty services.
            direct.orders: Permission to interact with direct order services.
            store.read: Permission to query store information.
        authorizationCode:
          authorizationUrl: /v1/auth/oauth2/authorize
          tokenUrl: /v1/auth/token
          scopes:
            organization.read: Permission to read data for organization/brands/stores on behalf of a user.
            organization.service_integration: Permission to manage the your integration with a given store on behalf of a user.
x-tagGroups:
- name: Endpoints
  tags:
  - account_pairing_endpoints
  - auth_endpoints
  - callback_endpoints
  - delivery_endpoints
  - finance_endpoints
  - inventory_endpoints
  - manager_menu_endpoints
  - manager_order_endpoints
  - manager_storefront_endpoints
  - menus_endpoints
  - orders_endpoints
  - organization_endpoints
  - ping_endpoints
  - reports_endpoints
  - reviews_endpoints
  - storefront_endpoints
  - manager_loyalty_endpoints
  - direct_orders_endpoints
  - store_endpoints
- name: Webhooks
  tags:
  - account_pairing_webhooks
  - delivery_webhooks
  - manager_orders_webhooks
  - menus_webhooks
  - orders_webhooks
  - ping_webhooks
  - reports_webhooks
  - storefront_webhooks