Mengubah status penagihan langganan untuk pengguna

  • Artikel

Gunakan metode ini di API pembelian Microsoft Store untuk mengubah status penagihan add-on langganan untuk pengguna tertentu. Anda dapat membatalkan, memperpanjang, mengembalikan dana, atau menonaktifkan perpanjangan otomatis untuk langganan.

Catatan

Metode ini hanya dapat digunakan oleh akun pengembang yang telah disediakan oleh Microsoft untuk dapat membuat add-on langganan untuk aplikasi Platform Windows Universal (UWP). Add-on langganan saat ini tidak tersedia untuk sebagian besar akun pengembang.

Pustaka Microsoft.StoreServices menyediakan fungsionalitas metode ini melalui STOREServicesClient.RecurrenceChangeAysnc API.

Prasyarat

Untuk menggunakan metode ini, Anda memerlukan:

  • Token akses Azure AD yang memiliki nilai https://onestore.microsoft.comURI audiens .
  • Kunci ID Microsoft Store yang mewakili identitas pengguna yang memiliki pemberian izin atas langganan yang ingin Anda ubah.

Untuk informasi selengkapnya, lihat Mengelola pemberian izin produk dari layanan.

Minta

Minta sintaks

Metode URI Permintaan
KIRIM https://purchase.mp.microsoft.com/v8.0/b2b/recurrences/{recurrenceId}/change

Meminta header

Header Jenis Deskripsi
Authorization string Wajib diisi. Token akses Azure AD dalam bentuktoken>Pembawa<.
Host string Harus diatur ke nilai purchase.mp.microsoft.com.
Panjang-Konten nomor Panjang isi permintaan.
Jenis-Konten string Menentukan jenis permintaan dan respons. Saat ini, satu-satunya nilai yang didukung adalah aplikasi/json.

Parameter permintaan

Nama Jenis Deskripsi Diperlukan
recurrenceId string ID langganan yang ingin Anda ubah. Untuk mendapatkan ID ini, panggil dapatkan langganan untuk metode pengguna , identifikasi entri isi respons yang mewakili add-on langganan yang ingin Anda ubah, dan gunakan nilai bidang id untuk entri tersebut. Ya

Isi permintaan

Bidang Jenis Deskripsi Diperlukan
b2bKey string Kunci ID Microsoft Store yang mewakili identitas pengguna yang langganannya ingin Anda ubah. Ya
changeType string Salah satu string berikut yang mengidentifikasi jenis perubahan yang ingin Anda buat:
  • Batal: Membatalkan langganan.
  • Perluas: Memperluas langganan. Jika Anda menentukan nilai ini, Anda juga harus menyertakan parameter extensionTimeInDays .
  • Pengembalian Dana: Mengembalikan dana langganan kepada pelanggan.
  • ToggleAutoRenew: Menonaktifkan perpanjangan otomatis untuk langganan. Jika perpanjangan otomatis saat ini dinonaktifkan untuk langganan, nilai ini tidak melakukan apa pun.
 Ya
extensionTimeInDays string Jika parameter changeType memiliki nilai Perpanjang, parameter ini menentukan jumlah hari untuk memperpanjang langganan. Ya, jika changeType memiliki nilai Extend; jika tidak, tidak.

Contoh permintaan

Contoh berikut menunjukkan cara menggunakan metode ini untuk memperpanjang periode langganan sebesar 5 hari. Ganti nilai b2bKey dengan kunci ID Microsoft Store yang mewakili identitas pengguna yang langganannya ingin Anda ubah.

POST https://purchase.mp.microsoft.com/v8.0/b2b/recurrences/mdr:0:bc0cb6960acd4515a0e1d638192d77b7:77d5ebee-0310-4d23-b204-83e8613baaac/change HTTP/1.1
Authorization: Bearer <your access token>
Content-Type: application/json
Host: https://purchase.mp.microsoft.com

{
  "b2bKey":  "eyJ0eXAiOiJ...",
  "changeType": "Extend",
  "extensionTimeInDays": "5"
}

Respons

Metode ini mengembalikan isi respons JSON yang berisi informasi tentang add-on langganan yang dimodifikasi, termasuk bidang apa pun yang dimodifikasi. Contoh berikut menunjukkan isi respons untuk metode ini.

{
  "items": [
    {
      "autoRenew":true,
      "beneficiary":"pub:gFVuEBiZHPXonkYvtdOi+tLE2h4g2Ss0ZId0RQOwzDg=",
      "expirationTime":"2017-06-16T03:07:49.2552941+00:00",
      "id":"mdr:0:bc0cb6960acd4515a0e1d638192d77b7:77d5ebee-0310-4d23-b204-83e8613baaac",
      "lastModified":"2017-01-10T21:08:13.1459644+00:00",
      "market":"US",
      "productId":"9NBLGGH52Q8X",
      "skuId":"0024",
      "startTime":"2017-01-10T21:07:49.2552941+00:00",
      "recurrenceState":"Active"
    }
  ]
}

Isi Respons

Isi respons berisi data berikut.

Nilai Jenis Deskripsi
autoRenew Boolean Menunjukkan apakah langganan dikonfigurasi untuk diperpanjang secara otomatis pada akhir periode langganan saat ini.
penerima string ID penerima atas pemberian izin yang terkait dengan langganan ini.
expirationTime string Tanggal dan waktu langganan akan kedaluwarsa, dalam format ISO 8601. Bidang ini hanya tersedia ketika langganan berada dalam status tertentu. Waktu kedaluwarsa biasanya menunjukkan kapan status saat ini kedaluwarsa. Misalnya, untuk langganan aktif, tanggal kedaluwarsa menunjukkan kapan perpanjangan otomatis berikutnya akan terjadi.
expirationTimeWithGrace string Tanggal dan waktu langganan akan kedaluwarsa termasuk masa tenggang, dalam format ISO 8601. Nilai ini menunjukkan kapan pengguna akan kehilangan akses ke langganan setelah langganan gagal diperpanjang secara otomatis.
id string ID langganan. Gunakan nilai ini untuk menunjukkan langganan mana yang ingin Anda ubah saat Memanggil perubahan status penagihan langganan untuk metode pengguna .
isTrial Boolean Menunjukkan apakah langganan adalah uji coba.
lastModified string Tanggal dan waktu langganan terakhir diubah, dalam format ISO 8601.
market string Kode negara (dalam format ISO 3166-1 alpha-2 dua huruf) tempat pengguna memperoleh langganan.
productId string ID Bursa untuk produk yang mewakili add-on langganan di katalog Microsoft Store. Contoh ID Store untuk produk adalah 9NBLGGH42CFD.
skuId string ID Toko untuk SKU yang mewakili add-on langganan katalog Microsoft Store. Contoh ID Store untuk SKU adalah 0010.
startTime string Tanggal dan waktu mulai untuk langganan, dalam format ISO 8601.
recurrenceState string Salah satu dari nilai berikut:
  • Tidak Ada: Ini menunjukkan langganan abadi.
  • Aktif: Langganan aktif dan pengguna berhak menggunakan layanan.
  • Tidak aktif: Langganan melewati tanggal kedaluwarsa, dan pengguna menonaktifkan opsi perpanjangan otomatis untuk langganan.
  • Dibatalkan: Langganan telah dihentikan secara sengaja sebelum tanggal kedaluwarsa, dengan atau tanpa pengembalian dana.
  • InDunning: Langganan dalam dunning (yaitu, langganan mendekati kedaluwarsa, dan Microsoft mencoba memperoleh dana untuk memperbarui langganan secara otomatis).
  • Gagal: Periode dunning berakhir dan langganan gagal diperpanjang setelah beberapa upaya.

Catatan:

  • Aktif/Dibatalkan/Gagal adalah status terminal. Saat langganan memasuki salah satu status ini, pengguna harus membeli kembali langganan untuk mengaktifkannya lagi. Pengguna tidak berhak menggunakan layanan di status ini.
  • Saat langganan Dibatalkan, expirationTime akan diperbarui dengan tanggal dan waktu pembatalan.
  • ID langganan akan tetap sama selama masa pakainya. Ini tidak akan berubah jika opsi perpanjangan otomatis diaktifkan atau dinonaktifkan. Jika pengguna membeli kembali langganan setelah mencapai status terminal, ID langganan baru akan dibuat.
  • ID langganan harus digunakan untuk menjalankan operasi apa pun pada langganan individual.
  • Saat pengguna membeli kembali langganan setelah membatalkan atau menghentikannya, jika Anda meminta hasil untuk pengguna, Anda akan mendapatkan dua entri: satu dengan ID langganan lama dalam status terminal, dan satu dengan ID langganan baru dalam status aktif.
  • Ini selalu merupakan praktik yang baik untuk memeriksa recurrenceState dan expirationTime, karena pembaruan ke recurrenceState berpotensi tertunda beberapa menit (atau kadang-kadang berjam-jam).
cancellationDate string Tanggal dan waktu langganan pengguna dibatalkan, dalam format ISO 8601.