Skip to main content
App Store metadata, screenshots, and localization Level: Beginner 10 min read

Configuring App Store Primary and Secondary Categories via MCP

A complete guide to configuring Primary and Secondary App Store categories for iOS and macOS applications, explaining API relationships, review implications, and FlightDeck operation staging.

Published: 2026-11-02 • Last Updated: 2026-11-02 • Author: Kip Lawrence
Key MCP Tools: apps_listflightdeck_operation_stagerelease_readiness_check

Overview: App Store Category Architecture and Discovery

When users search or browse the Apple App Store, categories dictate where your application appears in top charts, editorial collections, and algorithmic recommendations. Apple allows developers to assign two categories:

  1. Primary Category: The most important classification for your application. It determines which top chart your app competes on (e.g., Top Free Utilities or Top Paid Productivity) and where your app is filed in the App Store tab navigation.
  2. Secondary Category: An optional second classification that broadens discoverability in search filters and curated collections, though it does not provide top chart placement.

In Apple's App Store Connect REST API, categories do not belong to the version draft (AppStoreVersion); instead, they are bound to the app-level AppInfo resource. Because categories define your app's core classification, changing them is subject to strict rules: category changes are locked once an app is live and can only be updated and submitted alongside an active version update during App Review.

TEXT
┌────────────────────────────────────────────────────────────────────────┐
│                   APP STORE CONNECT RESOURCE HIERARCHY                 │
│                                                                        │
│   App Record (e.g., "Quest Companion", ID: 6812899314)                 │
│       │                                                                │
│       ├── AppInfo (Global App Settings & Classification)               │
│       │     ├── Primary Category ──► "PRODUCTIVITY" (Top Charts)       │
│       │     └── Secondary Category ─► "UTILITIES" (Search Discovery)   │
│       │                                                                │
│       └── AppStoreVersion (Version Draft e.g., "1.2.0")                │
│             ├── Version Localizations (What's New, Description)        │
│             └── Attached Build (Binary IPA / PKG)                      │
└────────────────────────────────────────────────────────────────────────┘
Important

FlightDeck MCP Operational Boundary: FlightDeck does not expose a standalone semantic tool named app_category_update. In the shipping application, inspecting or modifying app categories is performed either through:

1. The App Store Connect web portal under App Information (recommended for beginners).

2. FlightDeck's Universal Operation Dispatcher using flightdeck_operation_stage targeting the canonical Apple API operation appInfos_updateInstance.

Any category modification staged via MCP requires explicit review and approval in FlightDeck's native macOS Approval Center.


Quick Answer: How to Configure Categories

To set or change your App Store categories:

  1. Create or Open a Version Draft: Categories cannot be altered in isolation on a live app. You must have an editable draft version (e.g., preparing Version 1.1 or 2.0).
  2. Select Strategically: Pick a Primary Category that reflects your app's core utility and where you have realistic chances of ranking in Top Charts. Choose a complementary Secondary Category.
  3. Update via Web Portal or MCP: - Via Portal: Navigate to App Store Connect > Apps > [Your App] > App Information > Primary Category. Select from the dropdown and click Save. - Via FlightDeck MCP: Instruct your AI assistant to stage an appInfos_updateInstance change set linking the target appCategories resource IDs.
  4. Submit with Next App Review: When your version update is submitted, Apple App Review validates that your app's content aligns with the selected categories under Guideline 2.3 (Accurate Metadata).

Category Impact on App Store Optimization (ASO)

Choosing the right category directly impacts discovery, conversion rates, and algorithmic visibility:

Category Assignment Apple Functionality ASO & Marketing Impact
Primary Category Determines primary top chart placement (Free, Paid, Grossing). Appears in the subtitle badge on your product page. Essential. High competition categories (e.g., Productivity) require heavy download velocity to rank; niche categories (e.g., Navigation or Weather) allow indie apps to reach top 50 charts faster.
Secondary Category Used by Apple's search and recommendation algorithms. Appears in search category filtering. Valuable. Captures traffic from secondary user intents without diluting your primary chart ranking.
Subcategories Games category only. Developers select two game subcategories (e.g., Action, Puzzle, Role Playing). Critical for games. Allows dual ranking across specific gaming genre charts.

Copyable Prompts for Your AI Coding Assistant

1. Inspect Current App Categories and Readiness

Use this prompt to have your assistant inspect your app's current configuration and check submission readiness:

MARKDOWN
Please inspect our application in App Store Connect using FlightDeck:
1. Locate our app record and retrieve its primary metadata.
2. Check our active draft version for any missing category or metadata blockers.
3. If our category is not set, list the standard Apple category options for our app type (e.g., Productivity, Utilities, Business, Developer Tools) and recommend the best Primary and Secondary pairing based on our app's features.

2. Stage Category Update via FlightDeck Universal Dispatcher

For advanced developers wishing to stage category updates via MCP:

MARKDOWN
I want to update our application's Primary Category to "PRODUCTIVITY" and Secondary Category to "UTILITIES":
1. Inspect our application's App Information in App Store Connect using FlightDeck.
2. Stage a change set using FlightDeck's universal operation dispatcher to update the App Information so that the primary category is PRODUCTIVITY and the secondary category is UTILITIES.
3. Do not commit immediately—confirm when the proposal is waiting in the FlightDeck Desktop Approval Center for my review.

Supported Apple App Store Categories

Apple supports the following standard top-level categories for iOS, iPadOS, and macOS apps:

TEXT
• Books                       • Lifestyle
• Business                    • Medical
• Developer Tools (macOS)     • Music
• Education                   • Navigation
• Entertainment               • News
• Finance                     • Photo & Video
• Food & Drink                • Productivity
• Games (Subcategories req.)  • Reference
• Graphics & Design           • Shopping
• Health & Fitness            • Social Networking
• Kids (Age band req.)        • Sports
• Magazines & Newspapers      • Travel
• Utilities                   • Weather
Warning

Guideline 2.3 Rejection (Inaccurate Category): Selecting an irrelevant category solely because it has low competition (e.g., selecting Medical for a task planner) is a frequent cause of App Review rejection. Apple Reviewers will reject your binary or require you to switch to a category that accurately represents the application's primary functionality.


Step-by-Step Workflow: Portal vs. MCP Dispatcher

MERMAID
graph TD
    A[Start: Change App Categories] --> B{Choose Workflow}
    
    B -->|Recommended / Visual| C[App Store Connect Web Portal]
    C --> C1[Open App > App Information]
    C1 --> C2[Select Primary & Secondary Category]
    C2 --> C3[Click Save]
    
    B -->|Automated / Scripted| D[FlightDeck MCP Universal Dispatcher]
    D --> D1[Assistant queries AppInfo resource ID]
    D1 --> D2[Call flightdeck_operation_stage: appInfos_updateInstance]
    D2 --> D3[Desktop Approval Center card generated]
    D3 --> D4[Human Developer clicks Approve]
    D4 --> D5[Direct TLS PATCH to Apple API]
    
    C3 --> E[Attached to Active Version Draft]
    D5 --> E
    E --> F[Submitted for App Review with Version Update]
    F --> G[Apple Approves & Publishes to New Categories]
  1. Sign in to App Store Connect.
  2. Click Apps and select your application.
  3. In the left sidebar under General, click App Information.
  4. Scroll down to the Category section.
  5. In the Primary Category dropdown, choose your main category.
  6. In the Secondary Category (Optional) dropdown, select your secondary category.
  7. Click Save in the top-right corner.

Option B: FlightDeck Universal Operation Dispatcher (Advanced)

Because categories are managed on the AppInfo resource, advanced automated agents stage the update via flightdeck_operation_stage:

JSON
{
  "operationId": "appInfos_updateInstance",
  "pathParameters": {
    "id": "app_info_id_12345678"
  },
  "requestBody": {
    "data": {
      "type": "appInfos",
      "id": "app_info_id_12345678",
      "relationships": {
        "primaryCategory": {
          "data": {
            "type": "appCategories",
            "id": "PRODUCTIVITY"
          }
        },
        "secondaryCategory": {
          "data": {
            "type": "appCategories",
            "id": "UTILITIES"
          }
        }
      }
    }
  }
}

In FlightDeck Desktop, the Approval Center displays the proposed relationship updates with full JSON-schema validation. Clicking Approve dispatches the authenticated payload to Apple.


Verifying Category Assignment

To verify that your app categories are correctly registered in Apple's systems before submitting for App Review:

MARKDOWN
Run a verification check on our application using FlightDeck:
1. Audit our active draft version for App Store submission readiness.
2. Confirm that there are no unconfigured category warnings or metadata blockers.
3. Confirm that the application is ready for review submission.

FlightDeck returns the structured readiness report confirming that all mandatory App Information attributes—including the Primary Category—are satisfied.


Troubleshooting Common Category Issues

1. "Cannot edit categories on a live version"

  • Cause: Attempting to alter categories when your app is READY_FOR_SALE without an editable version draft.
  • Fix: Create a new version draft (e.g., app_store_version_create(versionString: "1.1.0")). Once the draft exists, your app's AppInfo enters an editable state.

2. "Subcategories are required for the Games category"

  • Cause: Selecting GAMES as your primary or secondary category without supplying mandatory subcategories (e.g., GAMES_PUZZLE).
  • Fix: If your app is a game, you must select at least one and up to two subcategories. If your app is not a game, select a non-game category such as Entertainment or Utilities.

3. "Kids category requires age band selection"

  • Cause: Selecting the Kids category requires completing Apple's specialized Made for Kids questionnaire and privacy certifications.
  • Fix: If your app is not specifically designed for children under 11, do not choose the Kids category.

Security & Approval Center Governance

  • Explicit Staging: Any universal mutation staged against appInfos_updateInstance is blocked by FlightDeck's fail-closed governance until reviewed by a human operator in FlightDeck Desktop.
  • Zero Intermediary Proxies: Category relationship payloads travel directly between your local Mac and Apple's servers over TLS 1.3.
  • Audit Logging: Every category change is permanently logged in FlightDeck's local audit trail with the operator's timestamp and cryptographic signature.

Official Apple Documentation

Connect Your AI Agent to App Store Connect

FlightDeck runs locally on your Mac, keeping private keys secure in your macOS Keychain and executing mutations only after your explicit approval.

Download FlightDeck on Mac App Store