Set Preferred Regions for Tenant

⚠️ Apple devices only.

Creates or replaces the tenant's preferred App Store region list, setting up to five ISO 3166-1 alpha-2 country codes that represent the regions where your organization operates.Submitting an empty countries array clears all preferred region preferences for the tenant. The list set here defines the available region options when assigning a storefront to individual VPP apps via PUT /v2/itunesapps/{appleAppId}/preferred-region. In the Console, this configuration lives in Apple MDM Management settings.

About Preferred Regions

Multi-region organizations that distribute VPP apps across countries need to ensure each app's App Store storefront matches the operating region of its target devices. The preferred regions list is the tenant-level foundation for that configuration — it defines the pool of allowed storefronts (up to five) from which per-app regions are then selected. This is a replace-style operation: submitting a new list overwrites the previous one entirely rather than appending to it. Audit (GET /v2/preferred-regions) before updating to avoid accidentally removing an actively used region.

Key Fields

countries (required) — array of ISO 3166-1 alpha-2 country codes in uppercase (e.g., ["AU", "IN", "US"]); maximum five entries; submit an empty array ([]) to clear all preferred regions

tenant_id (response) — UUID of the tenant whose preferred regions were updated

countries (response) — the saved country code list

created_by / updated_by — UUID of the user who created or last modified the list

created_at / updated_at — timestamps of creation and last update

Common Use Cases

Initial setup of the preferred region list when onboarding iOS VPP management for a multi-country deployment

Adding a new country to the allowed storefront pool when the organization expands to a new region

Removing stale regions from the list by resubmitting a trimmed country array

Best Practices

Keep the list to only the countries where you actively deploy VPP apps — the five-region cap is a hard limit

Before updating, call GET /v2/preferred-regions and check which regions are actively assigned to apps via GET /v2/itunesapps; removing a region that apps depend on will break their storefront assignments

Use uppercase two-letter codes (e.g., "US", not "us") to match Apple's App Store country code format

Workflow

Call GET /v2/preferred-regions to retrieve the current list and confirm what, if anything, needs to change

POST to /v2/preferred-regions with the complete desired countries array (this replaces the existing list)

Assign individual app storefronts from the updated pool using PUT /v2/itunesapps/{appleAppId}/preferred-region