A Google Play relationship field showing which prior subscription purchase a newly issued token has replaced.
linkedPurchaseToken appears in a Google Play subscription resource when a new purchase supersedes an earlier one, such as certain upgrades, downgrades, or resubscriptions. It gives a backend the lineage needed to retire the previous purchase. The value is not a customer identifier and should not be exposed as one; both tokens remain opaque credentials whose state must be verified through the Play Developer API.
A plan replacement is processed as a new purchase. The app receives a new token, the server calls purchases.subscriptionsv2.get, verifies package and product context, acknowledges the new purchase when required, and examines replacement information. If a linked token exists, Google’s guidance is to invalidate the old token in the entitlement system so it cannot continue granting access independently. This prevents double entitlement, duplicated renewal records, and replay of a superseded purchase.
The field is contextual, not guaranteed on every return to a subscription. Restoring a canceled but still active subscription can retain the same token. A fresh resubscription after expiration may create a new token without linkedPurchaseToken. Current subscriptionsv2 line items also expose itemReplacement details that help explain product-level changes, including deferred replacements and subscriptions with add-ons. Code must handle absent links safely rather than assuming every new token has a predecessor.
Persist a one-way replacement relationship inside the same transaction that updates entitlement ownership. Reject cycles, scope the old purchase to the correct app and user, and make repeated notifications idempotent. Never delete audit history simply because a token is no longer active; mark it superseded so support and reconciliation can explain the chain. Apple transaction lineage uses different identifiers such as original transaction information and does not return this Play-named field, so cross-platform storage should normalize purpose while preserving raw store evidence.
The opaque Play purchase credential represented on both sides of the link.
The plan-change rules that commonly lead to replacement purchases.
The access record that must not remain active for both tokens.
Preserve lineage while keeping one valid entitlement path.
Start free