REST Resource: purchases.productsv2

  • A ProductPurchaseV2 resource indicates the status of a user's in-app product purchase.

  • Key information includes the product line items, purchase state context, test purchase context, order ID, and acknowledgement state.

  • The PurchaseStateContext provides details about the purchase state, which can be PURCHASED, CANCELLED, or PENDING.

  • ProductLineItem contains item-level information such as the product ID and offer details.

  • The resource includes information on consumption state and acknowledgement state of the purchase.

Resource: ProductPurchaseV2

A ProductPurchaseV2 resource indicates the status of a user's inapp product purchase.

JSON representation 
{
  "productLineItem": [
    {
      object (ProductLineItem)
    }
  ],
  "kind": string,
  "purchaseStateContext": {
    object (PurchaseStateContext)
  },
  "testPurchaseContext": {
    object (TestPurchaseContext)
  },
  "orderId": string,
  "obfuscatedExternalAccountId": string,
  "obfuscatedExternalProfileId": string,
  "regionCode": string,
  "purchaseCompletionTime": string,
  "acknowledgementState": enum (AcknowledgementState)
}
Fields
productLineItem[]

object (ProductLineItem)

Contains item-level info for a ProductPurchaseV2.
kind

string

This kind represents a ProductPurchaseV2 object in the androidpublisher service.
purchaseStateContext

object (PurchaseStateContext)

Information about the purchase state of the purchase.
testPurchaseContext

object (TestPurchaseContext)

Information related to test purchases. This will only be set for test purchases.
orderId

string

The order id associated with the purchase of the inapp product. May not be set if there is no order associated with the purchase.
obfuscatedExternalAccountId

string

An obfuscated version of the id that is uniquely associated with the user's account in your app. Only present if 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.
regionCode

string

ISO 3166-1 alpha-2 billing region code of the user at the time the product was granted.
purchaseCompletionTime

string (Timestamp format)

The time when the purchase was successful, i.e., when the PurchaseState has changed to PURCHASED. This field will not be present until the payment is complete. For example, if the user initiated a pending transaction (https://developer.android.com/google/play/billing/integrate#pending), this field will not be populated until the user successfully completes the steps required to complete the transaction.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
acknowledgementState

enum (AcknowledgementState)

Output only. The acknowledgement state of the purchase.

PurchaseStateContext

Context about the purchase state.

JSON representation 
{
  "purchaseState": enum (PurchaseState)
}
Fields
purchaseState

enum (PurchaseState)

Output only. The purchase state of the purchase.

PurchaseState

Possible purchase states.

Enums
PURCHASE_STATE_UNSPECIFIED Purchase state unspecified. This value should never be set.
PURCHASED Purchased successfully.
CANCELLED Purchase canceled.
PENDING The purchase is in a pending state and has not yet been completed. For more information on handling pending purchases, see https://developer.android.com/google/play/billing/integrate#pending.

TestPurchaseContext

Context about a test purchase.

JSON representation 
{
  "fopType": enum (FopType)
}
Fields
fopType

enum (FopType)

The fop type of the test purchase.

FopType

Possible fop types.

Enums
FOP_TYPE_UNSPECIFIED Fop type unspecified. This value should never be set.
TEST The purchase was made using a test card.

ProductLineItem

Contains item-level info for a ProductPurchaseV2.

JSON representation 
{
  "productId": string,
  "productOfferDetails": {
    object (ProductOfferDetails)
  }
}
Fields
productId

string

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

object (ProductOfferDetails)

The offer details for this item.

ProductOfferDetails

Offer details information related to a purchase line item.

JSON representation 
{
  "offerTags": [
    string
  ],
  "offerId": string,
  "purchaseOptionId": string,
  "rentOfferDetails": {
    object (RentOfferDetails)
  },
  "offerToken": string,
  "quantity": integer,
  "refundableQuantity": integer,
  "consumptionState": enum (ConsumptionState)
}
Fields
offerTags[]

string

The latest offer tags associated with the offer. It includes tags inherited from the purchase option.
offerId

string

The offer ID. Only present for offers.
purchaseOptionId

string

The purchase option ID.
rentOfferDetails

object (RentOfferDetails)

Offer details about rent offers. This will only be set for rental line items.
offerToken

string

The per-transaction offer token used to make this purchase line item.
quantity

integer

The quantity associated with the purchase of the inapp product.
refundableQuantity

integer

The quantity eligible for refund, i.e. quantity that hasn't been refunded. The value reflects quantity-based partial refunds and full refunds.
consumptionState

enum (ConsumptionState)

Output only. The consumption state of the purchase.

RentOfferDetails

This type has no fields.

Offer details information related to a rental line item.

ConsumptionState

Possible consumption states.

Enums
CONSUMPTION_STATE_UNSPECIFIED Consumption state unspecified. This value should never be set.
CONSUMPTION_STATE_YET_TO_BE_CONSUMED Yet to be consumed.
CONSUMPTION_STATE_CONSUMED Consumed already.

AcknowledgementState

Acknowledgement state of the one time product.

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

Methods

getproductpurchasev2

 Checks the purchase and consumption status of an inapp item.

Error codes

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

Error code Reason Description Resolution
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 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.
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.