Skip to main content
This page documents quirks and tips for specific App Store Connect API endpoints. Use it as a reference when encountering unexpected behavior or implementing new features.

​
Analytics & Sales Reports

​
Date Format Requirements

Date formats vary by report frequency:
  • DAILY/WEEKLY: YYYY-MM-DD (e.g., 2024-01-15)
  • MONTHLY: YYYY-MM (e.g., 2024-01)
  • YEARLY: YYYY (e.g., 2024)
Example: 
# Daily report
asc analytics get --date 2024-01-15 --frequency daily

# Monthly report
asc analytics get --date 2024-01 --frequency monthly

​
Vendor Number

Vendor number comes from Sales and Trends → Reports URL (vendorNumber=... parameter). Set it globally: 
export ASC_VENDOR_NUMBER="12345678"

​
Pagination Quirks

Use --paginate with asc analytics get --date to avoid missing instances on later pages. Without pagination, you may only receive partial data. 
asc analytics get --date 2024-01-01 --paginate

​
Long-Running Operations

Long analytics runs may require raising ASC_TIMEOUT: 
export ASC_TIMEOUT=5m
asc analytics get --date 2024-01-01 --paginate

​
Finance Reports

Finance reports use Apple fiscal months (YYYY-MM), not calendar months.

​
Report Type Mapping

API --report-type values map to App Store Connect UI options:
API --report-typeUI Option--region Code(s)
FINANCIALAll Countries or Regions (Single File)ZZ (consolidated)
FINANCIALAll Countries or Regions (Multiple Files)US, EU, JP, etc.
FINANCE_DETAILAll Countries or Regions (Detailed)Z1 (required)
Not availableTransaction Tax (Single File)N/A
Example: 
# Consolidated report
asc finance get --report-type FINANCIAL --region ZZ --period 2024-01

# Detailed report (requires Z1)
asc finance get --report-type FINANCE_DETAIL --region Z1 --period 2024-01

​
Important Notes

List available regions: 
asc finance regions

​
Sandbox Testers

​
Required Fields

  • Email
  • First and last name
  • Password + password confirmation
  • Secret question and answer
  • Birth date
  • Territory (3-letter App Store territory code)

​
Password Requirements

Password must include:
  • Uppercase letter
  • Lowercase letter
  • Number
  • Minimum 8 characters
Example: 
asc sandbox-testers create \
  --email "test@example.com" \
  --first-name "Test" \
  --last-name "User" \
  --password "SecurePass123" \
  --territory USA

​
Territory Codes

Territory uses 3-letter App Store territory codes:
  • USA - United States
  • JPN - Japan
  • GBR - United Kingdom
  • DEU - Germany
  • etc.

​
API Version Differences

  • List/get: Use v2 API
  • Create/delete: Use v1 endpoints (may be unavailable on some accounts)
  • Update/clear-history: Use v2 API
If create/delete operations fail, your API key role may lack v1 endpoint access.

​
Game Center

​
Game Center Detail ID

Most Game Center endpoints require a Game Center detail ID, resolved via: 
asc apps game-center-detail --app "123456789"
If Game Center is not enabled for the app, the detail lookup returns 404.

​
Releases

Releases are required to make achievements/leaderboards/leaderboard-sets live. Create a release after creating the resource: 
# Create achievement first
asc game-center achievements create --app "123456789" --title "First Win"

# Then create release to make it live
asc game-center releases create --app "123456789"

​
Image Uploads

Image uploads follow a three-step flow:
  1. Reserve upload slot: Request upload URL from API
  2. Upload file: PUT file to reserved URL
  3. Commit upload: Notify API of completion
Use upload operations for this workflow.

​
Challenges Minimum Platform Versions

The challengesMinimumPlatformVersions relationship on gameCenterDetails uses appStoreVersions linkages. Important:
  • Live API rejects gameCenterAppVersions for this relationship
  • The relationship endpoint is replace-only (PATCH)
  • GET relationship requests are rejected with “does not allow ‘GET_RELATIONSHIP’… Allowed operation is: REPLACE”
  • Setting challengesMinimumPlatformVersions requires a live App Store version
  • Non-live versions fail with ENTITY_ERROR.RELATIONSHIP.INVALID.MIN_CHALLENGES_VERSION_MUST_BE_LIVE
Error message: “must be live to be set as a minimum challenges version.”

​
Authentication & Rate Limiting

​
JWT Token Validity

JWTs issued for App Store Connect are valid for 10 minutes. The CLI handles renewal automatically.

​
Automatic Retries

Automatic retries apply only to:
  • Methods: GET/HEAD requests
  • Status codes: 429 (rate limit) and 503 (service unavailable)
POST/PATCH/DELETE are NOT retried to prevent duplicate operations. Configure retry behavior: 
export ASC_MAX_RETRIES=5
export ASC_BASE_DELAY=1s
export ASC_MAX_DELAY=30s
export ASC_RETRY_LOG=true

​
Retry-After Headers

Retry-After headers are honored when present. The CLI respects server-specified delays.

​
Permission Errors (403)

Some endpoints return 403 when the API key role lacks permission:
  • Finance reports: Requires Admin or Finance role
  • Reviews: Requires App Manager or higher
  • Sales reports: Requires Sales or Admin role
Generate a new API key with appropriate permissions at: https://appstoreconnect.apple.com/access/integrations/api

​
Devices

​
No DELETE Endpoint

Devices can only be enabled/disabled via PATCH. There is no DELETE endpoint. 
asc devices update --device "123456789" --status DISABLED

​
Registration Requirements

  • iOS: UDID (Unique Device Identifier)
  • macOS: Hardware UUID
Example: 
asc devices create --name "iPhone 15 Pro" --udid "00000000-0000000000000000" --platform IOS

​
Device Management Location

Device management UI lives in the Apple Developer portal, not App Store Connect.

​
Device Limits

  • Device reset is limited to once per membership year
  • Disabling does not free slots
  • Plan device registrations accordingly

​
Pass Type IDs

​
Include Parameter Rejection

Live API rejects include=passTypeId and fields[passTypeIds] on /v1/passTypeIds/{id}/certificates despite the OpenAPI spec allowing them. The CLI does not expose those parameters for pass-type-ids certificates list to avoid API errors. Example (working): 
asc pass-type-ids certificates list --pass-type-id "123456789"
Not supported (causes API error): 
# Don't use --include or --fields with certificates
asc pass-type-ids certificates list --pass-type-id "123456789" --include passTypeId

​
General API Quirks

​
Relationship Operations

  • Some relationships are replace-only (PATCH), not append
  • GET relationship requests may be rejected for certain endpoints
  • Related resources may need to be in specific states (e.g., “live”)

​
Pagination

Always use --paginate for complete results: 
asc builds list --app "123456789" --paginate
Without --paginate, only the first page is returned (default limit varies by endpoint).

​
Filters and Sorting

Filter syntax uses bracket notation: 
asc builds list --app "123456789" --filter "preReleaseVersion.version=1.0.0"
Sort with - prefix for descending: 
asc crashes --app "123456789" --sort -createdDate

​
Response Delays

Some operations return success but take time to process:
  • Build processing (can take 10-30 minutes)
  • Screenshot processing
  • Review submissions
Poll the resource or check App Store Connect web UI for status.

​
Debugging API Issues

Enable debug logging to see full HTTP request/response details: 
export ASC_DEBUG=api
asc <command>
This shows:
  • Request method, URL, headers, body
  • Response status, headers, body
  • Retry attempts and timing
Use this when reporting issues or investigating unexpected behavior.

​
Additional Resources

For endpoint existence and request/response schemas, use the offline OpenAPI snapshot in docs/openapi/latest.json.