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

Parameter	Type	Required	Nullable	Description
access_level_id	String	Yes	No	ID của mức độ truy cập có trả phí được thiết lập trong Adapty Dashboard.
store	String	Yes	No	Cửa hàng nơi sản phẩm được mua. Các tùy chọn: app_store, play_store, stripe, hoặc tên cửa hàng tùy chỉnh của bạn.
store_product_id	String	Yes	No	ID của sản phẩm trong cửa hàng ứng dụng (như App Store, Google Play, Stripe) đã mở khóa mức độ truy cập này.
store_base_plan_id	String	Yes	Yes	Base plan ID trong Google Play hoặc price ID trong Stripe.
store_transaction_id	String	Yes	No	ID giao dịch trong cửa hàng ứng dụng (App Store, Google Play, Stripe, v.v.).
store_original_transaction_id	String	Yes	No	Đối với các gói đăng ký, ID này liên kết giao dịch gốc trong chuỗi gia hạn. Các giao dịch sau được liên kết dưới dạng gia hạn. Nếu không có gia hạn, store_original_transaction_id trùng với store_transaction_id.
offer	Object	Yes	No	Đối tượng Offer. Có thể là `null` nếu khách hàng không có mức độ truy cập nào.
environment	String	No	No	Môi trường của giao dịch đã cấp quyền truy cập. Các tùy chọn: `Sandbox`, `Production`.
starts_at	ISO 8601 date	Yes	Yes	Ngày giờ mức độ truy cập bắt đầu có hiệu lực. Có thể là thời điểm trong tương lai.
purchased_at	ISO 8601 date	Yes	No	Ngày giờ của lần mua gần nhất cho mức độ truy cập này.
originally_purchased_at	ISO 8601 date	Yes	No	Đối với các gói đăng ký, đây là ngày giờ của lần mua đầu tiên (gốc) trong chuỗi, gắn với `store_original_transaction_id`.
expires_at	ISO 8601 date	Yes	Yes	Ngày giờ mức độ truy cập hết hạn. Có thể là thời điểm trong quá khứ, hoặc `null` đối với quyền truy cập trọn đời.
renewal_cancelled_at	ISO 8601 date	Yes	Yes	Ngày giờ tự động gia hạn bị tắt cho một gói đăng ký. Gói đăng ký vẫn có thể còn hiệu lực; chỉ là sẽ không tự động gia hạn nữa. Đặt thành `null` nếu người dùng kích hoạt lại gói đăng ký.
billing_issue_detected_at	ISO 8601 date	Yes	Yes	Ngày giờ phát hiện sự cố thanh toán (như thẻ bị từ chối). Gói đăng ký vẫn có thể còn hiệu lực. Giá trị này sẽ được xóa nếu thanh toán thành công sau đó.
is_in_grace_period	Boolean	Yes	No	Cho biết gói đăng ký có đang trong thời gian ân hạn hay không (chỉ áp dụng cho gói đăng ký tự động gia hạn).
cancellation_reason	String	Yes	Yes	Lý do hủy, với các tùy chọn như: `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, `store_original_transaction_id` will coincide with `store_transaction_id`.
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

Tham số	Kiểu	Bắt buộc	Nullable	Mô tả
purchase_type	String	Yes	No	Loại sản phẩm đã mua. Giá trị có thể có: `one_time_purchase`.
store	String	Yes	No	Cửa hàng nơi sản phẩm được mua. Giá trị có thể có: `app_store`, `play_store`, `stripe`, hoặc Store ID của cửa hàng tùy chỉnh của bạn.
environment	String	No	No	Môi trường giao dịch cung cấp mức độ truy cập. Các tùy chọn: `Sandbox`, `Production`. Mặc định sử dụng `Production`.
store_product_id	String	Yes	No	ID sản phẩm trong app store (App Store, Google Play, Stripe, v.v.) đã mở khóa mức độ truy cập này.
store_transaction_id	String	Yes	No	ID giao dịch trong app store (App Store, Google Play, Stripe, v.v.).
store_original_transaction_id	String	Yes	No	Đối với các gói đăng ký định kỳ, đây là ID giao dịch gốc liên kết chuỗi các lần gia hạn. Giao dịch gốc là giao dịch đầu tiên trong chuỗi; các giao dịch sau là lần gia hạn. Nếu không có gia hạn, `store_original_transaction_id` trùng với `store_transaction_id`.
offer	Object	No	Yes	Ưu đãi được sử dụng cho giao dịch mua dưới dạng đối tượng Offer.
is_family_shared	Boolean	No	No	Giá trị Boolean cho biết sản phẩm có hỗ trợ chia sẻ gia đình trong App Store Connect hay không. Chỉ dành cho iOS. Luôn là `false` với iOS dưới 14.0 và macOS dưới 11.0. Mặc định là `false`.
price	Object	Yes	No	Giá của sản phẩm mua một lần dưới dạng đối tượng Price. Lần mua gói đăng ký đầu tiên với chi phí bằng không là dùng thử miễn phí; lần gia hạn với chi phí bằng không là gia hạn miễn phí.
purchased_at	ISO 8601 date	Yes	No	Thời điểm mức độ truy cập được mua gần nhất.
refunded_at	ISO 8601 date	No	No	Nếu được hoàn tiền, hiển thị thời điểm hoàn tiền.
cancellation_reason	String	No	No	Các lý do hủy có thể có: `voluntarily_cancelled`, `billing_error`, `price_increase`, `product_was_not_available`, `refund`, `cancelled_by_developer`, `new_subscription`, `unknown`.
variation_id	String	No	No	ID biến thể dùng để theo dõi các giao dịch mua đến paywall cụ thể mà chúng được thực hiện từ đó.

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 Subscription 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

Tham số	Kiểu	Nullable	Mô tả
app_id	String	:heavy_minus_sign:	ID nội bộ của ứng dụng. Bạn có thể xem trong Adapty Dashboard: App Settings -> General tab.
profile_id	UUID	:heavy_minus_sign:	ID hồ sơ người dùng Adapty. Bạn có thể xem trong trường Adapty ID trên Adapty Dashboard -> Profiles -> trang hồ sơ cụ thể.
customer_user_id	String	:heavy_plus_sign:	ID người dùng của bạn trong hệ thống. Bạn có thể xem trong trường Customer user ID trên Adapty Dashboard -> Profiles -> trang hồ sơ cụ thể. Tham số này chỉ hoạt động nếu bạn xác định người dùng trong code ứng dụng qua Adapty SDK.
total_revenue_usd	Float	:heavy_minus_sign:	Giá trị float thể hiện tổng doanh thu tính bằng USD kiếm được từ hồ sơ người dùng.
segment_hash	String	:heavy_minus_sign:	Tham số nội bộ.
timestamp	Integer	:heavy_minus_sign:	Thời gian phản hồi tính bằng mili giây, dùng để giải quyết race condition.
custom_attributes	Array	:heavy_minus_sign:	Hồ sơ người dùng cho phép tối đa 30 thuộc tính tùy chỉnh. Nếu bạn cung cấp mảng `custom_attributes`, phải có ít nhất một khóa thuộc tính. Key: Khóa phải là chuỗi không quá 30 ký tự. Chỉ được dùng chữ cái, chữ số, dấu gạch ngang, dấu chấm và dấu gạch dưới. Value: Giá trị thuộc tính không được vượt quá 30 ký tự. Chỉ chấp nhận chuỗi và số thực (float); giá trị boolean sẽ được chuyển đổi thành float. Gửi giá trị rỗng hoặc null để xóa thuộc tính.
access_levels	Array	:heavy_plus_sign:	Mảng các đối tượng Access level. Có thể null nếu người dùng không có mức độ truy cập nào.
subscriptions	Array	:heavy_plus_sign:	Mảng các đối tượng Subscription. Có thể null nếu người dùng không có gói đăng ký nào.
non_subscriptions	Array	:heavy_plus_sign:	Mảng các đối tượng Non-Subscription. Có thể null nếu người dùng chưa có giao dịch mua nào.

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, `vendor_product_id` will be one of: `adapty_server_side_product` — granted via the server-side API. `adapty_dashboard_product` — granted manually in the Adapty Dashboard. `adapty_promotion` — legacy.
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

Name	Type	Required	Description
lang	String	Yes	Locale code for the paywall localization. It uses language and region subtags separated by a hyphen (-). Examples: `en` for English, `pt-br` for Brazilian Portuguese. 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.

Locale code for the paywall localization. It uses language and region subtags separated by a hyphen (-).

Examples: en for English, pt-br for Brazilian Portuguese.

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

Parameter	Type	Required	Nullable	Description
purchase_type	String	Yes	No	Loại sản phẩm được mua. Giá trị có thể có: `subscription`.
store	String	Yes	No	Cửa hàng nơi sản phẩm được mua. Các tùy chọn bao gồm `app_store`, `play_store`, `stripe`, hoặc Store ID của cửa hàng tùy chỉnh của bạn.
environment	String	No	No	Môi trường nơi giao dịch diễn ra. Các tùy chọn là `Sandbox` hoặc `Production`. Mặc định sử dụng `Production`.
store_product_id	String	Yes	No	ID của sản phẩm trên cửa hàng ứng dụng (App Store, Google Play, Stripe, v.v.) đã mở khóa mức độ truy cập này.
store_transaction_id	String	Yes	No	ID giao dịch trên cửa hàng ứng dụng (App Store, Google Play, Stripe, v.v.).
store_original_transaction_id	String	Yes	No	Đối với các gói đăng ký, ID này liên kết đến giao dịch đầu tiên trong chuỗi gia hạn. Mỗi lần gia hạn đều được kết nối với giao dịch gốc này. Nếu không có gia hạn, `store_original_transaction_id` sẽ khớp với `store_transaction_id`.
offer	Object	No	Yes	Ưu đãi được sử dụng trong lần mua hàng, được cung cấp dưới dạng đối tượng Offer.
is_family_shared	Boolean	No	No	Giá trị Boolean cho biết sản phẩm có hỗ trợ chia sẻ gia đình trong App Store Connect hay không. Chỉ dành cho iOS. Luôn là `false` đối với iOS dưới 14.0 và macOS dưới 11.0. Mặc định là `false`.
price	Object	Yes	No	Giá của gói đăng ký hoặc sản phẩm mua hàng dưới dạng đối tượng Price. Lần mua gói đăng ký ban đầu với chi phí bằng không là dùng thử miễn phí; gia hạn với chi phí bằng không là gia hạn miễn phí.
purchased_at	ISO 8601 date	Yes	No	Ngày giờ mua mức độ truy cập gần nhất.
refunded_at	ISO 8601 date	No	No	Ngày giờ gói đăng ký được hoàn tiền, nếu có.
cancellation_reason	String	No	No	Các lý do hủy có thể có bao gồm: `voluntarily_cancelled`, `billing_error`, `price_increase`, `product_was_not_available`, `refund`, `upgraded`, hoặc `unknown`.
variation_id	String	No	No	ID biến thể dùng để theo dõi các lần mua hàng đến paywall cụ thể mà chúng được thực hiện từ đó.
originally_purchased_at	ISO 8601 date	Yes	No	Đối với chuỗi gói đăng ký, đây là ngày mua của giao dịch gốc, được liên kết bởi `store_original_transaction_id`.
expires_at	ISO 8601 date	Yes	No	Ngày giờ mức độ truy cập hết hạn. Có thể là trong quá khứ và `null` đối với quyền truy cập trọn đời.
renew_status	Boolean	Yes	No	Cho biết tính năng tự động gia hạn có được bật cho gói đăng ký hay không.
renew_status_changed_at	ISO 8601 date	No	No	Ngày giờ tính năng tự động gia hạn được bật hoặc tắt.
billing_issue_detected_at	ISO 8601 date	No	No	Ngày giờ phát hiện sự cố thanh toán (ví dụ: thẻ bị từ chối). Gói đăng ký vẫn có thể còn hiệu lực. Thông tin này sẽ được xóa nếu thanh toán thành công.
grace_period_expires_at	ISO 8601 date	No	No	Ngày giờ thời gian ân hạn sẽ kết thúc nếu gói đăng ký hiện đang trong thời gian ân hạn.