Menjadwalkan perubahan untuk langganan perdagangan baru menggunakan API Pusat Mitra

Berlaku untuk: Pusat Mitra

Artikel ini menjelaskan bagaimana Anda dapat menggunakan API Partner Center untuk menjadwalkan perubahan untuk langganan perdagangan baru yang hanya terjadi pada perpanjangan langganan. API ini mendukung langganan perangkat lunak dan berbasis lisensi perdagangan baru.

Nota

Pengalaman perdagangan baru untuk layanan berbasis lisensi mencakup banyak kemampuan baru dan tersedia untuk semua Penyedia Solusi Cloud (CSP). Untuk informasi selengkapnya, lihat gambaran umum pengalaman perdagangan baru .

Membuat perubahan terjadwal memungkinkan Anda mengubah langganan, secara otomatis, saat perpanjangan berikutnya terjadi. Dengan menjadwalkan perubahan, Anda dapat memilih untuk menambah atau mengurangi jumlah lisensi, mengubah jangka waktu dan frekuensi penagihan, dan bahkan memilih untuk meningkatkan SKU. Perubahan penjadwalan memungkinkan Anda melakukan modifikasi pada langganan Anda pada perpanjangan, bukan segera selama jangka waktu saat ini.

Penting

Jika Anda membuat perubahan jangka menengah (segera) sebelum tanggal perpanjangan, semua perubahan terjadwal yang sebelumnya dijadwalkan terjadi saat perpanjangan akan dihapus.

Prasyarat

Kredensial seperti yang dijelaskan dalam autentikasi Pusat Mitra. Skenario ini mendukung autentikasi dengan kredensial Aplikasi mandiri dan Aplikasi+Pengguna.
ID pelanggan (customer-tenant-id). Jika Anda tidak mengetahui ID pelanggan, Anda dapat mencarinya di Pusat Mitra dengan memilih ruang kerja Pelanggan, lalu pelanggan dari daftar pelanggan, lalu Akun. Pada halaman Akun pelanggan, cari ID Microsoft di bagian Info Akun Pelanggan. ID Microsoft sama dengan ID pelanggan (customer-tenant-id).
ID langganan.
Perpanjangan otomatis diaktifkan pada langganan.

Metode Pusat Mitra

Untuk menjadwalkan perubahan langganan di Pusat Mitra:

Pilih pelanggan.
Pilih langganan yang ingin Anda jadwalkan perubahannya.
Aktifkan Perpanjangan otomatis.
Pilih Kelola perpanjangan.
Lakukan modifikasi pada langganan untuk dilakukan pada perpanjangan.
Pilih Oke untuk menutup panel samping.
pilih Kirim untuk menyimpan perubahan.

Nota

Perpanjangan diproses setelah hari terakhir dalam jangka waktu, mulai pukul 12.00 UTC pada hari berikutnya. Perpanjangan diproses dalam antrean dan mungkin memerlukan waktu hingga 24 jam untuk diproses.

C#

Untuk menjadwalkan perubahan langganan pelanggan:

Dapatkan langganan berdasarkan ID.
Dapatkan kelayakan transisi untuk jenis kelayakan transisi terjadwal.
Buat objek ScheduledNextTermInstructions dan tetapkan sebagai properti langganan.
Panggil metode Patch() untuk memperbarui langganan dengan perubahan terjadwal.

var selectedSubscription = subscriptionOperations.Get();
selectedSubscription.ScheduledNextTermInstructions = new ScheduledNextTermInstructions
{
    Product = new ProductTerm
    {
        ProductId = changeToProductId,
        SkuId = changeToSkuId,
        AvailabilityId = changeToAvailabilityId,
        BillingCycle = changeToBillingCycle,
        TermDuration = changeToTermDuration,
    },
    Quantity = changeToQuantity,
    customTermEndDate = DateTime,
};
var updatedSubscription = subscriptionOperations.Patch(selectedSubscription);

Untuk menjadwalkan perubahan langganan pelanggan, di mana perubahan terjadwal yang diinginkan adalah ke produk yang berbeda:

Dapatkan langganan berdasarkan ID.
Dapatkan kelayakan transisi untuk jenis kelayakan transisi terjadwal.
Panggil metode Patch() untuk memperbarui langganan dengan perubahan terjadwal.

Permintaan REST

Sintaks dari permintaan

Metode	Meminta URI
PATCH	{baseURL}/v1/customers/{customer-tenant-id}/subscriptions/{subscription-id} HTTP/1.1

Parameter URI

Tabel ini mencantumkan parameter kueri yang diperlukan untuk memanggil API.

Nama	Jenis	Diperlukan	Deskripsi
id penyewa pelanggan	panduan	Ya	GUID yang sesuai dengan pelanggan.
id langganan	panduan	Ya	GUID yang merupakan identifikasi unik yang sesuai dengan langganan.

Header permintaan

Untuk informasi selengkapnya, lihat header REST Pusat Mitra.

Isi permintaan

Sumber daya Langganan lengkap diperlukan di dalam isi permintaan, dengan properti scheduledNextTermInstructions ditentukan. Untuk menjadwalkan perubahan langganan Anda, pastikan bahwa properti AutoRenewEnabled diatur ke true.

Untuk ID ketersediaan pada akhir penjualan dengan konversi (EndofSaleWithConversions) menawarkan:

GetTransitionEligibility akan mengembalikan CatalogItemID.

sebuah. Pastikan untuk mengatur jenis kelayakan Terjadwal jika tidak, defaultnya segera.
Gunakan CatalogItemID untuk kemudian mengekstrak availabilityID.

Jika Anda menggunakan GET Availabilities untuk menentukan ketersediaan untuk instruksi ScheduledNextTerm dan jika semua istilah berada dalam status EOS, Anda akan menerima daftar kosong. Cara terbaik untuk menentukan jalur yang valid adalah dengan memanggil GetTransitionEligibilty API untuk mengembalikan opsi yang valid.

Lapangan	Jenis	Diperlukan	Deskripsi
PetunjukJadwalUntukIstilahBerikutnya	objek	Ya	Menentukan instruksi periode berikutnya untuk langganan. Properti berisi objek `product` dan bidang `quantity`.

Menggunakan scheduledActions untuk menetapkan instruksi periode berikutnya (perubahan terjadwal)

Ketentuan layanan tambahan menyediakan cara baru untuk menetapkan instruksi saat masa berlaku berakhir. Konstruk baru scheduledActions memberi mitra satu cara untuk menentukan pembaruan untuk jangka waktu berikutnya, termasuk pembatalan, perpanjangan ke jangka layanan yang diperpanjang, atau perpanjangan ke target akhir masa berlaku lainnya. Mitra dapat mengatur instruksi scheduledActions RenewToNewTerm alih-alih scheduledNextTermInstructions sebelumnya. Selengkapnya tentang penggunaan scheduledActions untuk menetapkan instruksi masa berlaku berikutnya dapat ditemukan di dokumentasi masa berlaku layanan tambahan.

Mitra yang menggunakan scheduledActions harus menghindari juga melewati scheduledNextTermInstructions saat membuat pembaruan untuk langganan yang memenuhi syarat untuk persyaratan layanan yang diperpanjang. Mitra yang memilih untuk meneruskan keduanya harus menyadari bahwa hanya scheduledActions yang dipertimbangkan. Mitra dapat terus mengirim hanya scheduledNextTermInstructions untuk mengatur instruksi untuk istilah berikutnya.

Penting

Hindari meneruskan instruksi untuk periode berikutnya di kedua scheduledActions dan nextTermInstructions. Gunakan satu atau yang lain. Jika keduanya diberikan, instruksi scheduledActions akan digunakan sebagai default.

Permintaan melalui aksi terjadwal

{
  "autoRenewEnabled": true,
  "scheduledActions": [
    {
      "scheduledType": "TermEnd",
      "actionType": "RenewToNewTerm",
      "instructions": {
        "product": {
          "productId": "CFQ7TTC0LHXH",
          "skuId": "0001",
          "availabilityId": "CFQ7TTC0LHXH",
          "billingCycle": "annual",
          "termDuration": "P1Y",
          "promotionId": "39NFJQT20KJ2:0001:39NFJQT1Q5KK"
        },
        "quantity": 25,
        "customTermEndDate": "2027-11-31T23:59:59.000Z"
      }
    }
  ]
}

Respons menggunakan tindakan terjadwal

{
  "autoRenewEnabled": true,
  "scheduledNextTermInstructions" : {
     "product": {
        "productId": "CFQ7TTC0LHXH",
        "skuId": "0001",
        "availabilityId": "CFQ7TTC0LHXH",
        "billingCycle": "annual",
        "termDuration": "P1Y",
        "promotionId": "39NFJQT20KJ2:0001:39NFJQT1Q5KK"
      },
      "quantity": 25,
      "customTermEndDate": "2027-11-31T23:59:59.000Z"
  },
  "scheduledActions":   "scheduledActions": [
    {
      "scheduledType": "TermEnd",
      "actionType": "RenewToNewTerm",
      "instructions": {
        "product": {
          "productId": "CFQ7TTC0LHXH",
          "skuId": "0001",
          "availabilityId": "CFQ7TTC0LHXH",
          "billingCycle": "annual",
          "termDuration": "P1Y",
          "promotionId": "39NFJQT20KJ2:0001:39NFJQT1Q5KK"
        },
        "quantity": 25,
        "customTermEndDate": "2027-11-31T23:59:59.000Z"
      }
    }
  ]
}

Menggunakan scheduledActions untuk mengatur transisi pada hari jadi

Beberapa SKU tiga tahunan tertentu yang mencakup Teams dapat dijadwalkan untuk dialihkan pada tanggal peringatan masa berlangganan.

Permintaan menggunakan tindakan terjadwal

{ 
    "id": "c10138d2-083b-4330-cf0d-6565dfaf22be", 
    "offerId": "CFQ7TTC0ZSXT:0001:CFQ7TTC0K85Z", 
    … 
    "scheduledActions": [ 
        { 
            "scheduleType": "CustomDate", // currently supported - EndOfTerm
            "actionType": "Transition", // currently supported - RenewToNewTerm, RenewToExtendedServiceTerm, Cancel 
            "effectiveDate": "2026-08-01", 
            "instructions": { 
                "product": { 
                    "productId": "CFQ7TTC0ZSXT", 
                    "skuId": "0001", 
                    "availabilityId": "CFQ7TTC0K8B0", 
                    "billingCycle": "monthly", 
                    "termDuration": "P1M" 
                }, 
            } 
        } 
    ] 
}

Permintaan yang menggunakan instruksi termin berikutnya yang terjadwal

PATCH https://api.partnercenter.microsoft.com/v1/customers/<customer-tenant-id>/subscriptions/<subscription-id> HTTP/1.1
Authorization: Bearer <token>
Accept: application/json
MS-RequestId: ca7c39f7-1a80-43bc-90d8-ee7d1cad3831
MS-CorrelationId: aaaa0000-bb11-2222-33cc-444444dddddd
If-Match: <etag>
Content-Type: application/json
Content-Length: 1029
Expect: 100-continue
Connection: Keep-Alive

{
    "id": "6e7aa601-629e-461b-8933-0898c3cc3c7c",
    "offerId": "DZH318Z0BXWC:0001:DZH318Z0BMJX",
    "offerName": "offer Name",
    "friendlyName": "friendly Name",
    "quantity": 1,
    "customTermEndDate": "2019-01-09T00:21:45.9263727",
    "unitType": "License(s)",
    "hasPurchasableAddons": false,
    "creationDate": "2019-01-04T01:00:12.6647304Z",
    "effectiveStartDate": "2019-01-09T00:21:45.9263727+00:00",
    "commitmentEndDate": "2019-02-08T00:21:45.9263727+00:00",
    "status": "active",
    "autoRenewEnabled": true,
    "scheduledNextTermInstructions": { 
      "product": { 
         "productId":  "DG7GMGF0DVSV", 
         "skuId":  "000P", 
         "availabilityId":  "DG7GMGF0F3Q9", 
         "billingCycle":  "Annual", 
         "termDuration":  "P3Y",
         "promotionId": "39NFJQT1PFPJ:000H:39NFJQT1Q5DK"
        }, 
      "quantity":  1 
      "customTermEndDate" : "2019-01-09T00:21:45.9263727",
     },  // original value = null 
    "isTrial": false,
    "billingType": "license",
    "billingCycle": "monthly",
    "termDuration": "P1M",
    "refundOptions": [{
        "type": "Full",
        "expiresAt": "2019-01-10T00:21:45.9263727+00:00"
    }],
    "isMicrosoftProduct": false,
    "partnerId": "",
    "contractType": "subscription",
    "publisherName": "publisher Name",
    "orderId": "ImxjLNL4_fOc-2KoyOxGTZcrlIquzls11",
    "attributes": {"objectType": "Subscription"},
}

Respons REST

Jika permintaan berhasil, metode ini akan mengembalikan properti-properti sumber daya Langganan yang telah diperbarui dalam isi respons.

Kode kesalahan dan keberhasilan respons

Setiap respons dilengkapi dengan kode status HTTP yang menunjukkan keberhasilan atau kegagalan, dan informasi penelusuran kesalahan lainnya. Gunakan alat pelacakan jaringan untuk membaca kode ini, jenis kesalahan, dan parameter lainnya. Untuk daftar lengkapnya, lihat kode kesalahan .

Respons menggunakan instruksi jangka waktu berikutnya yang dijadwalkan

HTTP/1.1 200 OK
Content-Length: 1322
Content-Type: application/json; charset=utf-8
MS-RequestId: ca7c39f7-1a80-43bc-90d8-ee7d1cad3831
MS-CorrelationId: aaaa0000-bb11-2222-33cc-444444dddddd
X-Locale: en-US

{
    "id": "6e7aa601-629e-461b-8933-0898c3cc3c7c",
    "offerId": "DZH318Z0BXWC:0001:DZH318Z0BMJX",
    "offerName": "offer Name",
    "friendlyName": "friendly Name",
    "quantity": 1,
    "customTermEndDate": "2019-01-09T00:21:45.9263727",
    "unitType": "License(s)",
    "hasPurchasableAddons": false,
    "creationDate": "2019-01-04T01:00:12.6647304Z",
    "effectiveStartDate": "2019-01-09T00:21:45.9263727+00:00",
    "commitmentEndDate": "2019-02-08T00:21:45.9263727+00:00",
    "status": "active",
    "autoRenewEnabled": true,
    "scheduledNextTermInstructions": { 
      "product": { 
         "productId":  "DG7GMGF0DVSV", 
         "skuId":  "000P", 
         "availabilityId":  "DG7GMGF0F3Q9", 
         "billingCycle":  "Annual", 
         "termDuration":  "P3Y",
         "promotionId": "39NFJQT1PFPJ:000H:39NFJQT1Q5DK"
        }, 
      "quantity":  1 
      "customTermEndDate": "2019-01-09T00:21:45.9263727",
     },  // original value = null 
    "isTrial": false,
    "billingType": "license",
    "billingCycle": "monthly",
    "termDuration": "P1M",
    "refundOptions": [{
        "type": "Full",
        "expiresAt": "2019-01-10T00:21:45.9263727+00:00"
    }],
    "isMicrosoftProduct": false,
    "partnerId": "",
    "contractType": "subscription",
    "publisherName": "publisher Name",
    "orderId": "ImxjLNL4_fOc-2KoyOxGTZcrlIquzls11",
    "attributes": {"objectType": "Subscription"},
}

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-06-30