Recuperare e aggiornare un abbonamento

Dopo aver recuperato un abbonamento, puoi utilizzare le informazioni della risposta positiva per modificare lo stato dell'abbonamento o aggiornarlo. Questa pagina illustra i diversi modi in cui puoi recuperare e aggiornare un abbonamento.

Recuperare 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:

  • CUSTOMER_ID: il nome del dominio principale del cliente o il suo identificatore univoco.
  • SUBSCRIPTION_ID: l'identificatore dell'abbonamento, unico per ogni cliente. Puoi recuperare questo valore utilizzando il metodo Recupera tutti gli abbonamenti del rivenditore.

Questa operazione non ha parametri nel corpo della richiesta.

Una risposta riuscita restituisce un codice di stato HTTP 200 e le impostazioni dell'abbonamento. Nell'esempio di risposta seguente, la proprietà isInTrial è false, ma non è presente la proprietà trialEndTime, il che significa che questo cliente non ha mai usufruito di 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"
}

Recuperare tutti gli abbonamenti di 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: il nome del dominio principale del cliente o il suo identificatore univoco.
  • 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 ha 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 che non sono gestiti in questa versione dell'API Reseller.

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

Recuperare tutti gli abbonamenti trasferibili di 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. customerId è obbligatorio ed è l'identificatore univoco del cliente restituito quando si recupera l'account di un cliente del rivenditore. customerAuthToken è un token di trasferimento fornito dal cliente specifico per il tuo ID rivenditore. Una volta generato dal cliente, è valido per 30 giorni. Per ulteriori informazioni su come i clienti generano il token, consulta 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: il nome del dominio principale del cliente o il suo identificatore univoco.
  • AUTH_TOKEN: un token di trasferimento fornito dal cliente specifico per il tuo ID rivenditore. Una volta generato dal cliente, è valido per 30 giorni. Per ulteriori 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 ha parametri nel corpo della richiesta.

Una risposta positiva 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 licenze necessarie nell'ordine di trasferimento. Un cliente potrebbe avere 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 questi abbonamenti utilizzando l'operazione collettiva, trasferiscili tutti. Il trasferimento di ogni abbonamento uno alla volta comporta un errore. Inoltre, l'operazione batch trasferisce solo le iscrizioni con stato ACTIVE. Per ulteriori informazioni, consulta la pagina Trasferire un abbonamento.

Recuperare tutti gli abbonamenti dei rivenditori

Per recuperare tutti gli abbonamenti ordinati o trasferiti correttamente da un rivenditore, utilizza 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 specifica di risultati che il server deve 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. customerNamePrefix, pageToken e maxResults sono stringhe di query facoltative.

L'esempio seguente recupera tutti gli abbonamenti di un rivenditore appartenenti 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 Google Workspace varia in base al 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 i piani di pagamento con impegno annuale sia quelli flessibili possono essere soggetti a prove senza costi di 30 giorni. Durante la prova, puoi cambiare il piano di pagamento dell'abbonamento in piani di impegno flessibili o annuali tutte le volte che vuoi. Tuttavia, al termine della prova e all'attivazione del piano, 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, avvia 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 idoneità dei clienti, consulta il Centro assistenza per l'amministrazione.

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

  • Non puoi aggiornare un piano di impegno annuale.

  • Non tutti i piani funzionano con tutti i prodotti. Per ulteriori informazioni sui prodotti utilizzati da questi piani, consulta Prodotti e SKU.

Per aggiornare un piano di prova di 30 giorni o un abbonamento a un piano flessibile in 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:

  • CUSTOMER_ID: il nome del dominio principale del cliente o il suo identificatore univoco.
  • SUBSCRIPTION_ID: l'identificatore dell'abbonamento, unico per ogni cliente. Puoi recuperare questo valore utilizzando il metodo Recupera tutti gli abbonamenti del rivenditore.

L'esempio seguente aggiorna l'abbonamento con subscriptionId con un valore di 123. Il valore 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 riuscita 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 i posti di un abbonamento

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

Aggiornare i posti per l'abbonamento di un piano annuale

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

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

Sostituisci quanto segue:

  • CUSTOMER_ID: il nome del dominio principale del cliente o il suo identificatore univoco.
  • SUBSCRIPTION_ID: l'identificatore dell'abbonamento, unico per ogni cliente. Puoi recuperare questo valore utilizzando il metodo Recupera tutti gli abbonamenti del rivenditore.

L'esempio seguente aggiorna l'abbonamento con 123 subscriptionId. Il valore customerId è C0123456. Il corpo della richiesta varia a seconda del tipo di piano:

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

L'abbonamento a un piano con impegno annuale di 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 del 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 i posti per l'abbonamento di 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 è il totale delle licenze esistenti e delle nuove licenze. Si tratta del numero massimo di licenze dell'utente che l'account può eseguire il provisioning.

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

Una risposta riuscita restituisce un codice di stato HTTP 201 e le impostazioni della licenza dell'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:

  • CUSTOMER_ID: il nome del dominio principale del cliente o il suo identificatore univoco.
  • SUBSCRIPTION_ID: l'identificatore dell'abbonamento, unico per ogni cliente. Puoi recuperare questo valore utilizzando il metodo Recupera tutti gli abbonamenti del rivenditore.

Di seguito è riportato un esempio di corpo della 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 con impegno annuale, rinnova automaticamente il piano degli abbonamenti 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. Si tratta dell'impostazione predefinita per i piani con impegno annuale attivo (pagati annualmente).
  • 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. Si tratta dell'impostazione predefinita per i piani con impegno annuale attivo (pagati mensilmente).
  • RENEW_ON_PROPOSED_OFFER: al termine dell'intervallo del piano di impegno corrente, rinnova in base all'ultima proposta di rinnovo con numberOfSeats come numero di licenze utente attive correnti o impegno dell'offerta proposta, a seconda del valore più alto.
  • SWITCH_TO_PAY_AS_YOU_GO: al termine dell'intervallo di un piano di impegno annuale, passa a un piano flessibile.
  • CANCEL: al termine di un intervallo del piano con impegno annuale, l'abbonamento viene sospeso. Per informazioni su come revocare una sospensione, consulta il Centro assistenza per l'amministrazione.

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

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

Avviare il servizio a pagamento da un abbonamento di prova senza costi

Per passare immediatamente un abbonamento di prova senza costi di 30 giorni a un abbonamento a pagamento per il servizio, 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:

  • CUSTOMER_ID: il nome del dominio principale del cliente o il suo identificatore univoco.
  • SUBSCRIPTION_ID: l'identificatore dell'abbonamento, unico per ogni cliente. Puoi recuperare questo valore utilizzando il metodo Recupera tutti gli abbonamenti del rivenditore.

Nell'esempio seguente, C0123456 è customerId e il valore di subscriptionId è 123:

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

Questa operazione non ha parametri nel corpo della richiesta.

Una risposta riuscita restituisce un codice di stato HTTP 201 e le impostazioni 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": 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 a metà del periodo di validità e non puoi pianificare un downgrade utilizzando le impostazioni di rinnovo. Ti consigliamo di impostare le impostazioni di rinnovo per passare a FLEXIBLE e poi eseguire il downgrade al termine del periodo di rinnovo.

Per eseguire l'upgrade o il downgrade di un abbonamento, crea un nuovo abbonamento con il skuId a 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: il nome del dominio principale del cliente o il suo identificatore univoco.

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

Scopri di più su upgrade e downgrade nella pagina Prodotti e SKU.