MikMak Availabilities API

openapi: 3.2.0
info:
  version: '1.0'
  title: Commerce API (v1) Availabilities API
servers:
- url: https://api.mikmak.ai
security:
- ApiKeyAuth: []
tags:
- name: Availabilities
paths:
  /commerce/v1/availabilities/{id}:
    get:
      tags:
      - Availabilities
      security:
      - ApiKeyAuth: []
      - JWTBearerAuth: []
      description: Returns a list of store availability. Distances are in the metric system (m).
      parameters:
      - name: id
        in: path
        required: true
        description: The list of the requested product ids separated by a comma
        schema:
          type: string
        example: 0048001353855,0048001213586
      - name: idType
        in: query
        description: 'The type of the unique product identifier (default - MikMak default Product Id, gtin, mpn, product_id). (eg: gtin)'
        schema:
          type: string
          default: default
          enum:
          - default
          - gtin
          - mpn
          - product_id
      - name: wtbId
        in: query
        required: true
        description: The experience id
        schema:
          type: string
        example: 54511c2f827bef6f9c68f29a
      - name: draft
        in: query
        description: True to use the draft experience configuration
        schema:
          type: boolean
      - name: maxDistance
        in: query
        description: Max search distance (radius) in km, this parameter can override subaccount default setting
        schema:
          type: integer
        example: 5
      - name: maxReturnedStores
        in: query
        description: Maximum number of returned stores
        schema:
          type: string
        example: 10
      - name: language
        in: query
        description: Requested language or locale for the product and retailers
        schema:
          type: string
        examples:
          language:
            value: en
            summary: Language code
          lcoale:
            value: en-US
            summary: Locale code
      - name: latitude
        in: query
        description: Search location latitude (any combination of Latitude + Longitude OR ZipCode + Country must be provided)
        required: true
        schema:
          type: number
        example: 48.8640493
      - name: longitude
        in: query
        required: true
        description: Search location longitude (any combination of Latitude + Longitude OR ZipCode + Country must be provided)
        schema:
          type: number
        example: 2.331052600000021
      - name: country
        in: query
        required: true
        description: Search location country code (2-letters)  (any combination of Latitude + Longitude OR ZipCode + Country must be provided)
        schema:
          type: string
        example: US
      - name: zipCode
        in: query
        required: true
        description: Search location zip code (any combination of Latitude + Longitude OR ZipCode + Country must be provided)
        schema:
          type: string
        example: 20004
      - name: city
        in: query
        description: Search location city
        schema:
          type: string
        example: Washington D.C
      - name: address
        in: query
        description: Search location address
        schema:
          type: string
        example: 401 9th St NW
      - name: state
        in: query
        description: Search location state
        schema:
          type: string
        example: DC
      - name: requestedCountry
        in: query
        description: Requested country code (2-letters). Only for multiple countries experience. If the location country is different from the requestedCountry, the location falls back to default location for the requested country.
        schema:
          type: string
        example: US
      - name: sessionId
        in: query
        description: Id for the current session so the events can be properly tracked.
        schema:
          type: string
        example: 1234abcd
      - name: currentUrl
        in: query
        description: The full URL visible in the shopper's browser as they interact with the Experience. It must include all query parameters. This is necessary to report on UTM parameters.
        schema:
          type: string
        example: https://www.mikmak.com/
      - name: sessionUrl
        in: query
        description: The full URL visible in the shopper's browser when they first arrived on the website. This has to be persisted throughout the session. It must include all query parameters. This is necessary to report on UTM parameters.
        schema:
          type: string
        example: https://www.mikmak.com/
      - name: includeOutOfStock
        in: query
        description: True to include out of stock products
        schema:
          type: boolean
        example: true
      - name: hideOutOfStockOfflineStores
        in: query
        description: True to hide out of stock offline stores
        schema:
          type: boolean
        example: true
      - name: applyTiedHouseLaw
        in: query
        description: To override the experience setting for applying tied house law
        schema:
          type: boolean
        example: true
      - name: retailerIds
        in: query
        description: Comma-separated list of retailer IDs to filter availability results. Only stores from the specified retailers will be returned. If omitted, all in-scope retailers are returned.
        schema:
          type: string
        example: 1,2,3
      - name: modes
        in: query
        description: Delivery mode filter (delivery, clickAndCollect, brickAndMortar). Filters availability results to only include stores that support the specified delivery modes
        schema:
          type: string
        example: delivery
      - name: src
        in: query
        description: Source identifier for tracking where the request originated from
        schema:
          type: string
      - name: instanceId
        in: query
        description: Instance identifier for multi-tenant or distributed system tracking
        schema:
          type: string
      responses:
        '200':
          description: 200 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AvailabilitiesResponse'
              example:
                location:
                  latitude: 32.781339
                  longitude: -96.799759
                  address: null
                  city: Dallas
                  country: US
                  state: TX
                  zipCode: '75270'
                  placeType: null
                  isMetricRegion: false
                products:
                - id: 0048001353855
                  ids:
                  - 0048001353855
                  gtin: 0048001353855
                  gtins:
                  - 0048001353855
                  imageUrl: https://img.static-swaven.com/v7/https%3A%2F%2Fassets.unileversolutions.com%2Fv1%2F1195565.png?width=500&org_if_sml=1&ci_url_encoded=1
                  thumbnailImageUrl: https://img.static-swaven.com/v7/https%3A%2F%2Fassets.unileversolutions.com%2Fv1%2F1195565.png?width=144&ci_url_encoded=1&force_format=webp,png&func=fit
                  brand: hellmann's
                  title: Mayonnaise Dressing with Olive Oil
                  subtitle: null
                  description: Hellmann's Mayonnaise Dressing with Olive Oil combines the creamy, rich taste you love from Hellmann's with the delicious goodness of olive oil.
                  packaging: 20 oz
                  review: null
                - id: 0048001213586
                  ids:
                  - 0048001213586
                  gtin: 0048001213586
                  gtins:
                  - 0048001213586
                  imageUrl: https://img.static-swaven.com/v7/https%3A%2F%2Fassets.unileversolutions.com%2Fv1%2F116893611.png?width=500&org_if_sml=1&ci_url_encoded=1
                  thumbnailImageUrl: https://img.static-swaven.com/v7/https%3A%2F%2Fassets.unileversolutions.com%2Fv1%2F116893611.png?width=144&ci_url_encoded=1&force_format=webp,png&func=fit
                  brand: hellmann's
                  title: Light Mayonnaise
                  subtitle: null
                  description: Looking for a lighter mayonnaise? Hellmann's Light Mayo has half the calories & half the fat of our Real Mayonnaise with the same rich, creamy taste!
                  packaging: 30 oz
                  review: null
                availabilities:
                - gtin: 0048001353855
                  store:
                    id: 265_WEB
                    name: Amazon
                    retailer:
                      id: 265
                      name: Amazon.com
                      logo:
                        url: https://img.static-swaven.com/v7/https%3A%2F%2Fcontent.static-swaven.com%2Fimg%2Fretailers%2Fhd%2F265_2048.png?width=200&org_if_sml=1&ci_url_encoded=1
                        isDefault: false
                      url: http://www.amazon.com
                    phoneNumber: ''
                    internationalPhoneNumber: ''
                    whatsappNumber: ''
                    delivery: true
                    clickAndCollect: false
                    brickAndMortar: false
                    url: https://www.amazon.com
                    storeOpeningHoursSchema: null
                    pickUpOptionAvailable: false
                  price:
                    currency: USD
                    value: 6.98
                  clickUrl: https://wtb-api-hub.swaven.com/wtb/v3/outbound_click?example=0048001353855
                  doNotTrackClickUrl: http://www.amazon.com
                  isTiedHouseLaw: false
                - gtin: 0048001213586
                  store:
                    id: 245_WEB
                    name: Walmart
                    retailer:
                      id: 245
                      name: Walmart
                      logo:
                        url: https://img.static-swaven.com/v7/https%3A%2F%2Fcontent.static-swaven.com%2Fimg%2Fretailers%2Fhd%2F245.png?width=200&org_if_sml=1&ci_url_encoded=1
                        isDefault: false
                      url: https://www.walmart.com
                    phoneNumber: ''
                    internationalPhoneNumber: ''
                    whatsappNumber: ''
                    delivery: true
                    clickAndCollect: false
                    brickAndMortar: false
                    storeOpeningHoursSchema: null
                    url: https://www.walmart.com
                    pickUpOptionAvailable: true
                  price:
                    currency: USD
                    value: 5.97
                  clickUrl: https://wtb-api-hub.swaven.com/wtb/v3/outbound_click?example=0048001213586
                  doNotTrackClickUrl: https://www.walmart.com
                  isTiedHouseLaw: false
                alcoholSettings:
                  tiedHouseLaw: 4
                  showLocalRetailers: true
                  showRetailerText: true
                  settingCode: 3
                  applyTiedHouseLaw: true
                  tiedHouseConditionMet: false
                sessionId: 1234abcd
        '400':
          description: '**Bad Request.** The request is invalid and cannot be processed.


            > **When:** Returned when required parameters are missing, malformed, or fail validation (e.g., invalid IDs, query parameters, or location data).

            '
        '401':
          description: '**Unauthorized.** Authentication failed.


            > **When:** Returned when the request is missing a valid API key or JWT, or when the token is expired or invalid.

            '
        '403':
          description: '**Forbidden.** The request is authenticated but not allowed.


            > **When:** Returned when access is restricted due to configuration rules, disallowed countries, disabled operators, or unauthorized products.

            '
        '404':
          description: '**Not Found.** The requested resource does not exist.


            > **When:** Returned when a configuration, product, experience, or continuation token cannot be found.

            '
        '500':
          description: '**Internal Server Error.** An unexpected server error occurred.


            > **When:** Returned when the server encounters an unhandled error while processing the request.

            '
components:
  schemas:
    Location:
      type: object
      description: Resolved or requested search location (shared across products, availabilities, and cart responses).
      properties:
        latitude:
          type: number
          description: Latitude
        longitude:
          type: number
          description: Longitude
        address:
          type:
          - string
          - 'null'
          description: Address
        city:
          type: string
          description: City
        country:
          type: string
          description: Country
        state:
          type: string
          description: State
        zipCode:
          type: string
          description: Zip code
        placeType:
          type:
          - string
          - 'null'
          description: Place type
        isMetricRegion:
          type: boolean
          description: Country is standard metric system (m) or not (miles)
    CatalogProduct:
      type: object
      description: Product metadata returned with availability and cart responses (catalog fields; not store-specific).
      properties:
        id:
          type: string
          description: Product id (when applicable)
        ids:
          type: array
          description: Alternate product identifiers
          items:
            type: string
        gtin:
          type: string
          description: GTIN
        gtins:
          type: array
          description: List of GTINs
          items:
            type: string
            description: GTIN
        imageUrl:
          type: string
          description: Product image URL
        thumbnailImageUrl:
          type: string
          description: Product thumbnail image URL (optimized for small displays, 144px width)
        brand:
          type: string
          description: Brand
        title:
          type: string
          description: Title
        subtitle:
          type:
          - string
          - 'null'
          description: Subtitle
        description:
          type: string
          description: Product description (empty by default)
        packaging:
          type: string
          description: Containing or color
        review:
          type: object
          description: Review
          properties:
            count:
              type: number
              description: Count
            averageRating:
              type: number
              description: Rating
            roundedAverageRating:
              type: number
              description: Rounded rating
    AvailabilitiesResponse:
      type: object
      description: Availabilities response
      properties:
        location:
          $ref: '#/components/schemas/Location'
        products:
          type: array
          description: List of products
          items:
            $ref: '#/components/schemas/CatalogProduct'
        availabilities:
          type: array
          description: List of availabilities
          items:
            properties:
              gtin:
                type: string
                description: GTIN
              price:
                type: object
                description: Price
                properties:
                  currency:
                    type: string
                    description: Currency
                  value:
                    type: number
                    description: Value
                  valueWithVoucher:
                    type: number
                    description: Value with Voucher
              store:
                type: object
                description: Store Info
                properties:
                  id:
                    type: string
                    description: Id
                  name:
                    type: string
                    description: Store name
                  retailer:
                    type: object
                    description: retailer
                    properties:
                      id:
                        type: number
                        description: Id
                      name:
                        type: string
                        description: Name
                      logo:
                        type: object
                        description: Logo
                        properties:
                          url:
                            type: string
                            description: URL
                          isDefault:
                            type: boolean
                            description: Is the default logo
                          type:
                            type: string
                            description: rectangle or square
                      logos:
                        type: array
                        description: List of logos
                        items:
                          type: object
                          properties:
                            url:
                              type: string
                              description: URL
                            type:
                              type: string
                              description: rectangle or square
                      url:
                        type: string
                        description: URL
                      subsidiary:
                        type: object
                        description: Subsidiary
                        properties:
                          name:
                            type: string
                            description: Name
                          logo:
                            type: object
                            description: Logo
                            properties:
                              url:
                                type: string
                                description: URL
                              isDefault:
                                type: boolean
                                description: Is the default logo
                              type:
                                type: string
                                description: rectangle or square
                          logos:
                            type: array
                            description: List of logos
                            items:
                              type: object
                              properties:
                                url:
                                  type: string
                                  description: URL
                                type:
                                  type: string
                                  description: rectangle or square
                      pickUpOptionAvailable:
                        type:
                        - boolean
                        - 'null'
                        description: Whether the retailer offers pickup options
                  localeInfo:
                    type: object
                    description: Locale Info
                    properties:
                      latitude:
                        type: number
                        description: Latitude
                      longitude:
                        type: number
                        description: Longitude
                      address:
                        type: string
                        description: Address
                      zipCode:
                        type: string
                        description: Zip code
                      city:
                        type: string
                        description: City
                      state:
                        type: string
                        description: State
                      open24:
                        type: boolean
                        description: Is open 24h
                      openingHours:
                        type: string
                        description: Opening hours
                      googleMapsUrl:
                        type: string
                        description: Google Maps URL
                      appointmentUrl:
                        type: string
                        description: Appointment URL
                      distance:
                        type: number
                        description: Distance
                      isLockedDown:
                        type: boolean
                        description: Is locked down
                      timeZone:
                        type: string
                        description: Time zone
                  phoneNumber:
                    type: string
                    description: Phone number
                  internationalPhoneNumber:
                    type: string
                    description: International phone number
                  whatsappNumber:
                    type: string
                    description: Whatsapp phone Number
                  delivery:
                    type: boolean
                    description: Is delivery
                  clickAndCollect:
                    type: boolean
                    description: Is click and collect (Buy Online Pickup In Store)
                  brickAndMortar:
                    type: boolean
                    description: Is brick and mortar
                  storeOpeningHoursSchema:
                    type: array
                    description: List of opening hours
                    items:
                      type: string
                      description: Opening hours
                  url:
                    type: string
                    description: URL
                  clickUrl:
                    type: string
                    description: Click URL
                  doNotTrackClickUrl:
                    type: string
                    description: Do not track click URL
              voucher:
                allOf:
                - $ref: '#/components/schemas/Voucher'
              isTiedHouseLaw:
                type: boolean
                description: Is tied house law
        sessionId:
          type: string
          description: SessionID value
        alcoholSettings:
          type: object
          description: Alcohol settings configuration
          properties:
            tiedHouseLaw:
              type: integer
              description: Tied house law setting code
              example: 4
            showLocalRetailers:
              type: boolean
              description: Whether to show local retailers
              example: true
            showRetailerText:
              type: boolean
              description: Whether to show retailer text
              example: true
            settingCode:
              type: integer
              description: Alcohol setting code
              example: 3
            applyTiedHouseLaw:
              type: boolean
              description: Whether to apply tied house law
              example: true
            tiedHouseConditionMet:
              type: boolean
              description: Whether tied house condition is met (null if applyTiedHouseLaw is false)
              example: false
    Voucher:
      type: object
      description: Promotional voucher that may apply to a line item
      properties:
        id:
          type: string
        versionId:
          type: string
        name:
          type: string
        code:
          type: string
        retailerId:
          type:
          - integer
          - 'null'
        online:
          type:
          - boolean
          - 'null'
        offline:
          type: boolean
        startDate:
          type:
          - string
          - 'null'
          format: date-time
        endDate:
          type:
          - string
          - 'null'
          format: date-time
        type:
          type: string
          description: Voucher type (configuration enum)
        text:
          type: string
        imageUrl:
          type: string
        description:
          type: string
        ctaText:
          type: string
        discountType:
          type:
          - string
          - 'null'
        discountPercent:
          type:
          - number
          - 'null'
          format: double
        discountAmount:
          type:
          - number
          - 'null'
          format: double
        url:
          type: string
        gtins:
          type: array
          items:
            type: string
        hasSecondStep:
          type: boolean
        secondStepUrl:
          type: string
        secondStepType:
          type:
          - string
          - 'null'
        formId:
          type:
          - string
          - 'null'
        locales:
          type: object
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API Key for authentication
    JWTBearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT Bearer token for authentication
x-sharedDocumentationSamples:
  locationDallas:
    latitude: 32.781339
    longitude: -96.799759
    address: null
    city: Dallas
    country: US
    state: TX
    zipCode: '75270'
    placeType: null
    isMetricRegion: false
  productsHellmannTwo:
  - id: 0048001353855
    ids:
    - 0048001353855
    gtin: 0048001353855
    gtins:
    - 0048001353855
    imageUrl: https://img.static-swaven.com/v7/https%3A%2F%2Fassets.unileversolutions.com%2Fv1%2F1195565.png?width=500&org_if_sml=1&ci_url_encoded=1
    thumbnailImageUrl: https://img.static-swaven.com/v7/https%3A%2F%2Fassets.unileversolutions.com%2Fv1%2F1195565.png?width=144&ci_url_encoded=1&force_format=webp,png&func=fit
    brand: hellmann's
    title: Mayonnaise Dressing with Olive Oil
    subtitle: null
    description: Hellmann's Mayonnaise Dressing with Olive Oil combines the creamy, rich taste you love from Hellmann's with the delicious goodness of olive oil.
    packaging: 20 oz
    review: null
  - id: 0048001213586
    ids:
    - 0048001213586
    gtin: 0048001213586
    gtins:
    - 0048001213586
    imageUrl: https://img.static-swaven.com/v7/https%3A%2F%2Fassets.unileversolutions.com%2Fv1%2F116893611.png?width=500&org_if_sml=1&ci_url_encoded=1
    thumbnailImageUrl: https://img.static-swaven.com/v7/https%3A%2F%2Fassets.unileversolutions.com%2Fv1%2F116893611.png?width=144&ci_url_encoded=1&force_format=webp,png&func=fit
    brand: hellmann's
    title: Light Mayonnaise
    subtitle: null
    description: Looking for a lighter mayonnaise? Hellmann's Light Mayo has half the calories & half the fat of our Real Mayonnaise with the same rich, creamy taste!
    packaging: 30 oz
    review: null