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-type`	UI Option	`--region` Code(s)
`FINANCIAL`	All Countries or Regions (Single File)	`ZZ` (consolidated)
`FINANCIAL`	All Countries or Regions (Multiple Files)	`US`, `EU`, `JP`, etc.
`FINANCE_DETAIL`	All Countries or Regions (Detailed)	`Z1` (required)
Not available	Transaction 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

FINANCE_DETAIL reports require region code Z1 (the only valid region for detailed reports)
Transaction Tax reports are NOT available via API; download manually from App Store Connect
Region codes reference: https://developer.apple.com/help/app-store-connect/reference/financial-report-regions-and-currencies/

List available regions:

asc finance regions

Sandbox Testers

The current CLI supports these sandbox tester operations: Example:

asc sandbox list
asc sandbox view --email "[email protected]"
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:

Reserve upload slot: Request upload URL from API
Upload file: PUT file to reserved URL
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

OpenAPI Specification: docs/openapi/latest.json
Endpoint Index: docs/openapi/paths.txt
API Documentation: https://sosumi.ai/documentation/appstoreconnectapi/ (preferred over developer.apple.com)
Official API Reference: https://developer.apple.com/documentation/appstoreconnectapi/

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

​API Notes

​Analytics & Sales Reports

​Date Format Requirements

​Vendor Number

​Pagination Quirks

​Long-Running Operations

​Finance Reports

​Report Type Mapping

​Important Notes

​Sandbox Testers

​Territory Codes

​API Version Differences

​Game Center

​Game Center Detail ID

​Releases

​Image Uploads

​Challenges Minimum Platform Versions

​Authentication & Rate Limiting

​JWT Token Validity

​Automatic Retries

​Retry-After Headers

​Permission Errors (403)

​Devices

​No DELETE Endpoint

​Registration Requirements

​Device Management Location

​Device Limits

​Pass Type IDs

​Include Parameter Rejection

​General API Quirks

​Relationship Operations

​Pagination

​Filters and Sorting

​Response Delays

​Debugging API Issues

​Additional Resources

API Notes

Analytics & Sales Reports

Date Format Requirements

Vendor Number

Pagination Quirks

Long-Running Operations

Finance Reports

Report Type Mapping

Important Notes

Sandbox Testers

Territory Codes

API Version Differences

Game Center

Game Center Detail ID

Releases

Image Uploads

Challenges Minimum Platform Versions

Authentication & Rate Limiting

JWT Token Validity

Automatic Retries

Retry-After Headers

Permission Errors (403)

Devices

No DELETE Endpoint

Registration Requirements

Device Management Location

Device Limits

Pass Type IDs

Include Parameter Rejection

General API Quirks

Relationship Operations

Pagination

Filters and Sorting

Response Delays

Debugging API Issues

Additional Resources