REST Resource: purchases.subscriptionsv2

Resource: SubscriptionPurchaseV2

Indicates the status of a user's subscription purchase.

JSON representation 
{
  "kind": string,
  "regionCode": string,
  "lineItems": [
    {
      object (SubscriptionPurchaseLineItem)
    }
  ],
  "startTime": string,
  "subscriptionState": enum (SubscriptionState),
  "latestOrderId": string,
  "linkedPurchaseToken": string,
  "pausedStateContext": {
    object (PausedStateContext)
  },
  "canceledStateContext": {
    object (CanceledStateContext)
  },
  "testPurchase": {
    object (TestPurchase)
  },
  "acknowledgementState": enum (AcknowledgementState),
  "externalAccountIdentifiers": {
    object (ExternalAccountIdentifiers)
  },
  "subscribeWithGoogleInfo": {
    object (SubscribeWithGoogleInfo)
  }
}
Fields
kind

string

This kind represents a SubscriptionPurchaseV2 object in the androidpublisher service.
regionCode

string

ISO 3166-1 alpha-2 billing country/region code of the user at the time the subscription was granted.
lineItems[]

object (SubscriptionPurchaseLineItem)

Item-level info for a subscription purchase. The items in the same purchase should be either all with AutoRenewingPlan or all with PrepaidPlan.
startTime

string (Timestamp format)

Time at which the subscription was granted. Not set for pending subscriptions (subscription was created but awaiting payment during signup).

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
subscriptionState

enum (SubscriptionState)

The current state of the subscription.
latestOrderId

string

The order id of the latest order associated with the purchase of the subscription. For autoRenewing subscription, this is the order id of signup order if it is not renewed yet, or the last recurring order id (success, pending, or declined order). For prepaid subscription, this is the order id associated with the queried purchase token.
linkedPurchaseToken

string

The purchase token of the old subscription if this subscription is one of the following: * Re-signup of a canceled but non-lapsed subscription * Upgrade/downgrade from a previous subscription. * Convert from prepaid to auto renewing subscription. * Convert from an auto renewing subscription to prepaid. * Topup a prepaid subscription.
pausedStateContext

object (PausedStateContext)

Additional context around paused subscriptions. Only present if the subscription currently has subscriptionState SUBSCRIPTION_STATE_PAUSED.
canceledStateContext

object (CanceledStateContext)

Additional context around canceled subscriptions. Only present if the subscription currently has subscriptionState SUBSCRIPTION_STATE_CANCELED or SUBSCRIPTION_STATE_EXPIRED.
testPurchase

object (TestPurchase)

Only present if this subscription purchase is a test purchase.
acknowledgementState

enum (AcknowledgementState)

The acknowledgement state of the subscription.
externalAccountIdentifiers

object (ExternalAccountIdentifiers)

User account identifier in the third-party service.
subscribeWithGoogleInfo

object (SubscribeWithGoogleInfo)

User profile associated with purchases made with 'Subscribe with Google'.

SubscriptionState

The potential states a subscription can be in, for example whether it is active or canceled. The items within a subscription purchase can either be all auto renewing plans or prepaid plans.

Enums
SUBSCRIPTION_STATE_UNSPECIFIED Unspecified subscription state.
SUBSCRIPTION_STATE_PENDING Subscription was created but awaiting payment during signup. In this state, all items are awaiting payment.
SUBSCRIPTION_STATE_ACTIVE Subscription is active. - (1) If the subscription is an auto renewing plan, at least one item is autoRenewEnabled and not expired. - (2) If the subscription is a prepaid plan, at least one item is not expired.
SUBSCRIPTION_STATE_PAUSED Subscription is paused. The state is only available when the subscription is an auto renewing plan. In this state, all items are in paused state.
SUBSCRIPTION_STATE_IN_GRACE_PERIOD Subscription is in grace period. The state is only available when the subscription is an auto renewing plan. In this state, all items are in grace period.
SUBSCRIPTION_STATE_ON_HOLD Subscription is on hold (suspended). The state is only available when the subscription is an auto renewing plan. In this state, all items are on hold.
SUBSCRIPTION_STATE_CANCELED Subscription is canceled but not expired yet. The state is only available when the subscription is an auto renewing plan. All items have autoRenewEnabled set to false.
SUBSCRIPTION_STATE_EXPIRED Subscription is expired. All items have expiryTime in the past.
SUBSCRIPTION_STATE_PENDING_PURCHASE_CANCELED Pending transaction for subscription is canceled. If this pending purchase was for an existing subscription, use linkedPurchaseToken to get the current state of that subscription.

PausedStateContext

Information specific to a subscription in paused state.

JSON representation 
{
  "autoResumeTime": string
}
Fields
autoResumeTime

string (Timestamp format)

Time at which the subscription will be automatically resumed.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

CanceledStateContext

Information specific to a subscription in the SUBSCRIPTION_STATE_CANCELED or SUBSCRIPTION_STATE_EXPIRED state.

JSON representation 
{

  // Union field cancellation_reason can be only one of the following:
  "userInitiatedCancellation": {
    object (UserInitiatedCancellation)
  },
  "systemInitiatedCancellation": {
    object (SystemInitiatedCancellation)
  },
  "developerInitiatedCancellation": {
    object (DeveloperInitiatedCancellation)
  },
  "replacementCancellation": {
    object (ReplacementCancellation)
  }
  // End of list of possible types for union field cancellation_reason.
}
Fields
Union field cancellation_reason. The reason why a subscription was canceled. cancellation_reason can be only one of the following:
userInitiatedCancellation

object (UserInitiatedCancellation)

Subscription was canceled by user.
systemInitiatedCancellation

object (SystemInitiatedCancellation)

Subscription was canceled by the system, for example because of a billing problem.
developerInitiatedCancellation

object (DeveloperInitiatedCancellation)

Subscription was canceled by the developer.
replacementCancellation

object (ReplacementCancellation)

Subscription was replaced by a new subscription.

UserInitiatedCancellation

Information specific to cancellations initiated by users.

JSON representation 
{
  "cancelSurveyResult": {
    object (CancelSurveyResult)
  },
  "cancelTime": string
}
Fields
cancelSurveyResult

object (CancelSurveyResult)

Information provided by the user when they complete the subscription cancellation flow (cancellation reason survey).
cancelTime

string (Timestamp format)

The time at which the subscription was canceled by the user. The user might still have access to the subscription after this time. Use lineItems.expiry_time to determine if a user still has access.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

CancelSurveyResult

Result of the cancel survey when the subscription was canceled by the user.

JSON representation 
{
  "reason": enum (CancelSurveyReason),
  "reasonUserInput": string
}
Fields
reason

enum (CancelSurveyReason)

The reason the user selected in the cancel survey.
reasonUserInput

string

Only set for CANCEL_SURVEY_REASON_OTHERS. This is the user's freeform response to the survey.

CancelSurveyReason

The reason the user selected in the cancel survey.

Enums
CANCEL_SURVEY_REASON_UNSPECIFIED Unspecified cancel survey reason.
CANCEL_SURVEY_REASON_NOT_ENOUGH_USAGE Not enough usage of the subscription.
CANCEL_SURVEY_REASON_TECHNICAL_ISSUES Technical issues while using the app.
CANCEL_SURVEY_REASON_FOUND_BETTER_APP The user found a better app.
CANCEL_SURVEY_REASON_OTHERS Other reasons.

SystemInitiatedCancellation

This type has no fields.

Information specific to cancellations initiated by Google system.

DeveloperInitiatedCancellation

This type has no fields.

Information specific to cancellations initiated by developers.

ReplacementCancellation

This type has no fields.

Information specific to cancellations caused by subscription replacement.

TestPurchase

This type has no fields.

Whether this subscription purchase is a test purchase.

AcknowledgementState

The possible acknowledgement states for a subscription.

Enums
ACKNOWLEDGEMENT_STATE_UNSPECIFIED Unspecified acknowledgement state.
ACKNOWLEDGEMENT_STATE_PENDING The subscription is not acknowledged yet.
ACKNOWLEDGEMENT_STATE_ACKNOWLEDGED The subscription is acknowledged.

ExternalAccountIdentifiers

User account identifier in the third-party service.

JSON representation 
{
  "externalAccountId": string,
  "obfuscatedExternalAccountId": string,
  "obfuscatedExternalProfileId": string
}
Fields
externalAccountId

string

User account identifier in the third-party service. Only present if account linking happened as part of the subscription purchase flow.
obfuscatedExternalAccountId

string

An obfuscated version of the id that is uniquely associated with the user's account in your app. Present for the following purchases: * If account linking happened as part of the subscription purchase flow. * It was specified using https://developer.android.com/reference/com/android/billingclient/api/BillingFlowParams.Builder#setobfuscatedaccountid when the purchase was made.
obfuscatedExternalProfileId

string

An obfuscated version of the id that is uniquely associated with the user's profile in your app. Only present if specified using https://developer.android.com/reference/com/android/billingclient/api/BillingFlowParams.Builder#setobfuscatedprofileid when the purchase was made.

SubscribeWithGoogleInfo

Information associated with purchases made with 'Subscribe with Google'.

JSON representation 
{
  "profileId": string,
  "profileName": string,
  "emailAddress": string,
  "givenName": string,
  "familyName": string
}
Fields
profileId

string

The Google profile id of the user when the subscription was purchased.
profileName

string

The profile name of the user when the subscription was purchased.
emailAddress

string

The email address of the user when the subscription was purchased.
givenName

string

The given name of the user when the subscription was purchased.
familyName

string

The family name of the user when the subscription was purchased.

SubscriptionPurchaseLineItem

Item-level info for a subscription purchase.

JSON representation 
{
  "productId": string,
  "expiryTime": string,

  // Union field plan_type can be only one of the following:
  "autoRenewingPlan": {
    object (AutoRenewingPlan)
  },
  "prepaidPlan": {
    object (PrepaidPlan)
  }
  // End of list of possible types for union field plan_type.
  "offerDetails": {
    object (OfferDetails)
  },

  // Union field deferred_item_change can be only one of the following:
  "deferredItemReplacement": {
    object (DeferredItemReplacement)
  }
  // End of list of possible types for union field deferred_item_change.
  "signupPromotion": {
    object (SignupPromotion)
  }
}
Fields
productId

string

The purchased product ID (for example, 'monthly001').
expiryTime

string (Timestamp format)

Time at which the subscription expired or will expire unless the access is extended (ex. renews).

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
Union field plan_type. The subscription plan type. plan_type can be only one of the following:
autoRenewingPlan

object (AutoRenewingPlan)

The item is auto renewing.
prepaidPlan

object (PrepaidPlan)

The item is prepaid.
offerDetails

object (OfferDetails)

The offer details for this item.
Union field deferred_item_change. The field is present when a item has a deferred change. It can either be removed or replaced. deferred_item_change can be only one of the following:
deferredItemReplacement

object (DeferredItemReplacement)

Information for deferred item replacement.
signupPromotion

object (SignupPromotion)

Promotion details about this item. Only set if a promotion was applied during signup.

AutoRenewingPlan

Information related to an auto renewing plan.

JSON representation 
{
  "autoRenewEnabled": boolean,
  "recurringPrice": {
    object (Money)
  },
  "priceChangeDetails": {
    object (SubscriptionItemPriceChangeDetails)
  },
  "installmentDetails": {
    object (InstallmentPlan)
  }
}
Fields
autoRenewEnabled

boolean

If the subscription is currently set to auto-renew, e.g. the user has not canceled the subscription
recurringPrice

object (Money)

The current recurring price of the auto renewing plan.
priceChangeDetails

object (SubscriptionItemPriceChangeDetails)

The information of the last price change for the item since subscription signup.
installmentDetails

object (InstallmentPlan)

The installment plan commitment and state related info for the auto renewing plan.

SubscriptionItemPriceChangeDetails

Price change related information of a subscription item.

JSON representation 
{
  "newPrice": {
    object (Money)
  },
  "priceChangeMode": enum (PriceChangeMode),
  "priceChangeState": enum (PriceChangeState),
  "expectedNewPriceChargeTime": string
}
Fields
newPrice

object (Money)

New recurring price for the subscription item.
priceChangeMode

enum (PriceChangeMode)

Price change mode specifies how the subscription item price is changing.
priceChangeState

enum (PriceChangeState)

State the price change is currently in.
expectedNewPriceChargeTime

string (Timestamp format)

The renewal time at which the price change will become effective for the user. This is subject to change(to a future time) due to cases where the renewal time shifts like pause. This field is only populated if the price change has not taken effect.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

PriceChangeMode

The mode of the price change.

Enums
PRICE_CHANGE_MODE_UNSPECIFIED Price change mode unspecified. This value should never be set.
PRICE_DECREASE If the subscription price is decreasing.
PRICE_INCREASE If the subscription price is increasing and the user needs to accept it.
OPT_OUT_PRICE_INCREASE If the subscription price is increasing with opt out mode.

PriceChangeState

The state of the price change.

Enums
PRICE_CHANGE_STATE_UNSPECIFIED Price change state unspecified. This value should not be used.
OUTSTANDING Waiting for the user to agree for the price change.
CONFIRMED The price change is confirmed to happen for the user.
APPLIED The price change is applied, i.e. the user has started being charged the new price.

InstallmentPlan

Information to a installment plan.

JSON representation 
{
  "initialCommittedPaymentsCount": integer,
  "subsequentCommittedPaymentsCount": integer,
  "remainingCommittedPaymentsCount": integer,
  "pendingCancellation": {
    object (PendingCancellation)
  }
}
Fields
initialCommittedPaymentsCount

integer

Total number of payments the user is initially committed for.
subsequentCommittedPaymentsCount

integer

Total number of payments the user will be committed for after each commitment period. Empty means the installment plan will fall back to a normal auto-renew subscription after initial commitment.
remainingCommittedPaymentsCount

integer

Total number of committed payments remaining to be paid for in this renewal cycle.
pendingCancellation

object (PendingCancellation)

If present, this installment plan is pending to be canceled. The cancellation will happen only after the user finished all committed payments.

PendingCancellation

This type has no fields.

This is an indicator of whether there is a pending cancellation on the virtual installment plan. The cancellation will happen only after the user finished all committed payments.

PrepaidPlan

Information related to a prepaid plan.

JSON representation 
{
  "allowExtendAfterTime": string
}
Fields
allowExtendAfterTime

string (Timestamp format)

If present, this is the time after which top up purchases are allowed for the prepaid plan. Will not be present for expired prepaid plans.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

OfferDetails

Offer details information related to a purchase line item.

JSON representation 
{
  "offerTags": [
    string
  ],
  "basePlanId": string,
  "offerId": string
}
Fields
offerTags[]

string

The latest offer tags associated with the offer. It includes tags inherited from the base plan.
basePlanId

string

The base plan ID. Present for all base plan and offers.
offerId

string

The offer ID. Only present for discounted offers.

DeferredItemReplacement

Information related to deferred item replacement.

JSON representation 
{
  "productId": string
}
Fields
productId

string

The productId going to replace the existing productId.

SignupPromotion

The promotion applied on this item when purchased.

JSON representation 
{

  // Union field promotion_type can be only one of the following:
  "oneTimeCode": {
    object (OneTimeCode)
  },
  "vanityCode": {
    object (VanityCode)
  }
  // End of list of possible types for union field promotion_type.
}
Fields
Union field promotion_type. The type of promotion applied to the item. promotion_type can be only one of the following:
oneTimeCode

object (OneTimeCode)

A one-time code was applied.
vanityCode

object (VanityCode)

A vanity code was applied.

OneTimeCode

This type has no fields.

A single use promotion code.

VanityCode

A multiple use, predefined promotion code.

JSON representation 
{
  "promotionCode": string
}
Fields
promotionCode

string

The promotion code.

Methods

get

 Get metadata about a subscription

revoke

 Revoke a subscription purchase for the user.