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 è incentrata su come 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 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. 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"
}

Recupera 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&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 il 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 quando viene recuperato l'account di un cliente del rivenditore. customerAuthToken è un token di trasferimento fornito dal cliente specifico per il tuo ID rivenditore. Una volta generato, il token è 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: 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. Dopo che il cliente genera il token, questo è 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,trasferisci tutti gli abbonamenti. Il trasferimento degli abbonamenti uno alla volta genera un errore. Inoltre, l'operazione batch trasferisce solo gli abbonamenti con stato ACTIVE. Per saperne di più, 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 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 di impegno flessibili o annuali tutte le volte che vuoi. Al termine della prova e dopo l'attivazione del piano, l'aggiornamento del piano segue le stesse regole dei piani attivi di altri 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 amministratore.

  • 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 il valore subscriptionId pari a 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à dell'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 della licenza utente di un abbonamento con 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 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 di 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 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 di quelle nuove. 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 attivi (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 corrente, rinnova l'ultimo rinnovo proposto con numberOfSeats pari al numero di licenze utente attive correnti o all'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, passa al 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 amministratori.

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.

Il seguente esempio 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 pianificare 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 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 l'identificatore univoco del cliente.

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

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