Recuperare e aggiornare un abbonamento

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

Recuperare un abbonamento

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

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 l'identificatore univoco del cliente.
  • SUBSCRIPTION_ID: l'identificatore dell'abbonamento univoco per ogni cliente. Puoi recuperare questo valore utilizzando il metodo Recupera tutti gli abbonamenti dei rivenditori.

Questa operazione non ha parametri nel corpo della richiesta.

Una risposta riuscita restituisce un codice di stato HTTP 200 e le impostazioni dell'abbonamento. Nella seguente risposta di esempio, la proprietà isInTrial è false, ma non esiste 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 l'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 ha parametri nel corpo della richiesta.

Una risposta riuscita 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 Reseller.

Se non gestisci questo cliente, 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. customerId è obbligatorio ed è l'identificatore univoco del cliente restituito durante il recupero dell'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 saperne di più 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: il nome del dominio principale del cliente o l'identificatore univoco del cliente.
  • AUTH_TOKEN: Un token di trasferimento fornito dal tuo cliente specifico per il tuo ID rivenditore. Una volta generato dal cliente, è valido per 30 giorni. Per saperne di più 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 riuscita 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 posti necessari 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 batch, trasferiscili tutti. Il trasferimento di ogni abbonamento uno alla volta genera un errore. Inoltre, l'operazione batch trasferisce solo gli abbonamenti con stato ACTIVE. Per maggiori 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 in sola lettura OAuth. customerNamePrefix, pageToken e maxResults sono stringhe di query facoltative.

L'esempio seguente recupera tutti gli abbonamenti di un rivenditore che appartengono a 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 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 i piani di pagamento flessibili che quelli con impegno annuale possono essere prove senza costi di 30 giorni. Durante la prova, puoi modificare il piano di pagamento dell'abbonamento in piani flessibili o con impegno annuale tutte le volte che vuoi. Tuttavia, al termine della prova e all'attivazione del piano, l'aggiornamento del piano segue le stesse regole degli altri piani attivi degli abbonamenti. Per passare immediatamente da 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 qualificazione dei clienti, consulta il Centro assistenza per l'amministrazione.

  • Puoi aggiornare un piano flessibile a 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 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:

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

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 con piano flessibile di Google Workspace.

Aggiornare i posti per l'abbonamento con piano annuale

Per aggiornare le impostazioni delle licenze utente di un abbonamento al 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:

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

L'esempio seguente aggiorna l'abbonamento con 123 subscriptionId. Il 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 con piano flessibile

L'abbonamento a un piano flessibile di Google Workspace utilizza il corpo della richiesta per aggiornare le licenze utente. Il valore maximumNumberOfSeats è la somma delle licenze esistenti e delle nuove licenze. Questo è il numero massimo di licenze 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 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:

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

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 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 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. Questa è l'impostazione predefinita per i piani con impegno annuale attivo (pagamento mensile).
  • RENEW_ON_PROPOSED_OFFER: al termine dell'intervallo del piano di impegno attuale, rinnova l'ultima proposta di rinnovo con numberOfSeats come numero di licenze utente attive attuali o impegno dell'offerta proposta, a seconda di quale sia il valore più alto.
  • SWITCH_TO_PAY_AS_YOU_GO: al termine dell'intervallo di un piano di impegno annuale, cambia il piano di impegno annuale in un piano flessibile.
  • CANCEL: al termine di un intervallo del piano con impegno annuale, l'abbonamento viene sospeso. Per capire come ripristinare un account sospeso, consulta il Centro assistenza per l'amministrazione.

Una risposta riuscita 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"
}

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

Per passare immediatamente da 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:

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

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 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 e non puoi programmare un downgrade utilizzando le impostazioni di rinnovo. Ti consigliamo di impostare le impostazioni di rinnovo in modo da passare a FLEXIBLE e poi eseguire il downgrade dopo il periodo di rinnovo.

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

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

Per saperne di più su upgrade e downgrade, consulta la pagina Prodotti e SKU.