openapi: 3.1.0
info:
  title: Starbucks Loyalty Menu 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: Menu
  description: Menu categories and items operations
paths:
  /v1/menu/categories:
    get:
      operationId: listMenuCategories
      summary: List Menu Categories
      description: Returns all available menu categories such as Hot Coffees, Cold Coffees, Teas, Refreshers, Food, and Merchandise.
      tags:
      - Menu
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  categories:
                    type: array
                    items:
                      $ref: '#/components/schemas/MenuCategory'
        '401':
          description: Unauthorized
        '429':
          description: Too Many Requests
  /v1/menu/categories/{categoryId}/items:
    get:
      operationId: listMenuItems
      summary: List Menu Items
      description: Returns all menu items within a specific category, including product descriptions, pricing, sizes, and customization options.
      tags:
      - Menu
      parameters:
      - name: categoryId
        in: path
        required: true
        description: The unique identifier of the menu category
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Maximum number of items to return
        schema:
          type: integer
          default: 50
      - name: offset
        in: query
        required: false
        description: Pagination offset
        schema:
          type: integer
          default: 0
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/MenuItem'
                  total:
                    type: integer
                  limit:
                    type: integer
                  offset:
                    type: integer
        '401':
          description: Unauthorized
        '404':
          description: Category Not Found
        '429':
          description: Too Many Requests
  /v1/menu/items/{itemId}:
    get:
      operationId: getMenuItem
      summary: Get Menu Item
      description: Returns detailed information for a specific menu item including full nutritional data, allergen information, customization options, and available sizes.
      tags:
      - Menu
      parameters:
      - name: itemId
        in: path
        required: true
        description: The unique identifier of the menu item
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MenuItemDetail'
        '401':
          description: Unauthorized
        '404':
          description: Item Not Found
        '429':
          description: Too Many Requests
components:
  schemas:
    MenuCategory:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        imageUrl:
          type: string
        itemCount:
          type: integer
    MenuItemDetail:
      allOf:
      - $ref: '#/components/schemas/MenuItem'
      - type: object
        properties:
          sizes:
            type: array
            items:
              type: object
              properties:
                id:
                  type: string
                name:
                  type: string
                price:
                  type: number
          customizations:
            type: array
            items:
              type: object
              properties:
                type:
                  type: string
                options:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                      priceModifier:
                        type: number
          calories:
            type: integer
          allergens:
            type: array
            items:
              type: string
    MenuItem:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        price:
          type: number
          format: float
        imageUrl:
          type: string
        categoryId:
          type: string
        available:
          type: boolean
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
externalDocs:
  description: Starbucks Developer Portal
  url: https://developer.starbucks.com/