Recuperare e aggiornare un abbonamento

Dopo aver recuperato un abbonamento, puoi utilizzare le informazioni della risposta riuscita per modificare lo stato dell'abbonamento o aggiornare l'abbonamento. Questa pagina si concentra sui diversi modi in cui puoi recuperare e aggiornare un abbonamento.

Recupera un abbonamento

Per recuperare un abbonamento ordinato o trasferito correttamente, utilizza la seguente GETrichiesta HTTP.

GET https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions/SUBSCRIPTION_ID

Sostituisci quanto segue:

Questa operazione non contiene parametri nel corpo della richiesta.

Una risposta corretta restituisce un codice di stato HTTP 200 e le impostazioni della sottoscrizione. Nella seguente risposta di esempio, la proprietà isInTrial è false, ma non esiste una proprietà trialEndTime, il che significa che questo cliente non ha mai partecipato a una prova senza costi di 30 giorni con questo piano.

{
  "kind": "reseller#subscription",
  "customerId": "C0123456",
  "subscriptionId": "123",
  "skuId": "1010020028",
  "billingMethod": "ONLINE",
  "creationTime": "1331647980142",
  "plan": {
    "planName": "ANNUAL",
    "isCommitmentPlan": true,
    "commitmentInterval": {
      "startTime": "1331647980142",
      "endTime": "1363183980142"
    }
  },
  "seats": {
    "kind": "subscriptions#seats",
    "numberOfSeats": 10,
    "licensedNumberOfSeats": 10
  },
  "trialSettings": {
    "isInTrial": false
  },
  "renewalSettings": {
    "kind": "subscriptions#renewalSettings",
    "renewalType": "RENEW_CURRENT_USERS_MONTHLY_PAY"
  },
  "purchaseOrderId": "example.com_annual_1",
  "status": "ACTIVE",
  "resourceUiUrl": "URL to customer's Subscriptions page in the Admin console",
  "skuName": "Google Workspace Business Standard"
}

Recupera tutti gli abbonamenti per un cliente

Per recuperare tutti gli abbonamenti di un cliente rivenditore specifico che sono stati ordinati o trasferiti correttamente, utilizza la seguente richiesta HTTP GET e includi il token di autorizzazione:

GET https://reseller.googleapis.com/apps/reseller/v1/subscriptions?customerId=CUSTOMER_ID value&pageToken=START_DATE&maxResults=MAX_NUMBER

Sostituisci quanto segue:

  • CUSTOMER_ID: nome di dominio principale del cliente o identificatore univoco del cliente.
  • START_DATE: la data di inizio nel formato YYYY-MM-DD.
  • MAX_NUMBER: il numero massimo di risultati restituiti in una pagina di risposta.

Questa operazione non contiene parametri nel corpo della richiesta.

Una risposta corretta restituisce un codice di stato HTTP 200 e un elenco degli abbonamenti e delle impostazioni del cliente. L'elenco degli abbonamenti potrebbe includere prodotti non gestiti in questa versione dell'API dei rivenditori.

Se non gestisci questo cliente non è gestito, viene restituito un errore 403 "Forbidden".

Recuperare tutti gli abbonamenti trasferibili per un cliente

Per recuperare tutti gli abbonamenti di un cliente che potrebbero essere trasferiti alla gestione del rivenditore, utilizza la seguente richiesta HTTP GET e includi il token di autorizzazione. Il customerId è obbligatorio ed è l'identificatore univoco del cliente restituito al recupero dell'account di un cliente del rivenditore. customerAuthToken è un token di trasferimento fornito dal cliente specifico del tuo ID rivenditore. Una volta generato dal cliente, è valido per 30 giorni. Per maggiori informazioni su come i clienti generano il token, vedi Trasferire l'account Google Workspace a un rivenditore.

GET https://reseller.googleapis.com/apps/reseller/v1/subscriptions?customerId=CUSTOMER_ID&customerAuthToken=AUTH_TOKEN&pageToken=START_DATE&maxResults=MAX_NUMBER

Sostituisci quanto segue:

  • CUSTOMER_ID: nome di dominio principale del cliente o identificatore univoco del cliente.
  • AUTH_TOKEN: un token di trasferimento fornito dal cliente, specifico per il tuo ID rivenditore. Dopo essere stato generato dal cliente, è valido per 30 giorni. Per maggiori informazioni su come i clienti generano il token, vedi Trasferire l'account Google Workspace a un rivenditore. Se questo valore non è valido o è scaduto, la risposta dell'API restituisce un errore 403 "Forbidden".
  • START_DATE: la data di inizio nel formato YYYY-MM-DD.
  • MAX_NUMBER: il numero massimo di risultati restituiti in una pagina di risposta.

Questa operazione non contiene parametri nel corpo della richiesta.

Una risposta corretta restituisce un codice di stato HTTP 200 e un elenco degli abbonamenti trasferibili del cliente con la data di scadenza del token di trasferimento e il numero minimo di utenze richieste nell'ordine di trasferimento. Un cliente potrebbe trattenere altri abbonamenti non trasferibili.

{
  "kind": "reseller#subscriptions",
  "subscriptions": [
    {
      "kind": "subscriptions#subscription",
      "customerId": "custId-6543",
      "subscriptionId": "432",
      "skuId": "1010020028",
      "billingMethod": "ONLINE",
      "creationTime": "1331647980142",
      "plan": {
        "planName": "ANNUAL",
        "isCommitmentPlan": true,
        "commitmentInterval": {
          "startTime": "1331647980142",
          "endTime": "1363183980142"
        }
      },
      "seats": {
        "kind": "subscriptions#seats",
        "numberOfSeats": 10,
        "maximumNumberOfSeats": 500,
        "licensedNumberOfSeats": 10
      },
      "trialSettings": {
        "isInTrial": false
      },
      "renewalSettings": {
        "kind": "subscriptions#renewalSettings",
        "renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
      },
      "transferInfo": {
        "transferabilityExpirationTime": "1333183980142",
        "minimumTransferableSeats": "20"
      },
      "purchaseOrderId": "PO_890",
      "status": "ACTIVE",
      "resourceUiUrl": "URL to customer's Subscriptions page in the Admin console",
      "skuName": "Google Workspace Business Standard"
    },
    {
      "kind": "subscriptions#subscription",
      "customerId": "custId-6543",
      "subscriptionId": "140",
      "skuId": "1010020028",
      "creationTime": "1329389322728",
      "plan": {
        "planName": "FLEXIBLE",
        "isCommitmentPlan": false
      },
      "seats": {
        "kind": "subscriptions#seats",
        "maximumNumberOfSeats": 50
        "licensedNumberOfSeats": 10
      },
      "trialSettings": {
        "isInTrial": false,
        "trialEndTime": "1331877480016"
      },
      "renewalSettings": {
        "kind": "subscriptions#renewalSettings",
        "renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
      },
      "transferInfo": {
        "transferabilityExpirationTime": "1333183780159",
        "minimumTransferableSeats": "10"
      },
      "purchaseOrderId": "",
      "status": "ACTIVE",
      "resourceUiUrl": "URL to customer's Subscriptions page in the Admin console",
      "skuName": "Google Workspace Business Standard"
    },
  ],
  "nextPageToken": "token"
}

Se prevedi di trasferire queste sottoscrizioni tramite l'operazione batch, trasferisci tutte le sottoscrizioni. Se trasferisci singolarmente ogni abbonamento si verifica un errore. Inoltre, l'operazione batch trasferisce solo gli abbonamenti con stato ACTIVE. Per maggiori informazioni, vedi Trasferire un abbonamento.

Recupera tutti gli abbonamenti dei rivenditori

Per recuperare tutti gli abbonamenti ordinati o trasferiti correttamente da un rivenditore, usa la seguente richiesta HTTP GET e includi il token di autorizzazione. 

GET https://reseller.googleapis.com/apps/reseller/v1/subscriptions?customerNamePrefix=PREFIX &pageToken=TOKEN&maxResults=MAX_NUMBER

Sostituisci quanto segue:

  • PREFIX: l'inizio del nome del cliente di cui stai cercando gli abbonamenti.
  • TOKEN: un token che identifica una pagina di risultati specifica che il server dovrebbe restituire.
  • MAX_NUMBER: il numero massimo di risultati restituiti in una pagina di risposta.

Questa operazione può utilizzare l'ambito di accesso di sola lettura OAuth. Le customerNamePrefix, pageToken e maxResults sono stringhe di query facoltative.

L'esempio seguente recupera tutte le sottoscrizioni di un rivenditore che appartengono ai clienti il cui nome inizia con "exam":

GET https://reseller.googleapis.com/apps/reseller/v1/subscriptions?customerNamePrefix=exam

{
  "kind": "reseller#subscriptions",
  "subscriptions": [
    {
      "kind": "subscriptions#subscription",
      "customerId": "C0123456",
      "subscriptionId": "123",
      "skuId": "1010020028",
      "creationTime": "1331647980142",
      "billingMethod": "ONLINE",
      "plan": {
        "planName": "ANNUAL",
        "isCommitmentPlan": true,
        "commitmentInterval": {
          "startTime": "1331647980142",
          "endTime": "1363183980142"
        }
      },
      "seats": {
        "kind": "subscriptions#seats",
        "numberOfSeats": 10,
        "licensedNumberOfSeats": 10
      },
      "trialSettings": {
        "isInTrial": false
      },
      "renewalSettings": {
        "kind": "subscriptions#renewalSettings",
        "renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
      },
      "purchaseOrderId": "PO_135",
      "status": "ACTIVE",
      "resourceUiUrl": "URL to customer's Subscriptions page in the Admin console",
      "skuName": "Google Workspace Business Standard"
    },
    {
      "kind": "subscriptions#subscription",
      "customerId": "custId-5678",
      "subscriptionId": "1404686",
      "skuId": "1010020028",
      "billingMethod": "ONLINE",
      "creationTime": "1329389322728",
      "plan": {
        "planName": "FLEXIBLE",
        "isCommitmentPlan": false
      },
      "seats": {
        "kind": "subscriptions#seats",
        "maximumNumberOfSeats": 50,
        "licensedNumberOfSeats": 10
      },
      "trialSettings": {
        "isInTrial": false,
        "trialEndTime": "1331877480016"
      },
      "renewalSettings": {
        "kind": "subscriptions#renewalSettings",
        "renewalType": "AUTO_RENEW"
      },
      "purchaseOrderId": "",
      "status": "ACTIVE",
      "resourceUiUrl": "URL to customer's Subscriptions page in the Admin console",
      "skuName": "Google Workspace Business Standard"
    },
  ],
  "nextPageToken": "token"
}

Aggiornare un piano di abbonamento

L'aggiornamento dei piani di Google Workspace varia a seconda del piano. Prima di aggiornare un piano, tieni presente quanto segue:

  • Quando crei un abbonamento e il cliente è idoneo, il piano dell'abbonamento può essere una prova di 30 giorni. Sia il piano di pagamento flessibile che quello annuale possono essere di prova senza costi di 30 giorni. Durante la prova, puoi cambiare il piano di pagamento dell'abbonamento in piano con impegno flessibile o annuale tutte le volte che vuoi. Tuttavia, al termine della prova e quando il piano diventa attivo, l'aggiornamento del piano segue le stesse regole dei piani attivi degli altri abbonamenti. Per passare immediatamente un abbonamento di prova a un piano attivo, attiva un servizio a pagamento da un abbonamento di prova senza costi di 30 giorni. Per ulteriori informazioni sulla prova di 30 giorni e sulle regole di qualificazione dei clienti, consulta il Centro assistenza per l'amministrazione.

  • Puoi aggiornare un piano flessibile a un piano con impegno annuale.

  • Non puoi aggiornare un piano con impegno annuale.

  • Non tutti i piani funzionano con tutti i prodotti. Per ulteriori informazioni su quali prodotti vengono utilizzati da questi piani, consulta la pagina Prodotti e SKU.

Per aggiornare un piano per una prova di 30 giorni o un abbonamento con piano flessibile a un piano con impegno annuale, utilizza la seguente richiesta HTTP POST:

POST https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions/SUBSCRIPTION_ID/changePlan

Sostituisci quanto segue:

L'esempio seguente aggiorna la sottoscrizione con subscriptionId con un valore pari a 123. Il customerId è C0123456.

POST https://reseller.googleapis.com/apps/reseller/v1/customers/C0123456/subscriptions/123/changePlan

Il corpo della richiesta contiene quanto segue:

{
  "kind": "reseller#changePlanRequest",
  "planName": "ANNUAL_MONTHLY_PAY",
  "seats": {
    "kind": "subscriptions#seats",
    "numberOfSeats": 10
  },
  "purchaseOrderId": "123_March2012"
}

Una risposta corretta restituisce un codice di stato HTTP 201 e le impostazioni del piano di abbonamento aggiornate:

{
  "kind": "reseller#subscription",
  "customerId": "C0123456",
  "subscriptionId": "123",
  "skuId": "1010020028",
  "creationTime": "1331647980142",
  "plan": {
    "planName": "ANNUAL",
    "isCommitmentPlan": true,
    "commitmentInterval": {
      "startTime": "1331647980142",
      "endTime": "1363183980142"
    }
  },
  "seats": {
    "kind": "subscriptions#seats",
    "numberOfSeats": 10,
    "licensedNumberOfSeats": 10
  },
  "trialSettings": {
    "isInTrial": false
  },
  "renewalSettings": {
    "kind": "subscriptions#renewalSettings",
    "renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
  },
  "purchaseOrderId": "123_March2012",
  "status": "ACTIVE",
  "skuName": "Google Workspace Business Standard"
}

Aggiornare le utenze di un abbonamento

L'aggiornamento di un abbonamento a un piano di impegno annuale utilizza proprietà di abbonamento diverse rispetto all'aggiornamento dell'abbonamento di un piano flessibile di Google Workspace.

Aggiornare le utenze per l'abbonamento di un piano annuale

Per aggiornare le impostazioni delle licenze utente di un abbonamento a un piano annuale, utilizza la seguente richiesta HTTP POST:

POST https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions/SUBSCRIPTION_ID/changeSeats

Sostituisci quanto segue:

L'esempio seguente aggiorna la sottoscrizione con il codice 123 subscriptionId. Il valore customerId è C0123456. Il corpo della richiesta varia in base al tipo di piano:

POST https://reseller.googleapis.com/apps/reseller/v1/customers/C0123456/subscriptions/123/changeSeats

L'abbonamento di un piano con impegno annuale a Google Workspace utilizza questo corpo della richiesta per aggiornare il numero di licenze utente. Il valore numberOfSeats è un totale. Ad esempio, se in precedenza avevi 10 licenze utente e hai un ordine cliente per 5 nuove licenze, il totale nel corpo della richiesta per numberOfSeats è 15, come mostrato nell'esempio seguente:

{
    "kind": "subscriptions#seats",
    "numberOfSeats": 15
}

Aggiornare le utenze per l'abbonamento a un piano flessibile

L'abbonamento a un piano flessibile di Google Workspace utilizza il corpo della richiesta per aggiornare le licenze utente. Il valore maximumNumberOfSeats corrisponde al totale delle licenze esistenti e delle nuove licenze. Corrisponde al numero massimo di licenze utente di cui l'account può eseguire il provisioning.

{
  "kind": "subscriptions#seats",
  "maximumNumberOfSeats": 15
}

Una risposta corretta restituisce un codice di stato HTTP 201 e le impostazioni delle licenze di abbonamento aggiornate:

{
  "kind": "reseller#subscription",
  "customerId": "C0123456",
  "subscriptionId": "123",
  "skuId": "1010020028",
  "creationTime": "1331647980142",
  "plan": {
    "planName": "FLEXIBLE",
    "isCommitmentPlan": false
  },
  "seats": {
    "kind": "subscriptions#seats",
    "maximumNumberOfSeats": 15,
    "licensedNumberOfSeats": 10
  },
  "trialSettings": {
    "isInTrial": false
  },
  "skuName": "Google Workspace Business Standard"
}

Aggiornare le impostazioni di rinnovo di un abbonamento

Per aggiornare le impostazioni di rinnovo di un abbonamento con impegno annuale, utilizza la seguente richiesta HTTP POST:

POST https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions/SUBSCRIPTION_ID/changeRenewalSettings

Sostituisci quanto segue:

Di seguito è riportato un esempio di corpo di richiesta:

{
  "kind": "subscriptions#renewalSettings",
  "renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
}

Il valore della proprietà renewalType può essere uno dei seguenti:

  • AUTO_RENEW_YEARLY_PAY: al termine dell'intervallo di un piano con impegno annuale, rinnova automaticamente il piano dell'abbonamento come ANNUAL_YEARLY_PAY con lo stesso numberOfSeats.
  • AUTO_RENEW_MONTHLY_PAY: al termine dell'intervallo di un piano di impegno annuale, rinnova automaticamente il piano dell'abbonamento come ANNUAL_MONTHLY_PAY con lo stesso numberOfSeats.
  • RENEW_CURRENT_USERS_YEARLY_PAY: al termine dell'intervallo di un piano con impegno annuale, rinnova il piano dell'abbonamento come ANNUAL_YEARLY_PAY, ma utilizza il numero totale di licenze utente attive correnti. Questa è l'impostazione predefinita per i piani con impegno annuale attivi (pagamento annuale).
  • RENEW_CURRENT_USERS_MONTHLY_PAY: al termine dell'intervallo di un piano con impegno annuale, rinnova il piano dell'abbonamento come ANNUAL_MONTHLY_PAY, ma utilizza il numero totale di licenze utente attive correnti. Questa è l'impostazione predefinita per i piani di impegno annuale attivi (pagati mensilmente).
  • RENEW_ON_PROPOSED_OFFER: al termine dell'intervallo del piano di impegno attuale, rinnova in base all'ultima proposta di rinnovo con numberOfSeats come numero di licenze utente attive attuali o impegno di offerta proposto a seconda di quale sia superiore.
  • SWITCH_TO_PAY_AS_YOU_GO: al termine dell'intervallo di un piano con impegno annuale, cambia il piano con impegno annuale in un piano flessibile.
  • CANCEL: al termine di un intervallo del piano di impegno annuale, l'abbonamento viene sospeso. Per informazioni su come revocare una sospensione, consulta il Centro assistenza per l'amministrazione.

Una risposta corretta restituisce un codice di stato HTTP 201 e le impostazioni di rinnovo dell'abbonamento aggiornate:

{
  "kind": "reseller#subscription",
  "customerId": "C0123456",
  "subscriptionId": "123",
  "skuId": "1010020028",
  "creationTime": "1331647980142",
  "plan": {
    "planName": "ANNUAL",
    "isCommitmentPlan": true,
    "commitmentInterval": {
      "startTime": "1331647980142",
      "endTime": "1363183980142"
    }
  },
  "seats": {
    "kind": "subscriptions#seats",
    "numberOfSeats": 15,
    "licensedNumberOfSeats": 15
  },
  "trialSettings": {
    "isInTrial": false
  },
  "renewalSettings": {
    "kind": "subscriptions#renewalSettings",
    "renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
  },
  "skuName": "Google Workspace Business Standard"
}

Attivazione del servizio a pagamento partendo da un abbonamento di prova senza costi

Per passare immediatamente un abbonamento di prova senza costi di 30 giorni a un abbonamento a un servizio a pagamento, se è già stato configurato un piano di pagamento per l'abbonamento di prova, utilizza la seguente richiesta HTTP POST. 

POST https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions/SUBSCRIPTION_ID/startPaidService

Sostituisci quanto segue:

L'esempio seguente ha C0123456 come customerId e il valore subscriptionId di 123:

POST https://reseller.googleapis.com/apps/reseller/v1/customers/C0123456/subscriptions/123/startPaidService

Questa operazione non contiene parametri nel corpo della richiesta.

Una risposta corretta restituisce un codice di stato HTTP 201 e le impostazioni di iscrizione aggiornate:

{
  "kind": "reseller#subscription",
  "customerId": "C0123456",
  "subscriptionId": "123",
  "skuId": "1010020028",
  "creationTime": "1331647980142",
  "plan": {
    "planName": "ANNUAL",
    "isCommitmentPlan": true,
    "commitmentInterval": {
      "startTime": "1331647980142",
      "endTime": "1363183980142"
    }
  },
  "seats": {
    "kind": "subscriptions#seats",
    "numberOfSeats": 15,
    "licensedNumberOfSeats": 15
  },
  "trialSettings": {
    "isInTrial": false
  },
  "renewalSettings": {
    "kind": "subscriptions#renewalSettings",
    "renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
  },
  "skuName": "Google Workspace Business Standard"
}

Eseguire l'upgrade o il downgrade di un abbonamento

Non puoi eseguire il downgrade dei piani annuali nel corso del periodo di validità e non puoi pianificare un downgrade utilizzando le impostazioni di rinnovo. Ti consigliamo di configurare le impostazioni di rinnovo in modo da passare a FLEXIBLE e di eseguire il downgrade dopo la data di rinnovo.

Per eseguire l'upgrade o il downgrade di un abbonamento, crea un nuovo abbonamento con il skuId per cui vuoi eseguire l'upgrade o il downgrade.

POST https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions

Sostituisci quanto segue:

  • CUSTOMER_ID: nome di dominio principale del cliente o identificatore univoco del cliente.

Questa chiamata termina l'abbonamento precedente e ne crea uno nuovo.

Puoi trovare ulteriori informazioni su upgrade e downgrade nella pagina Prodotti e SKU.