> ## 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.

# Api notes

# 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**:

```bash theme={null} theme={null}
# 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:

```bash theme={null} theme={null}
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.

```bash theme={null} theme={null}
asc analytics view --request-id "REQUEST_ID" --date "2024-01-01" --paginate
```

### Long-Running Operations

Long analytics runs may require raising `ASC_TIMEOUT`:

```bash theme={null} theme={null}
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**:

```bash theme={null} theme={null}
# 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/](https://developer.apple.com/help/app-store-connect/reference/financial-report-regions-and-currencies/)

List available regions:

```bash theme={null} theme={null}
asc finance regions
```

## Sandbox Testers

The current CLI supports these sandbox tester operations:

**Example**:

```bash theme={null} theme={null}
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:

```bash theme={null} theme={null}
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:

```bash theme={null} theme={null}
# 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:

```bash theme={null} theme={null}
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](https://appstoreconnect.apple.com/access/integrations/api)

## Devices

### No DELETE Endpoint

Devices can **only be enabled/disabled** via PATCH. There is no DELETE endpoint.

```bash theme={null} theme={null}
asc devices update --id "123456789" --status DISABLED
```

### Registration Requirements

* **iOS**: UDID (Unique Device Identifier)
* **macOS**: Hardware UUID

**Example**:

```bash theme={null} theme={null}
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):

```bash theme={null} theme={null}
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:

```bash theme={null} theme={null}
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:

```bash theme={null} theme={null}
asc builds list --app "123456789" --version "1.0.0"
```

Sort with `-` prefix for descending:

```bash theme={null} theme={null}
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:

```bash theme={null} theme={null}
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/](https://sosumi.ai/documentation/appstoreconnectapi/) (preferred over developer.apple.com)
* **Official API Reference**: [https://developer.apple.com/documentation/appstoreconnectapi/](https://developer.apple.com/documentation/appstoreconnectapi/)

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