Skip to main content

​
API Notes

Quirks, tips, and behaviors for specific App Store Connect API endpoints
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 sales report
asc analytics sales --vendor "12345678" --type SALES --subtype SUMMARY --frequency DAILY --date "2024-01-15"

# Monthly sales report
asc analytics sales --vendor "12345678" --type SUBSCRIPTION --subtype DETAILED --frequency MONTHLY --date "2024-01"

​
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 view --request-id ... --date ... to avoid missing instances on later pages. Without pagination, you may only receive partial data. 
asc analytics view --request-id "REQUEST_ID" --date "2024-01-01" --paginate

​
Long-Running Operations

Long analytics runs may require raising ASC_TIMEOUT: 
export ASC_TIMEOUT=5m
asc analytics view --request-id "REQUEST_ID" --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 reports --vendor "12345678" --report-type FINANCIAL --region ZZ --date "2024-01"

# Detailed report (requires Z1)
asc finance reports --vendor "12345678" --report-type FINANCE_DETAIL --region Z1 --date "2024-01"

​
Important Notes

List available regions: 
asc finance regions

​
Sandbox Testers

The current CLI supports these sandbox tester operations: Example: 
asc sandbox list
asc sandbox view --email "test@example.com"
asc sandbox update --id "SANDBOX_TESTER_ID" --territory USA
asc sandbox clear-history --id "SANDBOX_TESTER_ID" --confirm

​
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/view/update/clear-history: Use the current CLI surface under asc sandbox ...
  • Historical create/delete endpoints used older API coverage and are not exposed by the current CLI

​
Game Center

​
Game Center Detail ID

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

​
Releases

Game Center resources often need a linked Game Center app version before they become active in App Store Connect: 
# Create achievement first
asc game-center achievements create --app "123456789" --reference-name "First Win" --vendor-id "com.example.firstwin" --points 10

# Then create the Game Center app version that links it to your App Store version
asc game-center app-versions create --app-store-version-id "APP_STORE_VERSION_ID"

​
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 --id "123456789" --status DISABLED

​
Registration Requirements

  • iOS: UDID (Unique Device Identifier)
  • macOS: Hardware UUID
Example: 
asc devices register --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:
  • --include is not available on asc pass-type-ids certificates list.
  • Use supported filters like --id, --certificate-type, or --fields instead.

​
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

Use explicit filter flags instead of generic --filter expressions: 
asc builds list --app "123456789" --version "1.0.0"
Sort with - prefix for descending: 
asc testflight crashes list --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.