openapi: 3.2.0
info:
  title: BYBE Stores API
  version: v1
  description: "\n Welcome to the BYBE API, V1.\n\n You can use this API to access our records of manufacturers,\n rebate offers, and products,\n as well as to validate redemptions for transactions and disburse payouts.\n\n Each route is documented below via the OpenAPI specification.\n Authorization details can be entered using the `Authorize` button on the right.\n "
servers:
- url: https://api.bybe.io
  description: Base URL declared by the provider in apis.yml (roadmap#122).
tags:
- name: Stores
  description: A store represents a specific retail location of a retailer.
paths:
  /v1/stores:
    get:
      summary: list stores
      tags:
      - Stores
      security:
      - basic_auth: []
      parameters:
      - name: state
        in: query
        schema:
          $ref: '#/components/schemas/state_string_enum'
        required: false
        description: Filter stores by state (two letter abbreviation)
      responses:
        '200':
          description: successfully list stores
          content:
            application/json:
              examples:
                list all stores:
                  value:
                    stores:
                    - id: 980190962
                      name: Columbus Store
                      retailer_identifier: CBUS
                      address_line_1: 1 Capitol Square
                      address_line_2: Suite 100
                      address_city: Columbus
                      address_state: OH
                      address_latitude: 39.961176
                      address_longitude: -82.998794
                      created_at: '2026-06-17T13:55:38.914Z'
                    - id: 298486374
                      name: LA Store
                      retailer_identifier: LA
                      address_line_1: 1 Capitol Square
                      address_line_2: null
                      address_city: Los Angeles
                      address_state: CA
                      address_latitude: 39.961176
                      address_longitude: -82.998794
                      created_at: '2026-06-17T13:55:38.914Z'
                    - id: 335794492
                      name: Always Valid Store
                      retailer_identifier: 0000Valid
                      address_line_1: 1 Capitol Square
                      address_line_2: null
                      address_city: Columbus
                      address_state: OH
                      address_latitude: 39.961176
                      address_longitude: -82.998794
                      created_at: '2026-06-17T13:55:38.914Z'
                    meta:
                      current_page: 1
                      total_pages: 1
                      per_page_limit: 5000
                      total_records: 3
                      count: 3
                filter stores by state:
                  value:
                    stores:
                    - id: 980190962
                      name: Columbus Store
                      retailer_identifier: CBUS
                      address_line_1: 1 Capitol Square
                      address_line_2: Suite 100
                      address_city: Columbus
                      address_state: OH
                      address_latitude: 39.961176
                      address_longitude: -82.998794
                      created_at: '2026-06-17T13:55:38.914Z'
                    - id: 335794492
                      name: Always Valid Store
                      retailer_identifier: 0000Valid
                      address_line_1: 1 Capitol Square
                      address_line_2: null
                      address_city: Columbus
                      address_state: OH
                      address_latitude: 39.961176
                      address_longitude: -82.998794
                      created_at: '2026-06-17T13:55:38.914Z'
                    meta:
                      current_page: 1
                      total_pages: 1
                      per_page_limit: 5000
                      total_records: 2
                      count: 2
  /v1/stores/{id}:
    parameters:
    - name: id
      in: path
      description: store_id
      required: true
      schema:
        type: string
    get:
      summary: show store details
      tags:
      - Stores
      security:
      - basic_auth: []
      parameters:
      - name: page
        in: query
        required: false
        description: Page of results to return
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: Number of stores per page
        schema:
          type: integer
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                test_example:
                  value:
                    store:
                      id: 980190962
                      name: Columbus Store
                      retailer_identifier: CBUS
                      address_line_1: 1 Capitol Square
                      address_line_2: Suite 100
                      address_city: Columbus
                      address_state: OH
                      address_latitude: 39.961176
                      address_longitude: -82.998794
                      created_at: '2026-06-17T13:55:38.914Z'
components:
  schemas:
    state_string_enum:
      type: string
      enum:
      - AL
      - AK
      - AS
      - AZ
      - AR
      - CA
      - CO
      - CT
      - DE
      - DC
      - FM
      - FL
      - GA
      - GU
      - HI
      - ID
      - IL
      - IN
      - IA
      - KS
      - KY
      - LA
      - ME
      - MH
      - MD
      - MA
      - MI
      - MN
      - MS
      - MO
      - MT
      - NE
      - NV
      - NH
      - NJ
      - NM
      - NY
      - NC
      - ND
      - MP
      - OH
      - OK
      - OR
      - PW
      - PA
      - PR
      - RI
      - SC
      - SD
      - TN
      - TX
      - UT
      - VT
      - VI
      - VA
      - WA
      - WV
      - WI
      - WY
  securitySchemes:
    basic_auth:
      type: http
      scheme: basic
      description: "\n Use your API key (token) and your API secret for username and password respectively.\n\n You can get these credentials, or generate new ones, on your developer page.\n\n You should encode your `Authorization:` header value in base64 as `api_key:api_secret`.\n (This will be shown as a curl request for you if you use the 'try it out' feature on this page while authorized.)\n "