REST Resource: purchases.subscriptions

Tài nguyên: SubscriptionPurchase

Tài nguyên SubscriptionPurchase cho biết trạng thái của giao dịch mua gói thuê bao của người dùng.

Biểu diễn dưới dạng JSON 
{
  "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
}
Trường
kind

string

Loại này đại diện cho một đối tượng subscriptionPurchase trong dịch vụ androidpublisher.
startTimeMillis

string (int64 format)

Thời gian cấp gói thuê bao, tính bằng mili giây kể từ Thời gian bắt đầu của hệ thống.
expiryTimeMillis

string (int64 format)

Thời gian gói thuê bao hết hạn, tính bằng mili giây kể từ Thời gian bắt đầu của hệ thống.
autoResumeTimeMillis

string (int64 format)

Thời gian gói thuê bao sẽ tự động tiếp tục, tính bằng mili giây kể từ Thời gian bắt đầu của hệ thống. Chỉ xuất hiện nếu người dùng yêu cầu tạm dừng gói thuê bao.
autoRenewing

boolean

Liệu gói thuê bao có tự động gia hạn khi hết hạn hay không.
priceCurrencyCode

string

Mã đơn vị tiền tệ theo tiêu chuẩn ISO 4217 cho giá thuê bao. Ví dụ: nếu giá được chỉ định bằng đồng bảng Anh, thì priceCurrencyCode là "GBP".
priceAmountMicros

string (int64 format)

Giá của gói thuê bao. Đối với các quốc gia chưa bao gồm thuế, giá này chưa bao gồm thuế. Đối với các quốc gia tính thuế gộp vào giá, giá sẽ bao gồm thuế. Giá được biểu thị bằng đơn vị một phần triệu, trong đó 1.000.000 đơn vị một phần triệu tương đương với một đơn vị tiền tệ. Ví dụ: nếu giá thuê bao là 1, 99 EUR, thì priceAmountMicros là 1990000.
introductoryPriceInfo

object (IntroductoryPriceInfo)

Thông tin về giá ưu đãi của gói thuê bao. Thông tin này chỉ xuất hiện khi gói thuê bao được mua với giá ưu đãi.

Trường này không cho biết gói thuê bao hiện đang trong thời gian áp dụng giá ưu đãi.
countryCode

string

Mã quốc gia/khu vực thanh toán gồm 2 chữ cái theo chuẩn ISO 3166-1 của người dùng tại thời điểm cấp gói thuê bao.
developerPayload

string

Chuỗi do nhà phát triển chỉ định chứa thông tin bổ sung về đơn đặt hàng.
paymentState

integer

Trạng thái thanh toán của gói thuê bao. Giá trị có thể là: 0. Khoản thanh toán đang chờ xử lý 1. Đã nhận được khoản thanh toán 2. Dùng thử miễn phí 3. Đang chờ xử lý yêu cầu tạm hoãn nâng cấp/hạ cấp

Không có đối với gói thuê bao đã huỷ hoặc hết hạn.
cancelReason

integer

Lý do gói thuê bao bị huỷ hoặc không tự động gia hạn. Giá trị có thể là: 0. Người dùng đã huỷ gói thuê bao 1. Hệ thống đã huỷ gói thuê bao, ví dụ: do vấn đề về việc thanh toán 2. Gói thuê bao đã được thay thế bằng một gói thuê bao mới 3. Nhà phát triển đã huỷ gói thuê bao
userCancellationTimeMillis

string (int64 format)

Thời gian người dùng huỷ gói thuê bao, tính bằng mili giây kể từ thời gian bắt đầu của hệ thống UNIX. Chỉ xuất hiện nếu cancelReason là 0.
cancelSurveyResult

object (SubscriptionCancelSurveyResult)

Thông tin do người dùng cung cấp khi họ hoàn tất quy trình huỷ gói thuê bao (khảo sát lý do huỷ).
orderId

string

Mã đơn đặt hàng của đơn đặt hàng định kỳ mới nhất được liên kết với giao dịch mua gói thuê bao. Nếu gói thuê bao bị huỷ do khoản thanh toán bị từ chối, thì đây sẽ là mã đơn đặt hàng của đơn đặt hàng bị từ chối thanh toán.
linkedPurchaseToken

string

Mã thông báo giao dịch mua của giao dịch mua ban đầu nếu gói thuê bao này thuộc một trong những trường hợp sau: 0. Đăng ký lại gói thuê bao đã huỷ nhưng chưa hết hạn 1. Nâng cấp/hạ cấp từ gói thuê bao cũ

Ví dụ: giả sử người dùng ban đầu đăng ký và bạn nhận được mã thông báo giao dịch mua X, sau đó người dùng huỷ và thực hiện quy trình đăng ký lại (trước khi gói thuê bao hết hạn) và bạn nhận được mã thông báo giao dịch mua Y, cuối cùng người dùng nâng cấp gói thuê bao và bạn nhận được mã thông báo giao dịch mua Z. Nếu bạn gọi API này bằng mã thông báo giao dịch mua Z, thì trường này sẽ được đặt thành Y. Nếu bạn gọi API này bằng mã thông báo giao dịch mua Y, thì trường này sẽ được đặt thành X. Nếu bạn gọi API này bằng mã thông báo giao dịch mua X, thì trường này sẽ không được đặt.
purchaseType

integer

Loại giao dịch mua gói thuê bao. Trường này chỉ được đặt nếu giao dịch mua này không được thực hiện bằng quy trình thanh toán tiêu chuẩn trong ứng dụng. Giá trị có thể là: 0. Kiểm thử (tức là mua từ tài khoản kiểm thử cấp phép) 1. Khuyến mãi (tức là mua bằng mã khuyến mãi)
priceChange

object (SubscriptionPriceChange)

Thông tin mới nhất về việc thay đổi giá. Trường này chỉ xuất hiện khi gói thuê bao sắp thay đổi giá nhưng chưa được áp dụng.

Sau khi gói thuê bao được gia hạn với giá mới hoặc gói thuê bao bị huỷ, hệ thống sẽ không trả về thông tin về việc thay đổi giá.
profileName

string

Tên hồ sơ của người dùng khi mua gói thuê bao. Chỉ xuất hiện đối với những giao dịch mua được thực hiện bằng tính năng "Đăng ký qua Google".
emailAddress

string

Địa chỉ email của người dùng khi mua gói thuê bao. Chỉ xuất hiện đối với những giao dịch mua được thực hiện bằng tính năng "Đăng ký qua Google".
givenName

string

Tên của người dùng khi mua gói thuê bao. Chỉ xuất hiện đối với những giao dịch mua được thực hiện bằng tính năng "Đăng ký qua Google".
familyName

string

Họ của người dùng khi mua gói thuê bao. Chỉ xuất hiện đối với những giao dịch mua được thực hiện bằng tính năng "Đăng ký qua Google".
profileId

string

Mã hồ sơ Google của người dùng khi họ mua gói thuê bao. Chỉ xuất hiện đối với những giao dịch mua được thực hiện bằng tính năng "Đăng ký qua Google".
acknowledgementState

integer

Trạng thái xác nhận của sản phẩm thuê bao. Giá trị có thể là: 0. Chưa được xác nhận 1. Đã xác nhận
externalAccountId

string

Giá trị nhận dạng tài khoản người dùng trong dịch vụ bên thứ ba. Chỉ xuất hiện nếu quá trình liên kết tài khoản diễn ra trong quy trình mua gói thuê bao.
promotionType

integer

Loại chương trình khuyến mãi được áp dụng cho giao dịch mua này. Trường này chỉ được đặt nếu bạn áp dụng chương trình khuyến mãi khi mua gói thuê bao. Giá trị có thể là: 0. Mã sử dụng một lần 1. Mã đặc trưng
promotionCode

string

Mã khuyến mãi được áp dụng cho giao dịch mua này. Trường này chỉ được đặt nếu bạn áp dụng chương trình khuyến mãi mã tuỳ chỉnh khi mua gói thuê bao.
obfuscatedExternalAccountId

string

Một phiên bản bị làm rối của mã nhận dạng được liên kết duy nhất với tài khoản của người dùng trong ứng dụng của bạn. Xuất hiện cho các giao dịch mua sau đây: * Nếu quá trình liên kết tài khoản diễn ra trong quy trình mua gói thuê bao. * Được chỉ định bằng https://developer.android.com/reference/com/android/billingclient/api/BillingFlowParams.Builder#setobfuscatedaccountid khi giao dịch mua được thực hiện.
obfuscatedExternalProfileId

string

Một phiên bản bị làm rối mã nguồn của mã nhận dạng được liên kết riêng biệt với hồ sơ người dùng trong ứng dụng của bạn. Chỉ xuất hiện nếu được chỉ định bằng https://developer.android.com/reference/com/android/billingclient/api/BillingFlowParams.Builder#setobfuscatedprofileid khi giao dịch mua được thực hiện.

IntroductoryPriceInfo

Chứa thông tin về giá ưu đãi của một gói thuê bao.

Biểu diễn dưới dạng JSON 
{
  "introductoryPriceCurrencyCode": string,
  "introductoryPriceAmountMicros": string,
  "introductoryPricePeriod": string,
  "introductoryPriceCycles": integer
}
Trường
introductoryPriceCurrencyCode

string

Mã đơn vị tiền tệ theo tiêu chuẩn ISO 4217 cho giá thuê bao ưu đãi. Ví dụ: nếu giá được chỉ định bằng đồng bảng Anh, thì priceCurrencyCode là "GBP".
introductoryPriceAmountMicros

string (int64 format)

Giá ưu đãi của gói thuê bao, chưa bao gồm thuế. Đơn vị tiền tệ giống với priceCurrencyCode. Giá được biểu thị bằng đơn vị một phần triệu, trong đó 1.000.000 đơn vị một phần triệu biểu thị một đơn vị tiền tệ. Ví dụ: nếu giá thuê bao là 1, 99 EUR, thì priceAmountMicros là 1990000.
introductoryPricePeriod

string

Kỳ hạn của giá ưu đãi, được chỉ định ở định dạng ISO 8601. Các giá trị phổ biến là (nhưng không giới hạn ở) "P1W" (một tuần), "P1M" (một tháng), "P3M" (ba tháng), "P6M" (sáu tháng) và "P1Y" (một năm).
introductoryPriceCycles

integer

Số kỳ thanh toán để cung cấp giá ưu đãi.

SubscriptionCancelSurveyResult

Thông tin do người dùng cung cấp khi họ hoàn tất quy trình huỷ gói thuê bao (khảo sát lý do huỷ).

Biểu diễn dưới dạng JSON 
{
  "cancelSurveyReason": integer,
  "userInputCancelReason": string
}
Trường
cancelSurveyReason

integer

Lý do huỷ mà người dùng chọn trong bản khảo sát. Giá trị có thể là: 0. Khác 1. Tôi không hay sử dụng dịch vụ này 2. Vấn đề kỹ thuật 3. Lý do liên quan đến chi phí 4. Tôi tìm thấy ứng dụng tốt hơn
userInputCancelReason

string

Lý do huỷ thông tin đầu vào do người dùng tuỳ chỉnh. Chỉ xuất hiện khi cancelReason là 0.

SubscriptionPriceChange

Chứa thông tin về việc thay đổi giá của gói thuê bao. Thông tin này có thể dùng để kiểm soát hành trình của người dùng khi thay đổi giá trong ứng dụng. Thông tin này có thể ở dạng yêu cầu người dùng xác nhận hoặc điều chỉnh trải nghiệm để đạt được lượt chuyển đổi thành công.

Biểu diễn dưới dạng JSON 
{
  "newPrice": {
    object (Price)
  },
  "state": integer
}
Trường
newPrice

object (Price)

Giá mới mà gói thuê bao sẽ gia hạn nếu người dùng chấp nhận thay đổi về giá.
state

integer

Trạng thái hiện tại của việc thay đổi giá. Giá trị có thể là: 0. Đang chờ xử lý: Trạng thái cho một thay đổi về giá đang chờ xử lý và người dùng cần đồng ý. Trong trạng thái này, bạn có thể tuỳ ý yêu cầu người dùng xác nhận bằng cách sử dụng API Trong ứng dụng. 1. Đã chấp nhận: Trạng thái cho một thay đổi về giá đã được chấp nhận. Gói thuê bao sẽ gia hạn trừ phi bị huỷ. Thay đổi về giá sẽ có hiệu lực vào một ngày trong tương lai khi gói thuê bao được gia hạn. Xin lưu ý rằng thay đổi này có thể không có hiệu lực vào lần gia hạn gói thuê bao tiếp theo.

Phương thức

acknowledge

 Xác nhận giao dịch mua gói thuê bao.

cancel

 Huỷ giao dịch mua gói thuê bao của người dùng.

defer

 Hoãn giao dịch mua gói thuê bao của người dùng cho đến một thời điểm hết hạn cụ thể trong tương lai.

get
(deprecated)

 Không dùng nữa: Thay vào đó, hãy sử dụng purchases.subscriptionsv2.get.

refund
(deprecated)

 Không dùng nữa: Thay vào đó, hãy sử dụng orders.refund.

revoke
(deprecated)

 Không dùng nữa: Thay vào đó, hãy sử dụng purchases.subscriptionsv2.revoke.

Mã lỗi

Các thao tác của tài nguyên này sẽ trả về các mã lỗi HTTP sau:

Mã lỗi Lý do Mô tả Độ phân giải
400 / 410 subscriptionExpired Gói thuê bao đã hết hạn và không thể thực hiện thao tác yêu cầu. Kiểm tra thời gian hết hạn của gói thuê bao. Thao tác này không được phép đối với các gói thuê bao đã hết hạn.
400 subscriptionInvalidArgument Bạn đã cung cấp một đối số không hợp lệ trong yêu cầu đăng ký. Xem lại tài liệu API và đảm bảo bạn đã cung cấp tất cả các trường bắt buộc và định dạng đúng.
400 invalidPurchaseState Giao dịch mua không ở trạng thái hợp lệ để thực hiện thao tác đã yêu cầu. Ví dụ: bạn có thể đang cố gắng xác nhận một giao dịch mua đã được sử dụng hoặc huỷ một gói thuê bao không còn hoạt động. Kiểm tra trạng thái hiện tại của tài nguyên bằng cách sử dụng Get API tương ứng trước khi thử thực hiện thao tác. Đảm bảo tài nguyên ở trạng thái phù hợp cho hành động.
400 invalidValue Bạn đã cung cấp một giá trị không hợp lệ trong yêu cầu. Lỗi này thường xảy ra khi mã thông báo mua hàng bị lỗi hoặc không hợp lệ. Hãy sửa giá trị trường không hợp lệ trong nội dung hoặc tham số yêu cầu dựa trên tài liệu tham khảo API.
400 prepaidSubscriptionNotSupported Thao tác đã yêu cầu không được hỗ trợ đối với gói thuê bao trả trước. Đảm bảo rằng thao tác này áp dụng được cho loại gói thuê bao. Lỗi này chỉ xảy ra với các phương thức như Huỷ, Hoãn, Hoàn tiền hoặc Thu hồi.
400 productNotOwnedByUser Mã thông báo mua hàng được cung cấp là hợp lệ, nhưng người dùng hiện không sở hữu sản phẩm. Điều này có thể xảy ra nếu giao dịch mua được hoàn tiền, thu hồi hoặc hết hạn trước khi được xác nhận. Kiểm tra trạng thái hiện tại của tài nguyên bằng cách sử dụng Get API tương ứng trước khi thử thực hiện thao tác. Đảm bảo tài nguyên ở trạng thái phù hợp cho hành động.
400 purchaseTokenMismatch Mã thông báo giao dịch mua được cung cấp không khớp với giao dịch mua, tên gói, mã nhận dạng gói thuê bao hoặc mã nhận dạng sản phẩm. Xác minh rằng tất cả thông tin chi tiết trong yêu cầu đều chính xác và tương ứng với nhau.
400 required Yêu cầu thiếu một trường hoặc tham số bắt buộc. Tham khảo tài liệu API để đảm bảo bạn đã thêm tất cả các trường và tham số bắt buộc.
400 unsupportedIabType Loại Thanh toán trong ứng dụng đã cho không hỗ trợ thao tác này. Đảm bảo phương thức API tương thích với loại mục đang được quản lý.
403 userInsufficientPermission Người dùng không có đủ quyền để thực hiện thao tác được yêu cầu. Đảm bảo người dùng được xác thực có các quyền cần thiết trong Google Play Console. Hãy xem phần Sử dụng tài khoản dịch vụ để biết thêm thông tin.
404 notFound Không tìm thấy tài nguyên được yêu cầu. Xác minh rằng các giá trị nhận dạng (ví dụ: mã thông báo giao dịch mua, tên gói, mã sản phẩm, mã thuê bao) là chính xác.
409 concurrentUpdate Đã có một nỗ lực cập nhật một đối tượng đang được cập nhật đồng thời. Thử lại yêu cầu với thời gian đợi luỹ thừa. Tránh sửa đổi đồng thời cùng một tài nguyên.
410 purchaseTokenNoLongerValid Mã thông báo mua hàng không hợp lệ vĩnh viễn vì tài khoản người dùng được liên kết đã bị xoá hoặc bản ghi mua hàng không còn tồn tại. Ngừng sử dụng mã thông báo mua hàng này.
410 subscriptionNoLongerAvailable Không thể truy vấn giao dịch mua gói thuê bao nữa vì giao dịch này đã hết hạn quá lâu. Lỗi này cho biết gói thuê bao đã hết hạn hơn 60 ngày. Bạn không nên truy vấn các gói thuê bao này nữa.
5xx Generic error Lỗi chung trong máy chủ Google Play. Hãy thử gửi lại yêu cầu.

Nếu vấn đề vẫn tiếp diễn, hãy liên hệ với người quản lý tài khoản Google Play hoặc gửi yêu cầu hỗ trợ. Hãy cân nhắc kiểm tra Trang tổng quan về trạng thái của Play để xem có sự cố ngừng hoạt động nào đã biết hay không.