API objects
API Adapty использует JSON-объекты — они помогают понять структуру ответа и интегрировать её в ваш код.
Все значения дат и времени соответствуют формату ISO 8601, например: “2020-01-15T15:10:36.517975+0000”.
Уровень доступа
Информация об уровне доступа пользователя.
Уровни доступа позволяют управлять возможностями пользователей в приложении без хардкода конкретных ID продуктов. Каждый продукт определяет, на какой срок пользователь получает определённый уровень доступа. При покупке Adapty предоставляет доступ к приложению на конкретный период (для подписок) или навсегда (для покупок с пожизненным доступом). Кроме того, вы можете выдать конкретный доступ пользователю на заданный срок через серверный API.
Доступные действия через серверный API Adapty:
- Проверить уровень доступа пользователя — получить данные его профиля
- Выдать конкретный доступ пользователю без привязки к транзакции
- Установить транзакцию и выдать уровень доступа пользователю
- Отозвать уровень доступа у пользователя
| Параметр | Тип | Обязательный | Nullable | Описание |
|---|---|---|---|---|
| access_level_id | String | Да | Нет | ID уровня доступа, настроенного в дашборде Adapty. |
| store | String | Да | Нет | Стор, в котором был куплен продукт. Варианты: app_store, play_store, stripe или название вашего кастомного стора. |
| store_product_id | String | Да | Нет | ID продукта в сторе (App Store, Google Play, Stripe), который открыл этот уровень доступа. |
| store_base_plan_id | String | Да | Да | ID базового плана в Google Play или ID цены в Stripe. |
| store_transaction_id | String | Да | Нет | ID транзакции в сторе (App Store, Google Play, Stripe и др.). |
| store_original_transaction_id | String | Да | Нет | Для подписок этот ID связывает исходную транзакцию в цепочке продлений. Последующие транзакции привязываются как продления. Если продлений нет, store_original_transaction_id совпадает с store_transaction_id. |
| offer | Object | Да | Нет | Объект Offer. Может быть null, если у пользователя нет уровней доступа. |
| environment | String | Нет | Нет | Среда транзакции, предоставившей доступ. Варианты: Sandbox, Production. |
| starts_at | ISO 8601 date | Да | Да | Дата и время, когда уровень доступа становится активным. Может быть в будущем. |
| purchased_at | ISO 8601 date | Да | Нет | Дата и время последней покупки для данного уровня доступа. |
| originally_purchased_at | ISO 8601 date | Да | Нет | Для подписок — дата и время самой первой (исходной) покупки в цепочке, привязанной к store_original_transaction_id. |
| expires_at | ISO 8601 date | Да | Да | Дата и время истечения уровня доступа. Может быть в прошлом или null для пожизненного доступа. |
| renewal_cancelled_at | ISO 8601 date | Да | Да | Дата и время, когда для подписки было отключено автопродление. Подписка при этом может оставаться активной — она просто не будет продлеваться. Устанавливается в null, если пользователь повторно активирует подписку. |
| billing_issue_detected_at | ISO 8601 date | Да | Да | Дата и время обнаружения проблемы с оплатой (например, неудачного списания с карты). Подписка при этом может оставаться активной. Сбрасывается, если платёж впоследствии проходит успешно. |
| is_in_grace_period | Boolean | Да | Нет | Показывает, находится ли подписка в льготном периоде (только для автовозобновляемых подписок). |
| cancellation_reason | String | Да | Да | Причина отмены. Возможные значения: voluntarily_cancelled, billing_error, price_increase, product_was_not_available, refund, upgraded, unknown. |
SDK содержит параметр is_active для проверки активности подписки, однако серверный API этот параметр не возвращает. Тем не менее статус подписки можно определить в любой момент, проверив, попадает ли текущая дата в диапазон между параметрами starts_at и expires_at.
Installation Meta
Информация об установке приложения на конкретном устройстве.
Доступные действия через серверный API Adapty:
| Параметр | Тип | Обязательный | Nullable | Описание |
|---|---|---|---|---|
| device_id | String | Да | Нет | Идентификатор устройства, генерируется на стороне клиента. |
| device | String | Нет | Да | Название модели устройства, видимое конечному пользователю. |
| locale | String | Нет | Да | Локаль, используемая конечным пользователем. |
| os | String | Нет | Да | Операционная система конечного пользователя. |
| platform | String | Нет | Да | Платформа устройства конечного пользователя. |
| timezone | String | Нет | Да | Часовой пояс конечного пользователя. |
| user_agent | String | Нет | Да | Сведения об окружении конечного пользователя: устройство, операционная система и браузер, с которого пользователь взаимодействует с вашим приложением. |
| idfa | String | Нет | Да | Идентификатор для рекламодателей (IDFA), присваиваемый Apple устройству пользователя. |
| idfv | String | Нет | Да | Идентификатор для вендоров (IDFV) — код, назначаемый всем приложениям одного разработчика и общий для всех его приложений на устройстве. |
| advertising_id | String | Нет | Да | Уникальный рекламный идентификатор, предоставляемый операционной системой Android, который рекламодатели могут использовать для однозначной идентификации пользователя. |
| android_id | String | Нет | Да | На Android 8.0 (API уровень 26) и выше — 64-битное число (в виде шестнадцатеричной строки), уникальное для каждой комбинации ключа подписи приложения, пользователя и устройства. Подробнее см. в документации для разработчиков Android. |
| android_app_set_id | String | Нет | Да | Идентификатор AppSetId — уникальный, сбрасываемый пользователем ID для каждого устройства и аккаунта разработчика, предназначенный для рекламных сценариев без монетизации. |
Non Subscription
Информация о покупках без подписки. Это могут быть разовые (расходуемые) продукты, разблокировки (например, новая карта в игре) и т. д.
Доступные действия через серверный API Adapty:
- Проверить текущие покупки без подписки пользователя — получить данные его профиля
| Параметр | Тип | Обязательный | Nullable | Описание |
|---|---|---|---|---|
| purchase_id | String | Да | Нет | Идентификатор покупки в Adapty. Можно использовать, чтобы убедиться, что эта покупка уже обработана, — например, при отслеживании разовых продуктов. |
| store | String | Да | Нет | Стор, в котором был куплен продукт. Возможные значения: app_store, play_store, stripe, название вашего кастомного стора. |
| store_product_id | String | Да | Нет | Идентификатор продукта в сторе (App Store / Google Play / Stripe и т. д.), открывшего данный уровень доступа. |
| store_base_plan_id | String | Да | Да | Идентификатор базового плана в Google Play Store или идентификатор цены в Stripe. |
| store_transaction_id | String | Да | Нет | Идентификатор транзакции в сторе (App Store / Google Play / Stripe и т. д.). |
| store_original_transaction_id | String | Да | Нет | При продлении подписок формируется цепочка транзакций. Исходная транзакция — самая первая в этой цепочке, и все остальные транзакции связаны с ней. Остальные транзакции в цепочке являются продлениями. Если продления не было, |
| purchased_at | ISO 8601 date | Да | Нет | Дата и время последней покупки уровня доступа. |
| environment | String | Нет | Нет | Среда транзакции, предоставившей уровень доступа. Возможные значения: Sandbox, Production. |
| is_refund | Boolean | Да | Нет | Указывает, был ли продукт возвращён. |
| is_consumable | Boolean | Да | Нет | Указывает, является ли продукт расходуемым. |
Разовая покупка
| Параметр | Тип | Обязательный | Nullable | Описание |
|---|---|---|---|---|
| purchase_type | String | Да | Нет | Тип приобретённого продукта. Возможное значение: one_time_purchase. |
| store | String | Да | Нет | Стор, в котором был куплен продукт. Возможные значения: app_store, play_store, stripe или Store ID вашего кастомного стора. |
| environment | String | Нет | Нет | Окружение транзакции, предоставившей уровень доступа. Варианты: Sandbox, Production. По умолчанию используется Production. |
| store_product_id | String | Да | Нет | ID продукта в сторе (App Store, Google Play, Stripe и т.д.), который открыл этот уровень доступа. |
| store_transaction_id | String | Да | Нет | ID транзакции в сторе (App Store, Google Play, Stripe и т.д.). |
| store_original_transaction_id | String | Да | Нет | Для повторяющихся подписок — это исходный ID транзакции, связывающий цепочку продлений. Исходная транзакция является первой в цепочке; последующие транзакции — это продления. Если продлений нет, |
| offer | Object | Нет | Да | Оффер, использованный при покупке, в виде объекта Offer. |
| is_family_shared | Boolean | Нет | Нет | Булево значение, указывающее, поддерживает ли продукт семейный доступ в App Store Connect. Только для iOS. Всегда false для iOS ниже 14.0 и macOS ниже 11.0. По умолчанию используется false. |
| price | Object | Да | Нет | Цена разовой покупки в виде объекта Price. Первоначальная покупка подписки с нулевой стоимостью является бесплатным пробным периодом; продление с нулевой стоимостью — бесплатным продлением. |
| purchased_at | ISO 8601 date | Да | Нет | Дата и время последней покупки уровня доступа. |
| refunded_at | ISO 8601 date | Нет | Нет | Если был выполнен возврат средств, отображает дату и время возврата. |
| cancellation_reason | String | Нет | Нет | Возможные причины отмены: voluntarily_cancelled, billing_error, price_increase, product_was_not_available, refund, cancelled_by_developer, new_subscription, unknown. |
| variation_id | String | Нет | Нет | ID варианта, используемый для отслеживания покупок до конкретного пейвола, с которого они были совершены. |
Offer
Информация о применённом офере. Объект Offer входит в состав объектов Subscription и Access level.
Доступные действия с оферами через серверный API Adapty:
- Применить офер при установке транзакции пользователю
| Параметр | Тип | Обязательный | Nullable | Описание |
|---|---|---|---|---|
| category | String | Да | Нет | Категория применённого офера. Варианты: introductory, promotional, offer_code, win_back. |
| type | String | Да | Нет | Тип активного офера. Варианты: free_trial, pay_as_you_go, pay_up_front и unknown. Если значение не равно null, это означает, что офер был применён в текущем расчётном периоде подписки. |
| id | String | Нет | Да | Идентификатор применённого офера. |
Price
Информация о стоимости продукта в местной валюте. Объект Price входит в состав объектов Subscription и Purchase.
Доступные действия с ценой продукта через серверный API Adapty:
- Установить транзакцию пользователю и указать её цену
| Параметр | Тип | Обязательный | Nullable | Описание |
|---|---|---|---|---|
| country | String | Да | Нет | Страна, для которой применяется цена. |
| currency | String | Да | Нет | Валюта цены. |
| value | Float | Да | Нет | Стоимость продукта в местной валюте. |
Profile
Информация о пользователе и его подписке.
Доступные действия с профилями пользователей через серверный API Adapty:
- Получить профиль пользователя с его уровнями доступа, подписками, покупками без подписки и т. д.
- Создать новый профиль пользователя
- Обновить профиль пользователя
- Удалить пользователя
| Параметр | Тип | Nullable | Описание |
|---|---|---|---|
| app_id | String | :heavy_minus_sign: | Внутренний ID вашего приложения. Можно найти в дашборде Adapty: App Settings -> General tab. |
| profile_id | UUID | :heavy_minus_sign: | ID профиля Adapty. Можно найти в поле Adapty ID на дашборде Adapty -> Profiles -> страница конкретного профиля. |
| customer_user_id | String | :heavy_plus_sign: | ID вашего пользователя в вашей системе. Можно найти в поле Customer user ID на дашборде Adapty -> Profiles -> страница конкретного профиля. Работает только если вы идентифицируете пользователей в коде мобильного приложения через Adapty SDK. |
| total_revenue_usd | Float | :heavy_minus_sign: | Число с плавающей точкой, представляющее общую выручку профиля в долларах США. |
| segment_hash | String | :heavy_minus_sign: | Внутренний параметр. |
| timestamp | Integer | :heavy_minus_sign: | Время ответа в миллисекундах, необходимо для разрешения состояния гонки. |
| custom_attributes | Array | :heavy_minus_sign: | Для профиля можно задать не более 30 пользовательских атрибутов. Если передаёте массив Ключ: строка длиной не более 30 символов. Допустимы только буквы, цифры, дефисы, точки и символы подчёркивания. Значение: не более 30 символов. Допустимы только строки и числа с плавающей точкой; булевы значения преобразуются в числа с плавающей точкой. Передайте пустое значение или null, чтобы удалить атрибут. |
| access_levels | Array | :heavy_plus_sign: | Массив объектов уровня доступа. Может быть null, если у пользователя нет уровней доступа. |
| subscriptions | Array | :heavy_plus_sign: | Массив объектов подписки. Может быть null, если у пользователя нет подписок. |
| non_subscriptions | Array | :heavy_plus_sign: | Массив объектов разовых покупок. Может быть null, если у пользователя нет покупок. |
Product
Объект содержит подробную информацию о продукте в Adapty.
| Название | Тип | Обязательный | Описание |
|---|---|---|---|
| title | String | Нет | Название продукта из раздела Products дашборда Adapty. |
| is_consumable | Boolean | Да | Указывает, является ли продукт расходуемым. |
| adapty_product_id | UUID | Нет | Внутренний идентификатор продукта в Adapty. |
| vendor_product_id | String | Да | Идентификатор продукта в сторах. |
| introductory_offer_eligibility | Boolean | Нет | Указывает, доступен ли пользователю introductory offer на iOS. |
| promotional_offer_eligibility | Boolean | Нет | Указывает, доступен ли пользователю promotional offer. |
| base_plan_id | String | Нет | Идентификатор базового плана для Google Play или идентификатор цены для Stripe. |
| offer | JSON | Нет | Объект Offer в формате JSON. |
{
"title": "Monthly Subscription w/o Trial",
"is_consumable": true,
"adapty_product_id": "InternalProductId",
"vendor_product_id": "onemonth_no_trial",
"introductory_offer_eligibility": false,
"promotional_offer_eligibility": true,
"base_plan_id": "B1",
"offer": {
"category": "promotional",
"type": "pay_up_front",
"id": "StoreOfferId"
}
}
RemoteConfig
Объект содержит информацию о Remote Config пейвола.
{
"lang": "en",
"data": "{\"bodyItems\":[{\"spacerValue\":{\"height\":20,\"style\":{\"type\":\"emptySpace\"}},\"type\":\"spacer\"},{\"mediaValue\":{\"ratio\":\"1:1\",\"source\":{\"fileType\":\"image\",\"reference\":{\"en\":\"bundle/images/new1.png\"}},\"widthStyle\":\"full\"},\"type\":\"media\"},{\"titleValue\":{\"alignment\":\"center\",\"subtitleConfig\":{\"fontSize\":17,\"text\":\"\",\"color\":\"#FFFFFF\"},\"titleConfig\":{\"fontSize\":22,\"text\":\"\"}},\"type\":\"title\"},{\"productListValue\":{\"items\":[{\"productId\":\"exampleapp.oneWeek\",\"promoText\":\"paywall.promo-1.title\",\"backgroundColor\":\"#0B867D\"},{\"discountRate\":80,\"productId\":\"exampleapp.oneYear\",\"promoText\":\"paywall.promo-2.title\",\"backgroundColor\":\"#0B867D\"}],\"layout\":\"vertical\"},\"type\":\"productList\"}],\"defaultProductId\":\"exampleapp.oneWeek\",\"footer\":{\"singleProductValue\":{\"customTitles\":{\"exampleapp.oneWeek\":\"Subscribe\",\"exampleapp.oneYear\":\"Subscribe\"},\"productId\":\"exampleapp.oneWeek\"},\"type\":\"singleProduct\"},\"id\":\"exampleapp\",\"isFullScreen\":true,\"settings\":{\"backgroundColor\":\"#000000\",\"closeButtonAlignment\":\"left\",\"closeButtonIconStyle\":\"light\",\"colorScheme\":{\"accent\":\"#007566\",\"background\":\"#001B0D\",\"label\":\"#FFFFFF\",\"primary\":\"#10C6B6\",\"secondaryLabel\":\"#FFFFFF\",\"seperator\":\"#FFFFFF\"},\"isFullScreen\":true,\"shouldShowAlertOnClose\":false,\"showCloseButtonAfter\":1,\"triggerPurchaseWithAlert\":false,\"triggerPurchaseWithProductChange\":false}}"
}
| Название | Тип | Обязательный | Описание |
|---|---|---|---|
| lang | String | Да | Код локали для локализации пейвола. Используются языковые и региональные подтеги, разделённые дефисом (-). Примеры: Подробнее см. в разделе Локализации и коды локалей. |
| data | String | Да | Сериализованная JSON-строка, представляющая Remote Config вашего пейвола. Найти её можно на вкладке Remote Config конкретного пейвола в дашборде Adapty. |
Subscription
Информация о подписке конечного пользователя. Доступные действия через серверный API Adapty:
- Проверить текущую подписку пользователя — получить данные его профиля
- Установить транзакцию пользователю и выдать ему подписку
| Параметр | Тип | Обязательный | Nullable | Описание |
|---|---|---|---|---|
| purchase_type | String | Да | Нет | Тип приобретённого продукта. Возможное значение: subscription. |
| store | String | Да | Нет | Стор, в котором был куплен продукт. Возможные значения: app_store, play_store, stripe или Store ID вашего кастомного стора. |
| environment | String | Нет | Нет | Среда, в которой была выполнена транзакция. Возможные значения: Sandbox или Production. По умолчанию используется Production. |
| store_product_id | String | Да | Нет | ID продукта в магазине приложений (App Store, Google Play, Stripe и т.д.), открывшего данный уровень доступа. |
| store_transaction_id | String | Да | Нет | ID транзакции в магазине приложений (App Store, Google Play, Stripe и т.д.). |
| store_original_transaction_id | String | Да | Нет | Для подписок этот ID связан с первой транзакцией в цепочке продлений. Каждое продление привязано к этой исходной транзакции. Если продлений не было, |
| offer | Object | Нет | Да | Оффер, использованный при покупке, в виде объекта Offer. |
| is_family_shared | Boolean | Нет | Нет | Булево значение, указывающее, поддерживает ли продукт семейный доступ в App Store Connect. Только для iOS. Всегда false для iOS ниже 14.0 и macOS ниже 11.0. По умолчанию используется false. |
| price | Object | Да | Нет | Цена подписки или покупки в виде объекта Price. Первичная покупка подписки с нулевой стоимостью является бесплатным пробным периодом; продление с нулевой стоимостью — бесплатным продлением. |
| purchased_at | ISO 8601 date | Да | Нет | Дата и время последней покупки уровня доступа. |
| refunded_at | ISO 8601 date | Нет | Нет | Дата и время возврата средств за подписку, если применимо. |
| cancellation_reason | String | Нет | Нет | Возможные причины отмены: voluntarily_cancelled, billing_error, price_increase, product_was_not_available, refund, upgraded или unknown. |
| variation_id | String | Нет | Нет | ID варианта, используемый для отслеживания покупок до конкретного пейвола, с которого они были совершены. |
| originally_purchased_at | ISO 8601 date | Да | Нет | Для цепочек подписок — дата покупки исходной транзакции, связанной через store_original_transaction_id. |
| expires_at | ISO 8601 date | Да | Нет | Дата и время истечения уровня доступа. Может быть в прошлом и null для пожизненного доступа. |
| renew_status | Boolean | Да | Нет | Указывает, включено ли автопродление для подписки. |
| renew_status_changed_at | ISO 8601 date | Нет | Нет | Дата и время, когда автопродление было включено или отключено. |
| billing_issue_detected_at | ISO 8601 date | Нет | Нет | Дата и время обнаружения проблемы с оплатой (например, неудачного списания с карты). Подписка при этом может оставаться активной. Сбрасывается, если платёж проходит успешно. |
| grace_period_expires_at | ISO 8601 date | Нет | Нет | Дата и время окончания льготного периода, если подписка в нём находится. |
SDK содержит параметр is_active для проверки активности подписки, однако серверный API этот параметр не возвращает. Тем не менее статус подписки можно определить в любой момент, проверив, попадает ли текущая дата в диапазон между параметрами starts_at и expires_at объекта Access Level.