Cambiare lo stato della fatturazione di una sottoscrizione per un utente

  • Articolo

Usare questo metodo nell'API di acquisto Microsoft Store per modificare lo stato di fatturazione di un componente aggiuntivo per un dato utente. È possibile annullare, estendere, rimborsare o disabilitare il rinnovo automatico di una sottoscrizione.

Nota

Questo metodo può essere usato solo dagli account degli sviluppatori di cui è stato effettuato il provisioning da Microsoft per consentire loro di creare componenti aggiuntivi di sottoscrizione per le app UWP (Universal Windows Platform). I componenti aggiuntivi di sottoscrizione non sono attualmente disponibili per la maggior parte degli account degli sviluppatori.

La libreria Microsoft.StoreServices fornisce la funzionalità di questo metodo tramite l'API StoreServicesClient.RecurrenceChangeAysnc.

Prerequisiti

Per utilizzare questo metodo, avrai bisogno di:

  • Un token di accesso di Azure AD con il valore URI del gruppo di destinatari https://onestore.microsoft.com.
  • Un chiave ID di Microsoft Store che rappresenta l'identità dell'utente in possesso di un diritto sulla sottoscrizione che si desidera modificare.

Per ulteriori informazioni, vedere Gestire i diritti dei prodotti di un servizio.

Richiedi

Sintassi della richiesta

metodo URI della richiesta
POST https://purchase.mp.microsoft.com/v8.0/b2b/recurrences/{recurrenceId}/change

Intestazione della richiesta

Intestazione Type Descrizione
Autorizzazione stringa Obbligatorio. Token di accesso di Azure AD nel formato Token di<connessione>.
Host string Deve essere impostato sul valore purchase.mp.microsoft.com.
Content-Length number Lunghezza del corpo della richiesta.
Content-Type string Specifica il tipo di richiesta e risposta. Attualmente, l'unico valore supportato è application/json.

Parametri della richiesta

Nome Tipo Descrizione Richiesto
recurrenceId string L'ID della sottoscrizione che si desidera modificare. Per ottenere questo ID, chiamare il metodo di recupero delle sottoscrizioni di un utente, identificare la voce del corpo della risposta che rappresenta il componente aggiuntivo della sottoscrizione che si desidera modificare e usare il valore del campo id per la voce. Sì

Corpo della richiesta

Campo Tipo Descrizione Richiesto
b2bKey string La chiave ID di Microsoft Store che rappresenta l'identità dell'utente di cui si desidera modificare la sottoscrizione. Sì
changeType string Una delle stringhe seguenti che identifica il tipo di modifica che si desidera apportare:
  • Cancel: annulla la sottoscrizione.
  • Extend: estende la sottoscrizione. Se si specifica questo valore, è necessario includere anche il parametro extensionTimeInDays.
  • Refund: rimborsa la sottoscrizione al cliente.
  • ToggleAutoRenew: disabilita il rinnova automatico della sottoscrizione. Se il rinnovo automatico della sottoscrizione è attualmente disabilitato, questo valore non esegue alcuna operazione.
 Sì
extensionTimeInDays string Se il parametro changeType ha il valore Extend, questo parametro specifica il numero di giorni di estensione della sottoscrizione. Sì se changeType ha il valore Extend, in caso contrario no.

Esempio di richiesta

L'esempio seguente illustra come usare questo metodo per estendere di 5 giorni il periodo di sottoscrizione. Sostituire il valore b2bKey con la chiave ID di Microsoft Store che rappresenta l'identità dell'utente di cui si desidera modificare la sottoscrizione.

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"
}

Response

Questo metodo restituisce un corpo della risposta JSON che contiene informazioni sul componente aggiuntivo della sottoscrizione modificato, inclusi i campi modificati. L'esempio seguente mostra un corpo della risposta per questo metodo.

{
  "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"
    }
  ]
}

Corpo della risposta

Il corpo della risposta contiene i dati seguenti:

Valore Tipo Descrizione
autoRenew Booleano Indica se la sottoscrizione è configurata per il rinnovo automatico alla fine del periodo di sottoscrizione corrente.
beneficiary string ID del beneficiario del diritto associato a questa sottoscrizione.
expirationTime string Data e ora di scadenza della sottoscrizione, in formato ISO 8601. Questo campo è disponibile solo quando la sottoscrizione è in determinati stati. L'ora di scadenza indica in genere quando scade lo stato corrente. Ad esempio, per una sottoscrizione attiva, la data di scadenza indica quando si verificherà il successivo rinnovo automatico.
expirationTimeWithGrace string Data e ora in cui la sottoscrizione scadrà, incluso il periodo di tolleranza, in formato ISO 8601. Questo valore indica quando l'utente perderà l'accesso alla sottoscrizione dopo che la sottoscrizione non è stata rinnovata automaticamente.
id string ID della sottoscrizione. Usare questo valore per indicare quale sottoscrizione si desidera modificare quando si chiama il metodo di modifica dello stato di fatturazione di una sottoscrizione per un utente.
isTrial Booleano Indica se la sottoscrizione è relativa a una versione di valutazione.
LastModified string Data e ora dell'ultima modifica della sottoscrizione, in formato ISO 8601.
market string Codice del Paese (in formato ISO 3166-1 alpha-2 a due lettere) in cui l'utente ha acquisito la sottoscrizione.
productId string ID dello Store per il prodotto che rappresenta il componente aggiuntivo di sottoscrizione nel catalogo di Microsoft Store. Un esempio di ID dello Store per un prodotto è 9NBLGGH42CFD.
skuId string ID dello Store per lo SKU che rappresenta il componente aggiuntivo di sottoscrizione nel catalogo di Microsoft Store. Un esempio di ID dello Store per uno SKU è 0010.
startTime string Data e ora di inizio della sottoscrizione, in formato ISO 8601.
recurrenceState string Uno dei valori seguenti:
  • None: indica una sottoscrizione perpetua.
  • Active: la sottoscrizione è attiva e l'utente ha diritto di usare i servizi.
  • Inactive: la sottoscrizione ha superato la data di scadenza e l'utente ne ha disattivato l'opzione di rinnovo automatico.
  • Annullata: la sottoscrizione è stata terminata intenzionalmente prima della data di scadenza, con o senza rimborso.
  • InDunning: la sottoscrizione è in stato di sollecito (ossia, è prossima alla scadenza e Microsoft sta tentando di acquisire i fondi per rinnovarla automaticamente).
  • Failed: il periodo di sollecito è terminato è non è stato possibile rinnovare la sottoscrizione dopo diversi tentativi.

Nota:

  • Inactive/Canceled/Failed sono stati di terminazione. Quando una sottoscrizione entra in uno di questi stati, l'utente deve riacquistarla per attivarla di nuovo. L'utente non ha diritto di usare i servizi in questi stati.
  • Quando una sottoscrizione è Canceled, il valore expirationTime verrà aggiornato con la data e l'ora dell'annullamento.
  • L'ID della sottoscrizione rimarrà invariato durante l'intera durata. Non cambierà se l'opzione di rinnovo automatico è attivata o disattivata. Se un utente acquista nuovamente una sottoscrizione dopo aver raggiunto uno stato di terminazione, verrà creato un nuovo ID sottoscrizione.
  • L'ID di una sottoscrizione deve essere usato per eseguire qualsiasi operazione su una singola sottoscrizione.
  • Quando un utente acquista nuovamente una sottoscrizione dopo averla annullata o interrotta, se si eseguono query sui risultati per l'utente, si otterranno due voci: una con l'ID sottoscrizione precedente in uno stato di terminazione e una con il nuovo ID sottoscrizione in uno stato attivo.
  • È sempre consigliabile controllare sia recurrenceState che expirationTime, poiché gli aggiornamenti di recurrenceState possono ritardare di alcuni minuti (o anche ore).
cancellationDate string Data e ora di annullamento della sottoscrizione dell'utente, in formato ISO 8601.