> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asccli.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Analytics reports

# Analytics and Reports

> Download sales, analytics, and financial reports from App Store Connect

Access and download comprehensive analytics, sales, and financial reports for your apps.

## Overview

The CLI provides access to:

* **Sales Reports**: Daily, weekly, and monthly sales data
* **Analytics Reports**: App usage, crashes, and performance metrics
* **Financial Reports**: Revenue and payment information
* **Custom Analytics**: Request specific metrics and segments

## Sales Reports

Sales reports provide transaction-level data for your apps.

### Download Daily Sales Report

```bash theme={null} theme={null}
asc analytics sales \
  --vendor "YOUR_VENDOR_NUMBER" \
  --type SALES \
  --subtype SUMMARY \
  --frequency DAILY \
  --date "2024-01-20"
```

### Download Weekly Sales Report

```bash theme={null} theme={null}
asc analytics sales \
  --vendor "YOUR_VENDOR_NUMBER" \
  --type SALES \
  --subtype SUMMARY \
  --frequency WEEKLY \
  --date "2024-01-20"
```

### Download Monthly Sales Report

```bash theme={null} theme={null}
asc analytics sales \
  --vendor "YOUR_VENDOR_NUMBER" \
  --type SALES \
  --subtype SUMMARY \
  --frequency MONTHLY \
  --date "2024-01-01"
```

### Sales Report Types

* **SALES**: Standard sales transactions
* **PRE\_ORDER**: Pre-order transactions
* **NEWSSTAND**: Newsstand sales (if applicable)
* **SUBSCRIPTION**: Subscription events
* **SUBSCRIPTION\_EVENT**: Detailed subscription lifecycle events

### Sales Report Subtypes

* **SUMMARY**: Aggregated sales summary
* **DETAILED**: Transaction-level details
* **OPT\_IN**: Reports for apps with opted-in features

<Note>
  The vendor number is found in App Store Connect under **Sales and Trends > Reports**. Set it as `ASC_VENDOR_NUMBER` environment variable to avoid repeating it.
</Note>

## Analytics Reports

Request custom analytics reports for detailed app metrics.

### Create Analytics Request

<Steps>
  <Step title="Request analytics report">
    Create a request for ongoing analytics access:

    ```bash theme={null} theme={null}
    asc analytics request \
      --app "YOUR_APP_ID" \
      --access-type ONGOING
    ```

    For one-time reports:

    ```bash theme={null} theme={null}
    asc analytics request \
      --app "YOUR_APP_ID" \
      --access-type ONE_TIME_SNAPSHOT
    ```
  </Step>

  <Step title="List analytics requests">
    View all analytics requests for your app:

    ```bash theme={null} theme={null}
    asc analytics requests --app "YOUR_APP_ID"
    ```
  </Step>

  <Step title="Check request status">
    Get detailed status of a request:

    ```bash theme={null} theme={null}
    asc analytics view --request-id "REQUEST_ID"
    ```
  </Step>

  <Step title="List available report instances">
    Once the request is processed, inspect the available reports and instances:

    ```bash theme={null} theme={null}
    asc analytics view --request-id "REQUEST_ID"
    ```
  </Step>
</Steps>

### Download Analytics Data

Download the actual report data:

```bash theme={null} theme={null}
asc analytics download \
  --request-id "REQUEST_ID" \
  --instance-id "INSTANCE_ID" \
  --output "./analytics-report.csv"
```

### Analytics Report Segments

Segment analytics by various dimensions:

```bash theme={null} theme={null}
asc analytics segments view \
  --segment-id "SEGMENT_ID" \
  --output json
```

Common segments include:

* App version
* Device type
* Platform version
* Territory
* Source type

## Financial Reports

Access payment and financial information:

### Download Financial Report

```bash theme={null} theme={null}
asc finance reports \
  --vendor "YOUR_VENDOR_NUMBER" \
  --report-type FINANCIAL \
  --region "ZZ" \
  --date "2024-01"
```

### Report Regions

Financial reports are organized by region:

```bash theme={null} theme={null}
asc finance reports \
  --vendor "YOUR_VENDOR_NUMBER" \
  --report-type FINANCIAL \
  --region "US" \
  --date "2024-01"
```

Common region codes:

* `US` - United States
* `EU` - European Union
* `JP` - Japan
* `AU` - Australia
* `CN` - China

## Complete Reporting Workflow

Here's a complete workflow for downloading reports:

```bash theme={null} theme={null}
#!/bin/bash
set -e

# Configuration
export ASC_VENDOR_NUMBER="YOUR_VENDOR_NUMBER"
export ASC_APP_ID="YOUR_APP_ID"
REPORT_DIR="./reports/$(date +%Y-%m-%d)"

mkdir -p "$REPORT_DIR"

# 1. Download daily sales report
echo "Downloading daily sales report..."
asc analytics sales \
  --vendor "$ASC_VENDOR_NUMBER" \
  --type SALES \
  --subtype SUMMARY \
  --frequency DAILY \
  --date "$(date -v-1d +%Y-%m-%d)" \
  --output "$REPORT_DIR/daily-sales.txt"

# 2. Download weekly sales report (if Monday)
if [ $(date +%u) -eq 1 ]; then
  echo "Downloading weekly sales report..."
  asc analytics sales \
    --vendor "$ASC_VENDOR_NUMBER" \
    --type SALES \
    --subtype SUMMARY \
    --frequency WEEKLY \
    --date "$(date -v-7d +%Y-%m-%d)" \
    --output "$REPORT_DIR/weekly-sales.txt"
fi

# 3. Request analytics if not already requested
echo "Checking for analytics request..."
REQUESTS=$(asc analytics requests --app "$ASC_APP_ID" --output json)

if [ "$(echo $REQUESTS | jq '.data | length')" -eq 0 ]; then
  echo "Creating analytics request..."
  asc analytics request --app "$ASC_APP_ID" --access-type ONGOING
fi

# 4. Download available analytics instances
REQUEST_ID=$(echo $REQUESTS | jq -r '.data[0].id')
if [ -n "$REQUEST_ID" ]; then
  echo "Downloading analytics instances..."
  REPORTS=$(asc analytics view --request-id "$REQUEST_ID" --output json)
  
  echo $REPORTS | jq -r '.data[]?.instances[]?.id' | while read INSTANCE_ID; do
    echo "Downloading instance $INSTANCE_ID..."
    asc analytics download \
      --request-id "$REQUEST_ID" \
      --instance-id "$INSTANCE_ID" \
      --output "$REPORT_DIR/analytics-$INSTANCE_ID.csv"
  done
fi

echo "Reports downloaded to $REPORT_DIR"
```

## Automated Daily Reports (CI/CD)

### GitHub Actions Example

```yaml theme={null} theme={null}
name: Daily Reports

on:
  schedule:
    - cron: '0 9 * * *'  # 9 AM UTC daily
  workflow_dispatch:

jobs:
  download_reports:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Install asc CLI
        run: |
          curl -fsSL https://raw.githubusercontent.com/rorkai/App-Store-Connect-CLI/main/install.sh | bash
      
      - name: Configure credentials
        env:
          ASC_KEY_ID: ${{ secrets.ASC_KEY_ID }}
          ASC_ISSUER_ID: ${{ secrets.ASC_ISSUER_ID }}
          ASC_PRIVATE_KEY: ${{ secrets.ASC_PRIVATE_KEY }}
          ASC_VENDOR_NUMBER: ${{ secrets.ASC_VENDOR_NUMBER }}
        run: |
          echo "Credentials configured"
      
      - name: Download daily sales report
        run: |
          YESTERDAY=$(date -d "yesterday" +%Y-%m-%d)
          asc analytics sales \
            --vendor "$ASC_VENDOR_NUMBER" \
            --type SALES \
            --subtype SUMMARY \
            --frequency DAILY \
            --date "$YESTERDAY" \
            --output "./sales-$YESTERDAY.txt"
      
      - name: Upload reports as artifact
        uses: actions/upload-artifact@v3
        with:
          name: sales-reports
          path: ./sales-*.txt
          retention-days: 30
      
      - name: Send to analytics platform (optional)
        run: |
          # Parse and send to your analytics/BI platform
          # Example: curl -X POST https://your-analytics.com/api/ingest -d @sales-*.txt
```

## Report Data Processing

### Parse Sales Report

Sales reports are typically tab-delimited:

```bash theme={null} theme={null}
# Extract download counts
grep "^[0-9]" sales-report.txt | cut -f7 | awk '{sum+=$1} END {print sum}'

# Extract revenue by app
grep "^[0-9]" sales-report.txt | awk -F'\t' '{revenue[$3]+=$14} END {for(app in revenue) print app, revenue[app]}'

# Extract top countries by downloads
grep "^[0-9]" sales-report.txt | awk -F'\t' '{country[$13]+=$7} END {for(c in country) print country[c], c}' | sort -rn | head -10
```

### Convert to JSON

```python theme={null} theme={null}
#!/usr/bin/env python3
import csv
import json
import sys

with open(sys.argv[1], 'r') as tsv_file:
    reader = csv.DictReader(tsv_file, delimiter='\t')
    rows = list(reader)
    
    with open('sales-report.json', 'w') as json_file:
        json.dump(rows, json_file, indent=2)

print(f"Converted {len(rows)} rows to JSON")
```

Run with:

```bash theme={null} theme={null}
python convert_sales.py sales-report.txt
```

## Troubleshooting

### "Vendor number not found"

**Problem**: Invalid or missing vendor number.

**Solution**: Find your vendor number in App Store Connect:

1. Go to **Sales and Trends**
2. Click **Reports**
3. Your vendor number is displayed at the top

Set it as an environment variable:

```bash theme={null} theme={null}
export ASC_VENDOR_NUMBER="YOUR_VENDOR_NUMBER"
```

### "Report not available for date"

**Problem**: Report for the requested date doesn't exist yet.

**Solution**:

* Daily reports are available \~24 hours after the date
* Weekly reports are available on Sundays for the previous week
* Monthly reports are available \~14 days after month end

### "Analytics request pending"

**Problem**: Analytics request is still processing.

**Solution**: Check request status:

```bash theme={null} theme={null}
asc analytics view --request-id "REQUEST_ID"
```

Wait for the state to change to `COMPLETED` before downloading instances.

### "Failed to download report"

**Problem**: Network issues or API errors during download.

**Solution**: Retry with increased timeout:

```bash theme={null} theme={null}
export ASC_TIMEOUT=180s
asc analytics sales --vendor "..." --date "..." --output report.txt
```

## Best Practices

1. **Automate daily downloads**: Set up scheduled jobs to download reports automatically

2. **Store reports securely**: Reports contain sensitive financial data—encrypt and restrict access

3. **Parse and analyze**: Don't just download—parse reports and feed into analytics platforms

4. **Set up monitoring**: Alert on anomalies like sudden drop in downloads or revenue

5. **Use environment variables**: Store vendor number and other config in environment variables

6. **Handle missing reports gracefully**: Not all reports are available for all dates

7. **Archive historical data**: Keep long-term archives for trend analysis

8. **Validate data**: Cross-check totals with App Store Connect web interface

## Related Commands

* [TestFlight Analytics](/guides/testflight) - Beta tester metrics
* [Build Analytics](/commands/builds) - Build processing and distribution metrics