API objects
Adapty API has JSON objects so you can understand a response structure and wrap it into your code.
All datetime values are ISO 8601, for example, “2020-01-15T15:10:36.517975+0000”.
Access level
Info about customer’s access level.
Access levels let you control what your app’s users can do in your mobile app without hardcoding specific product IDs. Each product defines how long the user gets a certain access level. So, whenever a user makes a purchase, Adapty grants access to the app for a specific period (for subscriptions) or forever (for lifetime purchases). Alternatively, you can grant specific access for a specified time to a user via server-side API.
You can do the following action via Adapty server-side API:
- Check users’s access level by retrieving their profile details
- Grant specific access to your end user without providing a transaction
- Set transaction and grant access level to your end user
- Revoke access level from your end user
| 参数 | 类型 | 必填 | 可为空 | 描述 |
|---|---|---|---|---|
| access_level_id | String | 是 | 否 | 在 Adapty 看板中设置的付费访问等级 ID。 |
| store | String | 是 | 否 | 购买产品的应用商店。可选值：app_store、play_store、stripe，或您的自定义商店名称。 |
| store_product_id | String | 是 | 否 | 解锁该访问等级的产品在应用商店（如 App Store、Google Play、Stripe）中的 ID。 |
| store_base_plan_id | String | 是 | 是 | Google Play 中的基础方案 ID 或 Stripe 中的价格 ID。 |
| store_transaction_id | String | 是 | 否 | 应用商店（App Store、Google Play、Stripe 等）中的交易 ID。 |
| 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。 |
Although the SDK includes the is_active parameter to check if a subscription is active, the server-side API does not provide this parameter. However, you can determine subscription status at any time by checking whether the current date falls between the starts_at and expires_at parameters.
Installation Meta
Information about installation of the app on a specific device.
You can do the following action via Adapty server-side API:
| Parameter | Type | Required | Nullable | Description |
|---|---|---|---|---|
| device_id | String | Yes | No | The device identifier is generated on the client side. |
| device | String | No | Yes | The end-user-visible device model name. |
| locale | String | No | Yes | The locale used by the end user. |
| os | String | No | Yes | The operating system used by the end user. |
| platform | String | No | Yes | The device platform used by the end user. |
| timezone | String | No | Yes | The timezone of the end user. |
| user_agent | String | No | Yes | Details about the end user environment: device, operating system, and browser information of the end user interacting with your application. |
| idfa | String | No | Yes | The Identifier for Advertisers, assigned by Apple to a user’s device. |
| idfv | String | No | Yes | The Identifier for Vendors (IDFV) is a code assigned to all apps by one developer and is shared across all apps by that developer on your device. |
| advertising_id | String | No | Yes | The Advertising ID is a unique identifier offered by the Android Operating System that advertisers might use to uniquely identify you. |
| android_id | String | No | Yes | On Android 8.0 (API level 26) and higher versions of the platform, a 64-bit number (expressed as a hexadecimal string), unique to each combination of app-signing key, user, and device. For more details, see Android developer documentation. |
| android_app_set_id | String | No | Yes | An AppSetId - unique, per-device, per developer-account user-resettable ID for non-monetizing advertising use cases. |
Non Subscription
Info about non-subscription purchases. These can be one-time (consumable) products, unlocks (like new map unlock in the game), etc.
You can do the following action via Adapty server-side API:
- Check user’s current non-subscriptions by retrieving their profile details
| Parameter | Type | Required | Nullable | Description |
|---|---|---|---|---|
| purchase_id | String | Yes | No | Identifier of the purchase in Adapty. You can use it to ensure that you’ve already processed this purchase, for example tracking one-time products. |
| store | String | Yes | No | Store where the product was purchased. Possible values are: app_store, play_store, stripe, name of your custom store. |
| store_product_id | String | Yes | No | Identifier of the product in the app store (App Store/Google Play/Stripe, etc.) that unlocked this access level. |
| store_base_plan_id | String | Yes | Yes | Base plan ID in the Google Play Store or price ID in Stripe. |
| store_transaction_id | String | Yes | No | The ID of the transaction in the app store (App Store/Google Play/Stripe, etc.). |
| store_original_transaction_id | String | Yes | No | In case of prolonged subscriptions, a chain of subscriptions is generated. The original transaction i the very first transaction in this chain and the chain is linked by it. Other transactions in the chain are prolongations. If no prolongation, |
| purchased_at | ISO 8601 date | Yes | No | The datetime when the access level was purchased the latest time. |
| environment | String | No | No | Environment of the transaction that provided the access level. Possible values: Sandbox, Production. |
| is_refund | Boolean | Yes | No | Indicates if the product has been refunded. |
| is_consumable | Boolean | Yes | No | Indicates whether the product is consumable. |
One-Time Purchase
| Parameter | Type | Required | Nullable | Description |
|---|---|---|---|---|
| purchase_type | String | 是 | 否 | 购买的产品类型。可选值：one_time_purchase。 |
| store | String | 是 | 否 | 购买产品的商店。可选值：app_store、play_store、stripe，或您的自定义商店的 Store ID。 |
| environment | String | 否 | 否 | 提供访问等级的交易环境。可选值：Sandbox、Production。默认使用 Production。 |
| store_product_id | String | 是 | 否 | 解锁该访问等级的产品在应用商店（App Store、Google Play、Stripe 等）中的产品 ID。 |
| store_transaction_id | String | 是 | 否 | 应用商店（App Store、Google Play、Stripe 等）中的交易 ID。 |
| store_original_transaction_id | String | 是 | 否 | 对于自动续订订阅，这是关联一系列续订记录的原始交易 ID。原始交易是链中的第一笔；后续交易为续订。 如果没有续订， |
| offer | Object | 否 | 是 | 购买时使用的优惠，以 Offer 对象表示。 |
| is_family_shared | Boolean | 否 | 否 | 布尔值，表示该产品是否在 App Store Connect 中支持家庭共享。仅限 iOS。iOS 14.0 以下及 macOS 11.0 以下始终为 false。默认值为 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
Information on the applied offer. The Offer object is a part of the Subscription, and Access level objects.
You can do the following actions with offers via Adapty server-side API:
- Apply offer when setting a transaction to your user
| Parameter | Type | Required | Nullable | Description |
|---|---|---|---|---|
| category | String | Yes | No | The category of the applied offer. Options are: introductory, promotional, offer_code, win_back. |
| type | String | Yes | No | The type of active offer. Options are: free_trial, pay_as_you_go, pay_up_front, and unknown. If this isn’t null, it means the offer was applied in the current subscription period. |
| id | String | No | Yes | The ID of the applied offer. |
Price
Information about the cost of your product in local currency. The Price object is a part of the Subscri S ption and Purchase objects.
You can do the following actions with product price via Adapty server-side API:
- Set transaction to your user and specify its price
| Parameter | Type | Required | Nullable | Description |
|---|---|---|---|---|
| country | String | Yes | No | The country where the price applies. |
| currency | String | Yes | No | The currency used for the price. |
| value | Float | Yes | No | The product’s cost in the local currency. |
Profile
Info about the customer and their subscription
You can do the following actions with user profiles via Adapty server-side API:
- Retrieve/get the end-user’s profile with their access levels, subscriptions, non-subscriptions, etc.
- Create a new end-user profile
- Update your end-user profile
- Delete your end-user
| 参数 | 类型 | 可为空 | 描述 |
|---|---|---|---|
| app_id | String | :heavy_minus_sign: | 您应用的内部 ID。可在 Adapty 看板中查看：App Settings -> General tab。 |
| profile_id | UUID | :heavy_minus_sign: | Adapty 用户画像 ID。可在 Adapty 看板 -> Profiles -> 具体用户画像页面的 Adapty ID 字段中查看。 |
| customer_user_id | String | :heavy_plus_sign: | 您的用户在您系统中的 ID。可在 Adapty 看板 -> Profiles -> 具体用户画像页面的 Customer user ID 字段中查看。仅当您通过 Adapty SDK 在移动应用代码中识别用户时才会生效。 |
| total_revenue_usd | Float | :heavy_minus_sign: | 浮点数，表示该用户画像累计获得的 USD 总收入。 |
| segment_hash | String | :heavy_minus_sign: | 内部参数。 |
| timestamp | Integer | :heavy_minus_sign: | 响应时间（毫秒），用于解决竞态条件。 |
| custom_attributes | Array | :heavy_minus_sign: | 每个用户画像最多可设置 30 个自定义属性。如果提供 Key： 键必须为字符串，且不超过 30 个字符。只允许使用字母、数字、短横线、点和下划线。 Value： 属性值不超过 30 个字符。只允许使用字符串和浮点数作为值，布尔值将被转换为浮点数。发送空值或 null 可删除该属性。 |
| access_levels | Array | :heavy_plus_sign: | 访问等级对象数组。如果用户没有访问等级，可为 null。 |
| subscriptions | Array | :heavy_plus_sign: | 订阅对象数组。如果用户没有订阅，可为 null。 |
| non_subscriptions | Array | :heavy_plus_sign: | 非订阅对象数组。如果用户没有购买记录，可为 null。 |
Product
This object contains details about a product in Adapty.
| Name | Type | Required | Description |
|---|---|---|---|
| title | String | No | Product name from the Products section in the Adapty Dashboard. |
| is_consumable | Boolean | Yes | Indicates whether the product is consumable. |
| adapty_product_id | UUID | No | Internal product ID as used in Adapty. |
| vendor_product_id | String | Yes | The product ID in app stores. If access was granted without a real store transaction,
|
| introductory_offer_eligibility | Boolean | No | Specifies if the user is eligible for an iOS introductory offer. |
| promotional_offer_eligibility | Boolean | No | Specifies if the user is eligible for a promotional offer. |
| base_plan_id | String | No | Base plan ID for Google Play or price ID for Stripe. |
| offer | JSON | No | An Offer object as a 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
This object contains information about a remote config for a paywall.
{
"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}}"
}
| Name | Type | Required | Description |
|---|---|---|---|
| lang | String | Yes | Locale code for the paywall localization. It uses language and region subtags separated by a hyphen (-). Examples: Refer to Localizations and locale codes for more details. |
| data | String | Yes | Serialized JSON string representing the remote config of your paywall. You can find it in the Remote Config tab of a specific paywall in the Adapty Dashboard. |
Subscription
Info about your end user subscription. You can do the following action via Adapty server-side API:
- Check the user’s current subscription by retrieving their profile details
- Set transaction to your user and grant a subscription to them
| 参数 | 类型 | 必填 | 可为空 | 描述 |
|---|---|---|---|---|
| purchase_type | String | 是 | 否 | 已购买产品的类型。可选值：subscription。 |
| store | String | 是 | 否 | 购买产品的商店。选项包括 app_store、play_store、stripe，或您的自定义商店的 Store ID。 |
| environment | String | 否 | 否 | 交易发生的环境。选项为 Sandbox 或 Production，默认使用 Production。 |
| store_product_id | String | 是 | 否 | 解锁此访问等级的应用商店（App Store、Google Play、Stripe 等）中的产品 ID。 |
| store_transaction_id | String | 是 | 否 | 应用商店（App Store、Google Play、Stripe 等）中的交易 ID。 |
| store_original_transaction_id | String | 是 | 否 | 对于订阅，此 ID 关联续期链中的首笔交易，每次续期均与该原始交易相关联。 如果没有续期， |
| offer | Object | 否 | 是 | 购买时使用的优惠，以 Offer 对象的形式提供。 |
| is_family_shared | Boolean | 否 | 否 | 布尔值，表示该产品是否在 App Store Connect 中支持家庭共享。仅限 iOS。iOS 14.0 以下及 macOS 11.0 以下始终为 false，默认值为 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 | 否 | 否 | 若订阅当前处于宽限期，此字段为宽限期结束的日期时间。 |
Although the SDK includes the is_active parameter to check if a subscription is active, the server-side API does not provide this parameter. However, you can determine subscription status at any time by checking whether the current date falls between the starts_at and expires_at parameters of the Access Level object.