App Store Connect API
Смена цен через API App Store Connect: ресурсы и запросы
Всё, что делают экраны цен в App Store Connect, доступно через API. Вот карта: какие есть ресурсы, как выглядят запросы, сколько вызовов нужно для изменения по всему миру и что на практике идёт не так.
Коротко
Чтобы изменить цену через API App Store Connect, получите ценовые точки продукта для базовой территории, выберите точку для новой цены и создайте график цен: POST /v1/appPriceSchedules для приложений, POST /v1/inAppPurchasePriceSchedules для встроенных покупок или по одному POST /v1/subscriptionPrices на территорию для подписок. Авторизуйтесь с помощью JWT, подписанного командным ключом API.
Аутентификация
Каждый запрос несёт bearer JWT, который вы подписываете закрытым ключом .p8 вашего ключа API (Apple: генерация токенов):
- Заголовок:
alg=ES256,kid= ваш Key ID,typ=JWT. - Полезная нагрузка:
iss= ваш Issuer ID,iat= сейчас,exp= не позже чем через 20 минут,aud=appstoreconnect-v1. Необязательныйscopeможет ограничить токен перечисленными GET-запросами. - Используйте один токен для многих запросов, пока он не истечёт; Apple рекомендует так делать ради производительности. Долгие задачи периодически создают новый токен.
- Ключу нужна роль, которая может управлять ценами: Admin или App Manager (в справке Apple в качестве необходимой роли указаны Account Holder, Admin или App Manager). О создании ключа рассказано в руководстве по ключу API.
Ресурсы
| Продукт | Ценовые точки | Выравнивание | Создание изменения цены |
|---|---|---|---|
| Приложение | `GET /v1/apps/{id}/appPricePoints`?filter[territory]=USA | `GET /v3/appPricePoints/{id}/equalizations` | `POST /v1/appPriceSchedules` — базовая территория плюс ручные цены |
| Встроенная покупка | `GET /v2/inAppPurchases/{id}/pricePoints` | `GET /v1/inAppPurchasePricePoints/{id}/equalizations` | `POST /v1/inAppPurchasePriceSchedules` — базовая территория обязательна |
| Подписка | `GET /v1/subscriptions/{id}/pricePoints` — всегда с filter[territory] | `GET /v1/subscriptionPricePoints/{id}/equalizations` | `POST /v1/subscriptionPrices` — по одному на территорию |
| Территории | `GET /v1/territories` | — | Только чтение: 175 витрин и их валюты |
У каждой ценовой точки есть customerPrice и ваша proceeds. Выравнивания точки — это соответствующие точки во всех остальных витринах: мировые цены Apple для этой базовой цены, без расчётов по курсам с вашей стороны. Для подписок с ежемесячным и предоплатным типами плана Apple также описывает adjustedEqualizations (Apple: настройка цен подписок по территориям). Текущее состояние читайте через GET /v1/apps/{id}/appPriceSchedule, а для подписок — через GET /v1/subscriptions/{id}/prices.
Как выглядят запросы
График цен приложения — это один документ JSON:API со встроенно создаваемыми ценами. Важные части:
| Где | Поле | Значение |
|---|---|---|
data | type | appPriceSchedules |
data.relationships | app | ID вашего приложения |
data.relationships | baseTerritory | Например, USA |
data.relationships | manualPrices | Ссылки на цены в included с временными ID вида ${price-1} |
included[] | type | appPrices (для встроенных покупок: inAppPurchasePrices) |
included[].attributes | startDate, endDate | null для «сейчас» и «без окончания» либо дата |
included[].relationships | appPricePoint | ID ценовой точки для этой территории |
Территории без ручной цены получают автоматическую цену Apple, производную от базовой. Цена подписки проще: type равен subscriptionPrices, атрибуты — startDate и preserveCurrentPrice (плюс planType, если у вас есть типы планов), а связи — с подпиской, территорией и subscriptionPricePoint.
Изменение по всему миру шаг за шагом
- Один раз получите список территорий и закешируйте его; они меняются редко.
- Для каждого продукта получите ценовые точки в базовой территории (по 200 на страницу) и найдите ту, что соответствует вашей новой базовой цене.
- Если вам нужны цены Apple везде, остановитесь здесь: для приложений и встроенных покупок достаточно одной базовой точки. Для собственных региональных цен рассчитайте целевую цену для каждой витрины и округлите её до ценовой точки — проще всего округлить целевую цену в базовой валюте и пройти по выравниваниям этой точки (как работает округление).
- Приложения и встроенные покупки: отправьте один график с базовой территорией и всеми ручными ценами. Подписки: отправьте по одному
subscriptionPricesна витрину с датой начала и политикой для действующих подписчиков. - Обрабатывайте 429 и 5xx с паузой и повтором; журналируйте каждый созданный ресурс — это ваш аудиторский след.
- Прочитайте график или цены обратно и выборочно проверьте несколько витрин в App Store Connect.
Сколько нужно запросов?
Пример: 2 приложения, 10 встроенных покупок и 4 подписки, цены меняются через 4 региональных уровня. В примере Apple про ограничение частоты запросов указано 3 500 запросов за скользящий час на ключ, и сказано, что реальные лимиты различаются, — читайте заголовок X-Rate-Limit в каждом ответе (Apple: ограничения частоты).
| Шаг | Расчёт | Запросов |
|---|---|---|
| Территории | Один раз | 1 |
| Базовые ценовые точки | 16 продуктов × около 5 страниц | ≈ 80 |
| Выравнивания | 16 продуктов × 4 точки уровней | ≈ 64 |
| Графики приложений и IAP | 12 продуктов × 1 | 12 |
| Цены подписок | 4 подписки × 175 витрин | 700 |
| Итого | ≈ 857 |
Подписки доминируют: Apple отмечает, что массовой конечной точки для применения выровненных цен подписок нет. Удвойте каталог, добавьте повторы и проверочный проход — и вы почти упрётесь в часовой лимит из примера, поэтому распределяйте задачу во времени, а не гоняйте плотный цикл.
Подводные камни
- POST графика заменяет весь график приложения или встроенной покупки. Включайте все ручные цены, которые хотите сохранить, а не только изменяемые — всё пропущенное возвращается к автоматической цене Apple.
- Чтобы запланировать будущее изменение для приложения или IAP, отправьте сегодняшние ручные цены с
endDate, равной новойstartDate, а следом — новые цены. Два соседних интервала с одной и той же ценовой точкой отклоняются («Adjacent intervals cannot have the same price point»), поэтому неизменённую территорию отправляйте одной записью без окончания. - У подписок не больше одной будущей цены на территорию. Удалите стоящую в очереди через `DELETE /v1/subscriptionPrices/{id}`, прежде чем создавать другую.
- Цена подписки без даты начала — это начальная цена. После одобрения подписки для дальнейших цен нужен
startDate; иначе API отвечает ошибкой состояния 409. - Снижение цены подписки применяется к действующим подписчикам, а любое изменение подписки после вступления в силу вернуть нельзя. Повышения могут требовать согласия — см. повышение цены подписки.
- Списки ценовых точек велики. Всегда фильтруйте по территории и используйте постраничную выдачу.
- Токены для этих конечных точек живут не больше 20 минут; долгим задачам нужно подписывать заново.
- Изменения могут появляться в песочнице до часа.
- В API нигде не спрашивают «вы уверены?». Шаг проверки придётся сделать самим.
Как безопасно тестировать скрипт для цен
Тестовой копии вашего аккаунта App Store Connect нет, поэтому безопасность нужно встроить в сам скрипт:
- Добавьте в скрипт флаг пробного запуска (dry run): он считает всё и печатает таблицу «продукт, территория, текущая цена, новая цена», но ничего не отправляет.
- Перед записью прочитайте действующий график или цены и сравните с планом; пропускайте территории, где уже стоит целевая цена.
- Первую настоящую запись выполните на одном продукте, который ещё не в продаже, или на одной территории и прочитайте результат обратно.
- Пишите строку журнала на каждую территорию со старой и новой ценовой точкой. Если что-то пойдёт не так, по этому журналу вы вернёте цены.
- Храните ключ в хранилище секретов, а не в репозитории, и выдайте скрипту отдельный ключ, чтобы его можно было отозвать независимо.
Обойтись без скрипта: RepriceCat
RepriceCat — по сути, это данное руководство в виде продукта. Вы подключаете собственный командный ключ (он хранится в зашифрованном виде и отзывается в любой момент), а сервис получает ценовые точки, округляет цены уровней до допустимых точек, строит графики — включая перенос сегодняшних цен для запланированных изменений — и сам укладывается в лимит запросов.
- Таблица проверки «продукт × страна», сегодняшняя цена → новая цена, до отправки чего-либо; пробный запуск, который ничего не отправляет.
- До 200 продуктов из разных приложений в одном изменении, сейчас или на выбранную дату.
- Страны, где не получилось, показываются с причиной от Apple и отправляются повторно отдельно; каждое изменение журналируется по странам с откатом.
- Обмен с таблицами: экспортируйте цены в XLSX или CSV, правьте и импортируйте обратно.
Выбираете между «написать самому» и «купить»? Прочитайте RepriceCat против скриптов на API или начните с бесплатного месяца.
Частые вопросы
Какая роль нужна ключу API App Store Connect, чтобы менять цены?
Admin или App Manager. В справке Apple о ценах в качестве ролей, которые могут управлять ценами, указаны Account Holder, Admin или App Manager; ключи с ролями Developer, Marketing, Sales или Finance этого не могут.
Может ли API изменить цены для всех территорий одним запросом?
Для приложений и встроенных покупок — да: один график цен несёт базовую территорию и все ручные цены. Для подписок каждая территория — отдельный ресурс subscriptionPrices, поэтому изменение по всему миру — до 175 запросов на подписку.
Как получить выровненные цены Apple через API?
Найдите ценовую точку для вашей базовой цены и вызовите её конечную точку equalizations. Она возвращает сопоставимую ценовую точку в каждой другой витрине, которую можно использовать как есть или как округлённую цену для регионального уровня.
Есть ли песочница или режим пробного запуска для вызовов, меняющих цены?
Нет. Графики цен действуют на реальный аккаунт. Тщательно проверяйте рассчитанный пакет, тестируйте на продукте, который ещё не вышел, или используйте инструмент со своим пробным запуском.
Каков лимит запросов API App Store Connect?
Лимиты действуют на ключ API за скользящий час и сообщаются в заголовке X-Rate-Limit каждого ответа. В примере Apple указано 3 500 запросов в час, но сказано, что реальные лимиты различаются; при превышении возвращается HTTP 429.
Как отменить запланированное изменение цены через API?
Для подписки удалите ожидающий ресурс subscriptionPrices. Для приложения или встроенной покупки отправьте новый график без будущей записи, помня, что POST заменяет весь график.
Попробуйте
Новые цены во всех странах от одной базовой цены
Уровни, привязка к ценовым точкам, одна таблица проверки, одно подтверждение — через App Store Connect API. Первый месяц бесплатно, затем $1 за приложение в месяц.