openapi: 3.1.0
info:
  title: Starbucks Loyalty Stores API
  description: Starbucks provides partner APIs for ordering, loyalty program integration, store locations, and menu data. These APIs enable authorized partners to integrate Starbucks ordering, rewards, and store discovery into their applications and services.
  version: '1.0'
  contact:
    name: Starbucks Developer Support
    url: https://developer.starbucks.com/
  termsOfService: https://www.starbucks.com/about-us/company-information/online-policies/terms-of-use
servers:
- url: https://api.starbucks.com
  description: Production
security:
- bearerAuth: []
tags:
- name: Stores
  description: Store location and search operations
paths:
  /v1/stores:
    get:
      operationId: listStores
      summary: List Stores
      description: Search for Starbucks store locations by geographic coordinates, address, or city. Returns store details including hours, amenities, and contact information.
      tags:
      - Stores
      parameters:
      - name: latitude
        in: query
        required: false
        description: Latitude coordinate for location-based search
        schema:
          type: number
          format: float
      - name: longitude
        in: query
        required: false
        description: Longitude coordinate for location-based search
        schema:
          type: number
          format: float
      - name: query
        in: query
        required: false
        description: Text search query (address, city, zip)
        schema:
          type: string
      - name: radius
        in: query
        required: false
        description: Search radius in miles
        schema:
          type: integer
          default: 25
      - name: limit
        in: query
        required: false
        description: Maximum number of stores to return
        schema:
          type: integer
          default: 10
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  stores:
                    type: array
                    items:
                      $ref: '#/components/schemas/Store'
                  total:
                    type: integer
        '401':
          description: Unauthorized
        '429':
          description: Too Many Requests
  /v1/stores/{storeId}:
    get:
      operationId: getStore
      summary: Get Store
      description: Returns detailed information for a specific Starbucks store location including address, hours of operation, amenities, and available services.
      tags:
      - Stores
      parameters:
      - name: storeId
        in: path
        required: true
        description: The unique identifier of the store
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoreDetail'
        '401':
          description: Unauthorized
        '404':
          description: Store Not Found
        '429':
          description: Too Many Requests
components:
  schemas:
    StoreDetail:
      allOf:
      - $ref: '#/components/schemas/Store'
      - type: object
        properties:
          hours:
            type: array
            items:
              type: object
              properties:
                day:
                  type: string
                open:
                  type: string
                close:
                  type: string
          amenities:
            type: array
            items:
              type: string
          services:
            type: array
            items:
              type: string
          mobileOrderingEnabled:
            type: boolean
          driveThru:
            type: boolean
    Coordinates:
      type: object
      properties:
        latitude:
          type: number
          format: float
        longitude:
          type: number
          format: float
    Address:
      type: object
      properties:
        street:
          type: string
        city:
          type: string
        state:
          type: string
        postalCode:
          type: string
        country:
          type: string
    Store:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        address:
          $ref: '#/components/schemas/Address'
        coordinates:
          $ref: '#/components/schemas/Coordinates'
        phone:
          type: string
        timezone:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
externalDocs:
  description: Starbucks Developer Portal
  url: https://developer.starbucks.com/