From be943c676172413acd39f2c4ac402a45cf6499b1 Mon Sep 17 00:00:00 2001 From: Liudmila Nemkova Date: Tue, 22 Oct 2024 13:06:06 +0300 Subject: [PATCH 1/3] Draft version. Not final --- .../version-3.0/server-side-api-objects.md | 90 +++++++++---------- .../version-3.0/server-side-api-specs.md | 2 +- 2 files changed, 46 insertions(+), 46 deletions(-) diff --git a/versioned_docs/version-3.0/server-side-api-objects.md b/versioned_docs/version-3.0/server-side-api-objects.md index 1753e608..1e0e0b14 100644 --- a/versioned_docs/version-3.0/server-side-api-objects.md +++ b/versioned_docs/version-3.0/server-side-api-objects.md @@ -39,61 +39,61 @@ if (profile.paidAccessLevels["premium"]?.isActive == true) { } ``` -| Param | Type | Required | Nullable | Description | -| :------------------------------------ | :------------ | :------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| **id** | str | ✅ | ❌ | Paid Access Level identifier configured by a developer in the Adapty Dashboard | -| **is\_active** | bool | ✅ | ❌ | Boolean indicating whether the paid access level is active | -| **expires\_at** | ISO 8601 date | ✅ | ✅ | The datetime when the access level will expire. It may be in the past and may be null for lifetime access | -| **starts\_at** | ISO 8601 date | ✅ | ✅ | The datetime when the access level will be active. May be in the future | -| **is\_lifetime** | bool | ✅ | ❌ | Boolean indicating whether the paid access level is active for a lifetime \(no expiration date\). If set to true you shouldn’t use expires\_at | -| **vendor\_product\_id** | str | ✅ | ✅ | Identifier of the product in the vendor system \(App Store/Google Play/Stripe, etc.\) that unlocked this access level | -| **base_plan_id** | str | ✅ | ✅ | [Base plan ID](https://support.google.com/googleplay/android-developer/answer/12154973) in the Google Play Store or [price ID](https://docs.stripe.com/products-prices/how-products-and-prices-work#what-is-a-price) in Stripe. | -| **store** | str | ✅ | ✅ | Store where the product was purchased. Possible values are: **app\_store**, **play\_store**, and **adapty** | -| **activated\_at** | ISO 8601 date | ✅ | ❌ | The datetime when the access level was activated. May be in the future | -| **renewed\_at** | ISO 8601 date | ✅ | ✅ | The datetime when the access level was renewed | -| **will\_renew** | bool | ✅ | ❌ | Boolean indicating whether an auto-renewable subscription is set to renew | -| **is\_in\_grace\_period** | bool | ✅ | ❌ | Boolean indicating whether auto-renewable subscription is in the [grace period](https://developer.apple.com/news/?id=09122019c) | -| **unsubscribed\_at** | ISO 8601 date | ✅ | ✅ | The datetime when an auto-renewable subscription was cancelled. Subscription can still be active, it means that auto-renewal is turned off. It will be set to null if the user reactivates the subscription | -| **billing\_issue\_detected\_at** | ISO 8601 date | ✅ | ✅ | The datetime when a billing issue was detected and a vendor was not able to charge the card. Subscription can still be active. Will set to null if the charge is successful | +| Param | Type | Required | Nullable | Description | +| :------------------------------------ | :------------ | :------- | :------- | :----------------------------------------------------------- | +| **id** | str | ✅ | ❌ | Paid Access Level identifier configured by a developer in the Adapty Dashboard | +| **is\_active** | bool | ✅ | ❌ | Boolean indicating whether the paid access level is active | +| **expires\_at** | ISO 8601 date | ✅ | ✅ | The datetime when the access level will expire. It may be in the past and may be null for lifetime access | +| **starts\_at** | ISO 8601 date | ✅ | ✅ | The datetime when the access level will be active. May be in the future | +| **is\_lifetime** | bool | ✅ | ❌ | Boolean indicating whether the paid access level is active for a lifetime \(no expiration date\). If set to true you shouldn’t use expires\_at | +| **vendor\_product\_id** | str | ✅ | ✅ |

This is the product ID from the vendor's system (App Store, Google Play, Stripe, etc.) that unlocked the access level. If an access level was granted without a transaction, one of the following values will be returned:

| +| **base_plan_id** | str | ✅ | ✅ | [Base plan ID](https://support.google.com/googleplay/android-developer/answer/12154973) in the Google Play Store or [price ID](https://docs.stripe.com/products-prices/how-products-and-prices-work#what-is-a-price) in Stripe. | +| **store** | str | ✅ | ✅ | Store where the product was purchased. Possible values are: **app\_store**, **play\_store**, and **adapty** | +| **activated\_at** | ISO 8601 date | ✅ | ❌ | The datetime when the access level was activated. May be in the future | +| **renewed\_at** | ISO 8601 date | ✅ | ✅ | The datetime when the access level was renewed | +| **will\_renew** | bool | ✅ | ❌ | Boolean indicating whether an auto-renewable subscription is set to renew | +| **is\_in\_grace\_period** | bool | ✅ | ❌ | Boolean indicating whether auto-renewable subscription is in the [grace period](https://developer.apple.com/news/?id=09122019c) | +| **unsubscribed\_at** | ISO 8601 date | ✅ | ✅ | The datetime when an auto-renewable subscription was cancelled. Subscription can still be active, it means that auto-renewal is turned off. It will be set to null if the user reactivates the subscription | +| **billing\_issue\_detected\_at** | ISO 8601 date | ✅ | ✅ | The datetime when a billing issue was detected and a vendor was not able to charge the card. Subscription can still be active. Will set to null if the charge is successful | | **active\_introductory\_offer\_type** | str | ✅ | ✅ | The type of active [introductory offer](https://developer.apple.com/app-store/subscriptions/#offering-introductory-prices). Possible values are: **free\_trial**, **pay\_as\_you\_go**, and **pay\_up\_front**. If the value is not null it means that the offer was applied during the current subscription period | -| **active\_promotional\_offer\_type** | str | ✅ | ✅ | The type of active [promotional offer](https://developer.apple.com/app-store/subscriptions/#subscription-offers). Possible values are: **free\_trial**, **pay\_as\_you\_go**, and **pay\_up\_front**. If the value is not null it means that the offer was applied during the current subscription period | +| **active\_promotional\_offer\_type** | str | ✅ | ✅ | The type of active [promotional offer](https://developer.apple.com/app-store/subscriptions/#subscription-offers). Possible values are: **free\_trial**, **pay\_as\_you\_go**, and **pay\_up\_front**. If the value is not null it means that the offer was applied during the current subscription period | ### Subscription Info about vendor subscription. You don’t have to use this object in most cases, **CustomerPaidAccessLevel** is the preferred way to work with access to the app. When using this object, you need to implement processing logic for each subscription period \(a week, a month, a year, lifetime\). -| Param | Type | Required | Nullable | Description | -| :------------------------------------ | :------------ | :------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| **is\_active** | bool | ✅ | ❌ | Boolean indicating whether the subscription is active | -| **expires\_at** | ISO 8601 date | ✅ | ✅ | The datetime when access level will expire. May be in the past and may be null for lifetime access | -| **starts\_at** | ISO 8601 date | ✅ | ✅ | The datetime when the subscription will be active. May be in the future for season subscriptions | -| **is\_lifetime** | bool | ✅ | ❌ | Boolean that indicates whether the subscription is active for a lifetime without an expiration date. If set to true you shouldn’t use expires\_at | -| **vendor\_product\_id** | str | ✅ | ✅ | Identifier of the product in vendor system \(App Store/Google Play etc.\) | -| **base_plan_id** | str | ✅ | ✅ | [Base plan ID](https://support.google.com/googleplay/android-developer/answer/12154973) in the Google Play Store or [price ID](https://docs.stripe.com/products-prices/how-products-and-prices-work#what-is-a-price) in Stripe. | -| **vendor\_transaction\_id** | str | ✅ | ✅ | Transaction id in the vendor system | -| **vendor\_original\_transaction\_id** | str | ✅ | ✅ | Original transaction id in vendor system. For auto-renewable subscription, this will be the ID of the first transaction in the subscription | -| **store** | str | ✅ | ✅ | Store where the product was purchased. Possible values are: **app\_store**, **play\_store**, and **adapty** | -| **activated\_at** | ISO 8601 date | ✅ | ❌ | The datetime when the access level was activated. May be in the future | -| **renewed\_at** | ISO 8601 date | ✅ | ✅ | The datetime when the access level was renewed | -| **will\_renew** | bool | ✅ | ❌ | Boolean indicating whether an auto-renewable subscription is set to renew. If a user did not cancel a subscription, will be set to true | -| **is\_in\_grace\_period** | bool | ✅ | ❌ | Boolean indicating whether an auto-renewable subscription is in the [grace period](https://developer.apple.com/news/?id=09122019c) | -| **unsubscribed\_at** | ISO 8601 date | ✅ | ✅ | The datetime when an auto-renewable subscription was canceled. Subscription can still be active, it just means that auto-renewal is turned off. Will be set to null if the user reactivates the subscription | -| **billing\_issue\_detected\_at** | ISO 8601 date | ✅ | ✅ | The datetime when the billing issue was detected \(vendor was not able to charge the card\). Subscription can still be active. Will be set to null if the charge is successful. | +| Param | Type | Required | Nullable | Description | +| :------------------------------------ | :------------ | :------- | :------- | :----------------------------------------------------------- | +| **is\_active** | bool | ✅ | ❌ | Boolean indicating whether the subscription is active | +| **expires\_at** | ISO 8601 date | ✅ | ✅ | The datetime when access level will expire. May be in the past and may be null for lifetime access | +| **starts\_at** | ISO 8601 date | ✅ | ✅ | The datetime when the subscription will be active. May be in the future for season subscriptions | +| **is\_lifetime** | bool | ✅ | ❌ | Boolean that indicates whether the subscription is active for a lifetime without an expiration date. If set to true you shouldn’t use expires\_at | +| **vendor\_product\_id** | str | ✅ | ✅ |

This is the product ID from the vendor's system (App Store, Google Play, Stripe, etc.) that unlocked the access level. If an access level was granted without a transaction, one of the following values will be returned:

| +| **base_plan_id** | str | ✅ | ✅ | [Base plan ID](https://support.google.com/googleplay/android-developer/answer/12154973) in the Google Play Store or [price ID](https://docs.stripe.com/products-prices/how-products-and-prices-work#what-is-a-price) in Stripe. | +| **vendor\_transaction\_id** | str | ✅ | ✅ | Transaction id in the vendor system | +| **vendor\_original\_transaction\_id** | str | ✅ | ✅ | Original transaction id in vendor system. For auto-renewable subscription, this will be the ID of the first transaction in the subscription | +| **store** | str | ✅ | ✅ | Store where the product was purchased. Possible values are: **app\_store**, **play\_store**, and **adapty** | +| **activated\_at** | ISO 8601 date | ✅ | ❌ | The datetime when the access level was activated. May be in the future | +| **renewed\_at** | ISO 8601 date | ✅ | ✅ | The datetime when the access level was renewed | +| **will\_renew** | bool | ✅ | ❌ | Boolean indicating whether an auto-renewable subscription is set to renew. If a user did not cancel a subscription, will be set to true | +| **is\_in\_grace\_period** | bool | ✅ | ❌ | Boolean indicating whether an auto-renewable subscription is in the [grace period](https://developer.apple.com/news/?id=09122019c) | +| **unsubscribed\_at** | ISO 8601 date | ✅ | ✅ | The datetime when an auto-renewable subscription was canceled. Subscription can still be active, it just means that auto-renewal is turned off. Will be set to null if the user reactivates the subscription | +| **billing\_issue\_detected\_at** | ISO 8601 date | ✅ | ✅ | The datetime when the billing issue was detected \(vendor was not able to charge the card\). Subscription can still be active. Will be set to null if the charge is successful. | | **active\_introductory\_offer\_type** | str | ✅ | ✅ | The type of active [introductory offer](https://developer.apple.com/app-store/subscriptions/#offering-introductory-prices). Possible values are: **free\_trial**, **pay\_as\_you\_go**, and **pay\_up\_front**. If the value is not null it means that the offer was applied during the current subscription period | -| **active\_promotional\_offer\_type** | str | ✅ | ✅ | The type of active [promotional offer](https://developer.apple.com/app-store/subscriptions/#subscription-offers). Possible values are: **free\_trial**, **pay\_as\_you\_go**, and **pay\_up\_front**. If the value is not null it means that the offer was applied during the current subscription period | -| **is\_sandbox** | bool | ✅ | ❌ | Boolean indicating whether the product was purchased in the sandbox or production environment | +| **active\_promotional\_offer\_type** | str | ✅ | ✅ | The type of active [promotional offer](https://developer.apple.com/app-store/subscriptions/#subscription-offers). Possible values are: **free\_trial**, **pay\_as\_you\_go**, and **pay\_up\_front**. If the value is not null it means that the offer was applied during the current subscription period | +| **is\_sandbox** | bool | ✅ | ❌ | Boolean indicating whether the product was purchased in the sandbox or production environment | ### Non Subscription Info about non-subscription purchases. These can be one-time \(consumable\) products, unlocks \(like new map unlock in the game\), etc. -| Param | Type | Required | Nullable | Description | -| :------------------------------------ | :------------ | :------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **purchase\_id** | str | ✅ | ❌ | 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 | -| **vendor\_product\_id** | str | ✅ | ✅ | Identifier of the product in vendor system \(App Store/Google Play etc.\) | -| **vendor\_transaction\_id** | str | ✅ | ✅ | Transaction ID in the vendor system | -| **vendor\_original\_transaction\_id** | str | ✅ | ✅ | Original transaction ID in vendor system. For auto-renewable subscription, this will be the ID of the first transaction in the subscription | -| **store** | str | ✅ | ✅ | Store where the product was purchased. Possible values are **app\_store**, **play\_store**, **adapty** | -| **purchased\_at** | ISO 8601 date | ✅ | ❌ | The datetime when the product was purchased | +| Param | Type | Required | Nullable | Description | +| :------------------------------------ | :------------ | :------- | :------- | :----------------------------------------------------------- | +| **purchase\_id** | str | ✅ | ❌ | 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 | +| **vendor\_product\_id** | str | ✅ | ✅ |

This is the product ID from the vendor's system (App Store, Google Play, Stripe, etc.) that unlocked the access level. If an access level was granted without a transaction, one of the following values will be returned:

| +| **vendor\_transaction\_id** | str | ✅ | ✅ | Transaction ID in the vendor system | +| **vendor\_original\_transaction\_id** | str | ✅ | ✅ | Original transaction ID in vendor system. For auto-renewable subscription, this will be the ID of the first transaction in the subscription | +| **store** | str | ✅ | ✅ | Store where the product was purchased. Possible values are **app\_store**, **play\_store**, **adapty** | +| **purchased\_at** | ISO 8601 date | ✅ | ❌ | The datetime when the product was purchased | | **is\_one\_time** | bool | ✅ | ❌ | Boolean indicating whether the product should only be processed once. For example, if a user purchased 500 coins in a game. If true, the purchase will be returned by Adapty API one time only | -| **is\_sandbox** | bool | ✅ | ❌ | Boolean indicating whether the product was purchased in a sandbox or production environment. | \ No newline at end of file +| **is\_sandbox** | bool | ✅ | ❌ | Boolean indicating whether the product was purchased in a sandbox or production environment. | \ No newline at end of file diff --git a/versioned_docs/version-3.0/server-side-api-specs.md b/versioned_docs/version-3.0/server-side-api-specs.md index f0a6e609..9afb10db 100644 --- a/versioned_docs/version-3.0/server-side-api-specs.md +++ b/versioned_docs/version-3.0/server-side-api-specs.md @@ -62,7 +62,7 @@ Request parameters: | **duration_days** | int | ✅\* see below | ❌ | Additional days to a current subscription\*\* | | **is_lifetime** | bool | ✅\* see below | ❌ | If set true, then a user will forever have a paid access level forever | | **starts_at** | ISO 8601 date | ❌ | ❌ | If the start time of the action is in the future, then you can transfer it. If the start time and the period are indicated, the period will be counted from the indicated time | -| **vendor_product_id** | str | ❌ | ❌ | Vendor product ID which initiates subscription renewal. The default value is **adapty_server_side_product** | +| **vendor_product_id** | str | ❌ | ❌ | When posting a transaction, include the product ID that triggers the subscription renewal. If you're granting an access level without a transaction, skip this parameter, and **adapty_server_side_product** will be used by default. | | **base_plan_id** | str | ❌ | ❌ | [Base plan ID](https://support.google.com/googleplay/android-developer/answer/12154973) in the Google Play Store or [price ID](https://docs.stripe.com/products-prices/how-products-and-prices-work#what-is-a-price) in Stripe. | | **vendor_original_transaction_id** | str | ❌ | ❌ | ID of the original transaction in the subscription renewal chain in a vendor environment. | | **vendor_transaction_id** | str | ❌ | ❌ |

Transaction ID in a vendor environment.

If it is the same as **vendor_original_transaction_id** or if **vendor_original_transaction_id** is absent, Adapty considers it the first subscription purchase. If it differs from **vendor_original_transaction_id**, Adapty considers the purchase the subscription renewal.

| From 6d786ed037b802355a21d26932872e7cb1c1321c Mon Sep 17 00:00:00 2001 From: Liudmila Nemkova Date: Wed, 23 Oct 2024 15:37:31 +0300 Subject: [PATCH 2/3] Fixed vendor_product_id --- versioned_docs/version-3.0/server-side-api-objects.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versioned_docs/version-3.0/server-side-api-objects.md b/versioned_docs/version-3.0/server-side-api-objects.md index 1e0e0b14..4f911152 100644 --- a/versioned_docs/version-3.0/server-side-api-objects.md +++ b/versioned_docs/version-3.0/server-side-api-objects.md @@ -46,7 +46,7 @@ if (profile.paidAccessLevels["premium"]?.isActive == true) { | **expires\_at** | ISO 8601 date | ✅ | ✅ | The datetime when the access level will expire. It may be in the past and may be null for lifetime access | | **starts\_at** | ISO 8601 date | ✅ | ✅ | The datetime when the access level will be active. May be in the future | | **is\_lifetime** | bool | ✅ | ❌ | Boolean indicating whether the paid access level is active for a lifetime \(no expiration date\). If set to true you shouldn’t use expires\_at | -| **vendor\_product\_id** | str | ✅ | ✅ |

This is the product ID from the vendor's system (App Store, Google Play, Stripe, etc.) that unlocked the access level. If an access level was granted without a transaction, one of the following values will be returned:

| +| **vendor\_product\_id** | str | ✅ | ✅ |

This is the product ID from the vendor's system (App Store, Google Play, Stripe, etc.) that unlocked the access level.

If an access level was granted without a transaction, one of the following values will be returned:

| | **base_plan_id** | str | ✅ | ✅ | [Base plan ID](https://support.google.com/googleplay/android-developer/answer/12154973) in the Google Play Store or [price ID](https://docs.stripe.com/products-prices/how-products-and-prices-work#what-is-a-price) in Stripe. | | **store** | str | ✅ | ✅ | Store where the product was purchased. Possible values are: **app\_store**, **play\_store**, and **adapty** | | **activated\_at** | ISO 8601 date | ✅ | ❌ | The datetime when the access level was activated. May be in the future | From d49b9951bbf676ba122499d179cf8e2971b2e08e Mon Sep 17 00:00:00 2001 From: Liudmila Nemkova Date: Wed, 23 Oct 2024 15:49:12 +0300 Subject: [PATCH 3/3] Version for review --- versioned_docs/version-3.0/server-side-api-objects.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versioned_docs/version-3.0/server-side-api-objects.md b/versioned_docs/version-3.0/server-side-api-objects.md index 4f911152..a40e472d 100644 --- a/versioned_docs/version-3.0/server-side-api-objects.md +++ b/versioned_docs/version-3.0/server-side-api-objects.md @@ -68,7 +68,7 @@ Info about vendor subscription. You don’t have to use this object in most case | **expires\_at** | ISO 8601 date | ✅ | ✅ | The datetime when access level will expire. May be in the past and may be null for lifetime access | | **starts\_at** | ISO 8601 date | ✅ | ✅ | The datetime when the subscription will be active. May be in the future for season subscriptions | | **is\_lifetime** | bool | ✅ | ❌ | Boolean that indicates whether the subscription is active for a lifetime without an expiration date. If set to true you shouldn’t use expires\_at | -| **vendor\_product\_id** | str | ✅ | ✅ |

This is the product ID from the vendor's system (App Store, Google Play, Stripe, etc.) that unlocked the access level. If an access level was granted without a transaction, one of the following values will be returned:

  • **adapty_server_side_product**: Access was granted through the server-side API
  • **adapty_dashboard_product**: Access was granted for a product the user purchased
  • **adapty_promotion**: legacy option
| +| **vendor\_product\_id** | str | ✅ | ✅ |

This is the product ID from the vendor's system (App Store, Google Play, Stripe, etc.) that unlocked the access level.

If an access level was granted without a transaction, one of the following values will be returned:

  • **adapty_server_side_product**: Access was [granted through the server-side API](server-side-api-specs#prolonggrant-a-subscription-for-a-user).
  • **adapty_dashboard_product**: Access was [granted in the Adapty Dashboard](give-access-level-to-specific-customer#give-access-level-to-a-specific-customer-in-the-adapty-dashboard).
  • **adapty_promotion**: legacy option
| | **base_plan_id** | str | ✅ | ✅ | [Base plan ID](https://support.google.com/googleplay/android-developer/answer/12154973) in the Google Play Store or [price ID](https://docs.stripe.com/products-prices/how-products-and-prices-work#what-is-a-price) in Stripe. | | **vendor\_transaction\_id** | str | ✅ | ✅ | Transaction id in the vendor system | | **vendor\_original\_transaction\_id** | str | ✅ | ✅ | Original transaction id in vendor system. For auto-renewable subscription, this will be the ID of the first transaction in the subscription | @@ -90,7 +90,7 @@ Info about non-subscription purchases. These can be one-time \(consumable\) prod | Param | Type | Required | Nullable | Description | | :------------------------------------ | :------------ | :------- | :------- | :----------------------------------------------------------- | | **purchase\_id** | str | ✅ | ❌ | 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 | -| **vendor\_product\_id** | str | ✅ | ✅ |

This is the product ID from the vendor's system (App Store, Google Play, Stripe, etc.) that unlocked the access level. If an access level was granted without a transaction, one of the following values will be returned:

  • **adapty_server_side_product**: Access was granted through the server-side API
  • **adapty_dashboard_product**: Access was granted for a product the user purchased
  • **adapty_promotion**: legacy option
| +| **vendor\_product\_id** | str | ✅ | ✅ |

This is the product ID from the vendor's system (App Store, Google Play, Stripe, etc.) that unlocked the access level.

If an access level was granted without a transaction, one of the following values will be returned:

  • **adapty_server_side_product**: Access was [granted through the server-side API](server-side-api-specs#prolonggrant-a-subscription-for-a-user).
  • **adapty_dashboard_product**: Access was [granted in the Adapty Dashboard](give-access-level-to-specific-customer#give-access-level-to-a-specific-customer-in-the-adapty-dashboard).
  • **adapty_promotion**: legacy option
| | **vendor\_transaction\_id** | str | ✅ | ✅ | Transaction ID in the vendor system | | **vendor\_original\_transaction\_id** | str | ✅ | ✅ | Original transaction ID in vendor system. For auto-renewable subscription, this will be the ID of the first transaction in the subscription | | **store** | str | ✅ | ✅ | Store where the product was purchased. Possible values are **app\_store**, **play\_store**, **adapty** |