REST Resource: purchases.subscriptions

  • The SubscriptionPurchase resource provides the status of a user's subscription purchase, including details like start and expiry times, auto-renewal status, pricing, and cancellation information.

  • The resource includes information on introductory pricing, cancellation survey results, and upcoming price changes for subscriptions.

  • Several methods are available to manage subscriptions, such as acknowledging, canceling, and deferring purchases, though some methods are deprecated.

  • The documentation also outlines potential HTTP error codes and their resolutions when interacting with this resource.

Resource: SubscriptionPurchase

A SubscriptionPurchase resource indicates the status of a user's subscription purchase.

JSON representation 
{
  "kind": string,
  "startTimeMillis": string,
  "expiryTimeMillis": string,
  "autoResumeTimeMillis": string,
  "autoRenewing": boolean,
  "priceCurrencyCode": string,
  "priceAmountMicros": string,
  "introductoryPriceInfo": {
    object (IntroductoryPriceInfo)
  },
  "countryCode": string,
  "developerPayload": string,
  "paymentState": integer,
  "cancelReason": integer,
  "userCancellationTimeMillis": string,
  "cancelSurveyResult": {
    object (SubscriptionCancelSurveyResult)
  },
  "orderId": string,
  "linkedPurchaseToken": string,
  "purchaseType": integer,
  "priceChange": {
    object (SubscriptionPriceChange)
  },
  "profileName": string,
  "emailAddress": string,
  "givenName": string,
  "familyName": string,
  "profileId": string,
  "acknowledgementState": integer,
  "externalAccountId": string,
  "promotionType": integer,
  "promotionCode": string,
  "obfuscatedExternalAccountId": string,
  "obfuscatedExternalProfileId": string
}
Fields
kind

string

This kind represents a subscriptionPurchase object in the androidpublisher service.
startTimeMillis

string (int64 format)

Time at which the subscription was granted, in milliseconds since the Epoch.
expiryTimeMillis

string (int64 format)

Time at which the subscription will expire, in milliseconds since the Epoch.
autoResumeTimeMillis

string (int64 format)

Time at which the subscription will be automatically resumed, in milliseconds since the Epoch. Only present if the user has requested to pause the subscription.
autoRenewing

boolean

Whether the subscription will automatically be renewed when it reaches its current expiry time.
priceCurrencyCode

string

ISO 4217 currency code for the subscription price. For example, if the price is specified in British pounds sterling, priceCurrencyCode is "GBP".
priceAmountMicros

string (int64 format)

Price of the subscription, For tax exclusive countries, the price doesn't include tax. For tax inclusive countries, the price includes tax. Price is expressed in micro-units, where 1,000,000 micro-units represents one unit of the currency. For example, if the subscription price is €1.99, priceAmountMicros is 1990000.
introductoryPriceInfo

object (IntroductoryPriceInfo)

Introductory price information of the subscription. This is only present when the subscription was purchased with an introductory price.

This field does not indicate the subscription is currently in introductory price period.
countryCode

string

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

string

A developer-specified string that contains supplemental information about an order.
paymentState

integer

The payment state of the subscription. Possible values are: 0. Payment pending 1. Payment received 2. Free trial 3. Pending deferred upgrade/downgrade

Not present for canceled, expired subscriptions.
cancelReason

integer

The reason why a subscription was canceled or is not auto-renewing. Possible values are: 0. User canceled the subscription 1. Subscription was canceled by the system, for example because of a billing problem 2. Subscription was replaced with a new subscription 3. Subscription was canceled by the developer
userCancellationTimeMillis

string (int64 format)

The time at which the subscription was canceled by the user, in milliseconds since the epoch. Only present if cancelReason is 0.
cancelSurveyResult

object (SubscriptionCancelSurveyResult)

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

string

The order id of the latest recurring order associated with the purchase of the subscription. If the subscription was canceled because payment was declined, this will be the order id from the payment declined order.
linkedPurchaseToken

string

The purchase token of the originating purchase if this subscription is one of the following: 0. Re-signup of a canceled but non-lapsed subscription 1. Upgrade/downgrade from a previous subscription

For example, suppose a user originally signs up and you receive purchase token X, then the user cancels and goes through the resignup flow (before their subscription lapses) and you receive purchase token Y, and finally the user upgrades their subscription and you receive purchase token Z. If you call this API with purchase token Z, this field will be set to Y. If you call this API with purchase token Y, this field will be set to X. If you call this API with purchase token X, this field will not be set.
purchaseType

integer

The type of purchase of the subscription. This field is only set if this purchase was not made using the standard in-app billing flow. Possible values are: 0. Test (i.e. purchased from a license testing account) 1. Promo (i.e. purchased using a promo code)
priceChange

object (SubscriptionPriceChange)

The latest price change information available. This is present only when there is an upcoming price change for the subscription yet to be applied.

Once the subscription renews with the new price or the subscription is canceled, no price change information will be returned.
profileName

string

The profile name of the user when the subscription was purchased. Only present for purchases made with 'Subscribe with Google'.
emailAddress

string

The email address of the user when the subscription was purchased. Only present for purchases made with 'Subscribe with Google'.
givenName

string

The given name of the user when the subscription was purchased. Only present for purchases made with 'Subscribe with Google'.
familyName

string

The family name of the user when the subscription was purchased. Only present for purchases made with 'Subscribe with Google'.
profileId

string

The Google profile id of the user when the subscription was purchased. Only present for purchases made with 'Subscribe with Google'.
acknowledgementState

integer

The acknowledgement state of the subscription product. Possible values are: 0. Yet to be acknowledged 1. Acknowledged
externalAccountId

string

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

integer

The type of promotion applied on this purchase. This field is only set if a promotion is applied when the subscription was purchased. Possible values are: 0. One time code 1. Vanity code
promotionCode

string

The promotion code applied on this purchase. This field is only set if a vanity code promotion is applied when the subscription was purchased.
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.

IntroductoryPriceInfo

Contains the introductory price information for a subscription.

JSON representation 
{
  "introductoryPriceCurrencyCode": string,
  "introductoryPriceAmountMicros": string,
  "introductoryPricePeriod": string,
  "introductoryPriceCycles": integer
}
Fields
introductoryPriceCurrencyCode

string

ISO 4217 currency code for the introductory subscription price. For example, if the price is specified in British pounds sterling, priceCurrencyCode is "GBP".
introductoryPriceAmountMicros

string (int64 format)

Introductory price of the subscription, not including tax. The currency is the same as priceCurrencyCode. Price is expressed in micro-units, where 1,000,000 micro-units represents one unit of the currency. For example, if the subscription price is €1.99, priceAmountMicros is 1990000.
introductoryPricePeriod

string

Introductory price period, specified in ISO 8601 format. Common values are (but not limited to) "P1W" (one week), "P1M" (one month), "P3M" (three months), "P6M" (six months), and "P1Y" (one year).
introductoryPriceCycles

integer

The number of billing period to offer introductory pricing.

SubscriptionCancelSurveyResult

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

JSON representation 
{
  "cancelSurveyReason": integer,
  "userInputCancelReason": string
}
Fields
cancelSurveyReason

integer

The cancellation reason the user chose in the survey. Possible values are: 0. Other 1. I don't use this service enough 2. Technical issues 3. Cost-related reasons 4. I found a better app
userInputCancelReason

string

The customized input cancel reason from the user. Only present when cancelReason is 0.

SubscriptionPriceChange

Contains the price change information for a subscription that can be used to control the user journey for the price change in the app. This can be in the form of seeking confirmation from the user or tailoring the experience for a successful conversion.

JSON representation 
{
  "newPrice": {
    object (Price)
  },
  "state": integer
}
Fields
newPrice

object (Price)

The new price the subscription will renew with if the price change is accepted by the user.
state

integer

The current state of the price change. Possible values are: 0. Outstanding: State for a pending price change waiting for the user to agree. In this state, you can optionally seek confirmation from the user using the In-App API. 1. Accepted: State for an accepted price change that the subscription will renew with unless it's canceled. The price change takes effect on a future date when the subscription renews. Note that the change might not occur when the subscription is renewed next.

Methods

acknowledge

 Acknowledges a subscription purchase.

cancel

 Cancels a user's subscription purchase.

defer

 Defers a user's subscription purchase until a specified future expiration time.

get
(deprecated)

 Deprecated: Use purchases.subscriptionsv2.get instead.

refund
(deprecated)

 Deprecated: Use orders.refund instead.

revoke
(deprecated)

 Deprecated: Use purchases.subscriptionsv2.revoke instead.

Error codes

The operations of this resource, return the following HTTP error codes:

Error code Reason Description Resolution
400 / 410 subscriptionExpired The subscription has expired and the requested operation cannot be performed. Check the subscription's expiration time. This operation is not allowed on expired subscriptions.
400 subscriptionInvalidArgument An invalid argument was provided in the request for the subscription. Review the API documentation and ensure all required fields are provided and correctly formatted.
400 invalidPurchaseState The purchase is not in a valid state to perform the requested operation. For example, you might be trying to acknowledge an already consumed purchase or cancel a subscription that is not active. Check the current state of the resource using the corresponding Get API before attempting the operation. Ensure the resource is in an appropriate state for the action.
400 invalidValue An invalid value was provided in the request. This is often returned for a malformed or invalid purchase token. Correct the invalid field value in the request body or parameters based on the API reference.
400 prepaidSubscriptionNotSupported The requested operation is not supported for prepaid subscriptions. Ensure the operation is applicable to the subscription type. This error is specific to methods like Cancel, Defer, Refund, or Revoke.
400 productNotOwnedByUser The provided purchase token is valid, but the user does not currently own the product. This can happen if the purchase was refunded, revoked or expired before acknowledgement. Check the current state of the resource using the corresponding Get API before attempting the operation. Ensure the resource is in an appropriate state for the action.
400 purchaseTokenMismatch The provided purchase token does not match the purchase, package name, subscription ID or product ID. Verify all the details in the request are correct and correspond to each other.
400 required A required field or parameter is missing from the request. Consult the API documentation to ensure all mandatory fields and parameters are included.
400 unsupportedIabType The operation is not supported for the given In-App Billing type. Ensure the API method is compatible with the item type being managed.
403 userInsufficientPermission The user does not have sufficient permission to perform the requested operation. Ensure the authenticated user has the necessary permissions in the Google Play Console. See Using a service account for more details.
404 notFound The requested resource could not be found. Verify the identifiers (e.g., purchase token, package name, product ID, subscription ID) are correct.
409 concurrentUpdate There was an attempt to update an object that is being updated concurrently. Retry the request with exponential backoff. Avoid simultaneous modifications to the same resource.
410 purchaseTokenNoLongerValid The purchase token is permanently invalid because the associated user account has been deleted or the purchase record no longer exists. Discontinue use of this purchase token.
410 subscriptionNoLongerAvailable The subscription purchase is no longer available for query because it has been expired for too long. This error indicates the subscription has been expired for more than 60 days. You should no longer query these subscriptions.
5xx Generic error Generic error in the Google Play server. Retry your request.

If the problem persists contact your Google Play account manager or submit a support request. Consider checking the Play Status Dashboard for any known outages.