openapi: 3.2.0
info:
  title: Vibes Platform Wallet Store Locations API
  version: 1.0.0
  description: Manage the store locations attached to a wallet campaign. Locations drive geofenced lock-screen notifications that remind pass holders about a nearby store.
servers:
- url: https://public-api.vibescm.com
  description: North America
- url: https://public-api.eu.vibes.com/
  description: EMEA
security:
- basicAuth: []
tags:
- name: Wallet Store Locations API
  description: Manage the store locations attached to a wallet campaign. Locations drive geofenced lock-screen notifications that remind pass holders about a nearby store.
paths:
  /companies/{company_key}/campaigns/wallet/{token}/locations:
    get:
      tags:
      - Wallet Store Locations API
      summary: Get store locations
      description: List the store locations attached to a wallet campaign. Results are paginated; use the `page` and `page_size` parameters to page through them.
      parameters:
      - name: X-API-Version
        in: header
        schema:
          type: string
          default: 1
      - name: company_key
        in: path
        schema:
          type: string
        required: true
      - name: token
        in: path
        schema:
          type: string
          description: The `token` is the SmartLink token (`wallet_id`) for the campaign.
        required: true
      - name: page
        in: query
        description: 1-indexed page number to return.
        schema:
          type: integer
      - name: page_size
        in: query
        description: Number of locations per page.
        schema:
          type: integer
      - name: zip
        in: query
        description: Optional filter by zip/postal code (exact match).
        schema:
          type: string
      - name: latitude
        in: query
        description: Optional filter by latitude (exact match).
        schema:
          type: string
      - name: longitude
        in: query
        description: Optional filter by longitude (exact match).
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/walletLocationsResponse'
        '404':
          description: The specified campaign does not exist.
  /companies/{company_key}/campaigns/wallet/{token}/locations/bulk:
    post:
      tags:
      - Wallet Store Locations API
      summary: Bulk create store locations
      description: 'Add store locations to a wallet campaign in a single request (up to 1000 per call). The `Idempotency-Key` header is required: repeating a request with the same key returns the original result without inserting duplicates.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/walletLocationsBulkRequest'
      parameters:
      - name: X-API-Version
        in: header
        schema:
          type: string
          default: 1
      - name: Content-Type
        in: header
        schema:
          type: string
        example: application/json
        required: true
      - name: Idempotency-Key
        in: header
        required: true
        description: Unique key (up to 255 characters) that makes the request safe to retry without creating duplicate locations.
        schema:
          type: string
      - name: company_key
        in: path
        schema:
          type: string
        required: true
      - name: token
        in: path
        schema:
          type: string
        required: true
        description: The `token` is the SmartLink token (`wallet_id`) for the campaign.<br><div style="color:#dd1e2e; background:url(https://d2xs7zaan7w9gl.cloudfront.net/data/pages/64014/widgets/48027d01-e827-45e0-b96d-227c1099eedc/image/1680214872.png?icon-24x24-warning.png) no-repeat 10px center; background-color:#FCEAEC; padding:10px; font-size:13px;"><div style="padding-left:35px"><b>Important:</b> Using the <b>"Try It"</b> feature on the righthand console will send an actual API call to our system. This may result in store locations being created.</div></div>
      responses:
        '201':
          description: The store locations were created.
  /companies/{company_key}/campaigns/wallet/{token}/locations/{id}:
    delete:
      tags:
      - Wallet Store Locations API
      summary: Delete a store location
      description: Remove a single store location from a wallet campaign.
      parameters:
      - name: X-API-Version
        in: header
        schema:
          type: string
          default: 1
      - name: company_key
        in: path
        schema:
          type: string
        required: true
      - name: token
        in: path
        schema:
          type: string
        required: true
        description: The `token` is the SmartLink token (`wallet_id`) for the campaign.
      - name: id
        in: path
        required: true
        description: The unique identifier of the store location to delete.<br><div style="color:#dd1e2e; background:url(https://d2xs7zaan7w9gl.cloudfront.net/data/pages/64014/widgets/48027d01-e827-45e0-b96d-227c1099eedc/image/1680214872.png?icon-24x24-warning.png) no-repeat 10px center; background-color:#FCEAEC; padding:10px; font-size:13px;"><div style="padding-left:35px"><b>Important:</b> Using the <b>"Try It"</b> feature on the righthand console will send an actual API call to our system. This may result in a store location being deleted.</div></div>
        schema:
          type: integer
      responses:
        '204':
          description: The store location was deleted.
        '404':
          description: The campaign or store location cannot be found.
  /companies/{company_key}/campaigns/wallet/{token}/locations/delete_all:
    delete:
      tags:
      - Wallet Store Locations API
      summary: Delete all store locations
      description: Remove store locations from a wallet campaign in bulk. Optional filters limit which locations are deleted; omit them to delete every location on the campaign.
      parameters:
      - name: X-API-Version
        in: header
        schema:
          type: string
          default: 1
      - name: company_key
        in: path
        schema:
          type: string
        required: true
      - name: token
        in: path
        schema:
          type: string
        required: true
        description: The `token` is the SmartLink token (`wallet_id`) for the campaign.<br><div style="color:#dd1e2e; background:url(https://d2xs7zaan7w9gl.cloudfront.net/data/pages/64014/widgets/48027d01-e827-45e0-b96d-227c1099eedc/image/1680214872.png?icon-24x24-warning.png) no-repeat 10px center; background-color:#FCEAEC; padding:10px; font-size:13px;"><div style="padding-left:35px"><b>Important:</b> Using the <b>"Try It"</b> feature on the righthand console will send an actual API call to our system. This may result in store locations being deleted.</div></div>
      - name: zip
        in: query
        description: Optional filter limiting deletion to locations with this zip/postal code.
        schema:
          type: string
      responses:
        '200':
          description: The matching store locations were deleted.
        '404':
          description: The specified campaign does not exist.
components:
  schemas:
    walletLocationsBulkRequest:
      example:
        locations:
        - location_id: store-001
          name: Downtown
          address: 123 Main St
          city: Chicago
          state: IL
          zip: '60601'
          latitude: '41.8781'
          longitude: '-87.6298'
          notification_message: Stop by the downtown store!
      type: object
      required:
      - locations
      properties:
        locations:
          type: array
          description: Store locations to add (up to 1000 per request).
          items:
            $ref: '#/components/schemas/walletLocation'
    walletLocationResponse:
      allOf:
      - type: object
        properties:
          id:
            type: integer
            description: Unique identifier of the store location.
      - $ref: '#/components/schemas/walletLocation'
    walletLocation:
      type: object
      description: A store location attached to a wallet campaign.
      properties:
        location_id:
          type: string
          description: Your own identifier for the store (for example a store number).
        name:
          type: string
          description: Store or location name.
        address:
          type: string
          description: Street address.
        address_2:
          type: string
          description: Optional second address line (suite, unit, etc.).
        city:
          type: string
          description: City.
        state:
          type: string
          description: State or province.
        zip:
          type: string
          description: Zip or postal code.
        phone_number:
          type: string
          description: Store contact phone number.
        store_hours:
          type: string
          description: Store operating hours.
        latitude:
          type: string
          description: Latitude of the location.
        longitude:
          type: string
          description: Longitude of the location.
        notification_message:
          type: string
          description: Lock-screen message shown to pass holders when they are near this location.
    walletLocationsResponse:
      type: array
      items:
        $ref: '#/components/schemas/walletLocationResponse'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic