API Mapping Reference

How asc-cli commands map to App Store Connect API endpoints.

Overview

asc-cli wraps the App Store Connect API to provide a developer-friendly CLI experience. This reference shows the underlying API calls.

Authentication

JWT Token Generation

The CLI generates JWT tokens per Apple's specification:

Component	Value
Algorithm	ES256
Key ID	From API key
Issuer ID	From App Store Connect
Audience	appstoreconnect-v1
Expiration	20 minutes

Token Refresh

Tokens auto-refresh before expiration. No manual refresh needed.

Apps Commands

asc apps list

API Endpoint:

GET /v1/apps

Parameters:

CLI Option	API Parameter
--limit	limit
--filter-bundle-id	filter[bundleId]

Response Mapping:

{
  "data": [
    {
      "id": "1234567890",
      "attributes": {
        "bundleId": "live.yooz.whisper",
        "name": "Yooz Whisper",
        "sku": "YOOZWHISPER"
      }
    }
  ]
}

asc apps info

API Endpoint:

GET /v1/apps/{id}

Includes:

• appStoreVersions
• preReleaseVersions

Subscriptions Commands

asc subscriptions list

API Sequence:

1. Get app by bundle ID
2. Get subscription groups for app
3. Get subscriptions for each group

Endpoints:

GET /v1/apps?filter[bundleId]=BUNDLE_ID
GET /v1/apps/{appId}/subscriptionGroups
GET /v1/subscriptionGroups/{groupId}/subscriptions

asc subscriptions pricing list

API Endpoint:

GET /v1/subscriptions/{id}/prices

Includes:

• subscriptionPricePoint
• territory

Response Mapping:

{
  "data": [
    {
      "id": "price-id",
      "relationships": {
        "subscriptionPricePoint": {
          "data": { "id": "60" }
        },
        "territory": {
          "data": { "id": "USA" }
        }
      }
    }
  ]
}

asc subscriptions pricing set

API Sequence:

1. Find price point matching USD amount
2. Get equalized prices for all territories
3. Create/update subscription prices

Endpoints:

GET /v1/subscriptionPricePoints?filter[territory]=USA
GET /v1/subscriptionPricePoints/{id}/equalizations
POST /v1/subscriptionPrices

Create Price Request:

{
  "data": {
    "type": "subscriptionPrices",
    "attributes": {
      "startDate": null,
      "preserveCurrentPrice": false
    },
    "relationships": {
      "subscription": {
        "data": { "type": "subscriptions", "id": "SUB_ID" }
      },
      "subscriptionPricePoint": {
        "data": { "type": "subscriptionPricePoints", "id": "POINT_ID" }
      },
      "territory": {
        "data": { "type": "territories", "id": "USA" }
      }
    }
  }
}

Offers Commands

asc subscriptions offers list

API Endpoint:

GET /v1/subscriptions/{id}/introductoryOffers

Includes:

• subscriptionPricePoint
• territory

asc subscriptions offers create

API Endpoint:

POST /v1/subscriptionIntroductoryOffers

Request Body:

{
  "data": {
    "type": "subscriptionIntroductoryOffers",
    "attributes": {
      "duration": "TWO_WEEKS",
      "numberOfPeriods": 1,
      "offerMode": "FREE_TRIAL",
      "startDate": null,
      "endDate": null
    },
    "relationships": {
      "subscription": {
        "data": { "type": "subscriptions", "id": "SUB_ID" }
      },
      "territory": {
        "data": { "type": "territories", "id": "USA" }
      }
    }
  }
}

Duration Mapping:

CLI	API
3d	THREE_DAYS
1w	ONE_WEEK
2w	TWO_WEEKS
1m	ONE_MONTH
2m	TWO_MONTHS
3m	THREE_MONTHS
6m	SIX_MONTHS
1y	ONE_YEAR

Offer Mode Mapping:

CLI	API
free-trial	FREE_TRIAL
pay-as-you-go	PAY_AS_YOU_GO
pay-up-front	PAY_UP_FRONT

asc subscriptions offers delete

API Endpoint:

DELETE /v1/subscriptionIntroductoryOffers/{id}

TestFlight Commands

asc testflight builds list

API Endpoint:

GET /v1/builds

Parameters:

CLI Option	API Parameter
--limit	limit
--app	filter[app]

asc testflight groups list

API Endpoint:

GET /v1/apps/{appId}/betaGroups

asc testflight groups create

API Endpoint:

POST /v1/betaGroups

Request:

{
  "data": {
    "type": "betaGroups",
    "attributes": {
      "name": "Beta Testers",
      "isInternalGroup": false,
      "publicLinkEnabled": false
    },
    "relationships": {
      "app": {
        "data": { "type": "apps", "id": "APP_ID" }
      }
    }
  }
}

asc testflight testers add

API Sequence:

1. Create or find beta tester
2. Add to beta group

Endpoints:

POST /v1/betaTesters
POST /v1/betaGroups/{groupId}/relationships/betaTesters

Bulk Operations

asc bulk apply

Executes multiple API calls based on YAML configuration:

1. Parse and validate YAML
2. For each subscription:
   • Find or validate subscription exists
   • Set pricing (multiple territory calls)
   • Create offers (multiple calls)
3. Report results

Optimization:

• Batches API calls where possible
• Handles rate limiting automatically
• Supports resume on failure

Rate Limiting

App Store Connect enforces rate limits:

Limit Type	Value
Requests per minute	500
Requests per hour	3600

CLI Handling:

• Automatic retry with backoff
• Progress saved for resume
• Warning at 80% of limit

Error Responses

Common Error Codes

HTTP Code	API Error	CLI Message
401	AUTHENTICATION_ERROR	Invalid credentials
403	FORBIDDEN	Permission denied
404	NOT_FOUND	Resource not found
409	CONFLICT	Resource already exists
429	RATE_LIMIT	Rate limited, retry
500	INTERNAL_ERROR	Server error

Error Response Format

{
  "errors": [
    {
      "id": "error-id",
      "status": "403",
      "code": "FORBIDDEN",
      "title": "Access Denied",
      "detail": "Your API key does not have permission..."
    }
  ]
}

Pagination

Large result sets are paginated:

API Response:

{
  "data": [...],
  "links": {
    "self": "...",
    "next": "...?cursor=..."
  },
  "meta": {
    "paging": {
      "total": 175,
      "limit": 50
    }
  }
}

CLI Handling:

• Auto-pagination for list commands
• --limit controls items per page
• All pages fetched by default

API Documentation

For complete API reference:

• App Store Connect API
• Auto-Renewable Subscriptions
• TestFlight

Learn More

• Commands Overview
• Configuration
• Troubleshooting